GEVENT doxygen
Joel Bodenmann
parent
f15208e09a
commit
7a6bf59b2b
|
|
@ -126,79 +126,118 @@ extern "C" {
|
|||
|
||||
/*---------- Listener Functions --------------------------------------------*/
|
||||
|
||||
/* Initialise a Listener.
|
||||
/**
|
||||
* @brief Create a Listener
|
||||
* @details If insufficient resources are available it will either assert or return NULL
|
||||
* depending on the value of GEVENT_ASSERT_NO_RESOURCE.
|
||||
*
|
||||
* @param[in] pl A listener
|
||||
*/
|
||||
void geventListenerInit(GListener *pl);
|
||||
|
||||
/* Attach a source to a listener.
|
||||
* Flags are interpreted by the source when generating events for each listener.
|
||||
* If this source is already assigned to the listener it will update the flags.
|
||||
* If insufficient resources are available it will either assert or return FALSE
|
||||
* depending on the value of GEVENT_ASSERT_NO_RESOURCE.
|
||||
/**
|
||||
* @brief Attach a source to a listener
|
||||
* @details Flags are interpreted by the source when generating events for each listener.
|
||||
* If this source is already assigned to the listener it will update the flags.
|
||||
* If insufficient resources are available it will either assert or return FALSE
|
||||
* depending on the value of GEVENT_ASSERT_NO_RESOURCE.
|
||||
*
|
||||
* @param[in] pl The listener
|
||||
* @param[in] gsh The source which has to be attached to the listener
|
||||
* @param[in] flags The flags
|
||||
*
|
||||
* @return TRUE if succeeded, FALSE otherwise
|
||||
*/
|
||||
bool_t geventAttachSource(GListener *pl, GSourceHandle gsh, unsigned flags);
|
||||
|
||||
/* Detach a source from a listener
|
||||
* If gsh is NULL detach all sources from this listener and if there is still
|
||||
* a thread waiting for events on this listener, it is sent the exit event.
|
||||
/**
|
||||
* @brief Detach a source from a listener
|
||||
* @details If gsh is NULL detach all sources from this listener and if there is still
|
||||
* a thread waiting for events on this listener, it is sent the exit event.
|
||||
*
|
||||
* @param[in] pl The listener
|
||||
* @param[in] gsh The source
|
||||
*/
|
||||
void geventDetachSource(GListener *pl, GSourceHandle gsh);
|
||||
|
||||
/* Wait for an event on a listener from an assigned source.
|
||||
* The type of the event should be checked (pevent->type) and then pevent should be typecast to the
|
||||
* actual event type if it needs to be processed.
|
||||
* timeout specifies the time to wait in system ticks.
|
||||
* TIME_INFINITE means no timeout - wait forever for an event.
|
||||
* TIME_IMMEDIATE means return immediately
|
||||
* Returns NULL on timeout or if a callback function is already registered.
|
||||
* Note: The GEvent buffer is staticly allocated within the GListener so the event does not
|
||||
/**
|
||||
* @brief Wait for an event on a listener from an assigned source.
|
||||
* @details The type of the event should be checked (pevent->type) and then pevent should
|
||||
* be typecast to the actual event type if it needs to be processed.
|
||||
* timeout specifies the time to wait in system ticks.
|
||||
* TIME_INFINITE means no timeout - wait forever for an event.
|
||||
* TIME_IMMEDIATE means return immediately
|
||||
* @note The GEvent buffer is staticly allocated within the GListener so the event does not
|
||||
* need to be dynamicly freed however it will get overwritten by the next call to
|
||||
* this routine.
|
||||
*
|
||||
* @param[in] pl The listener
|
||||
* @param[in] timeout The timeout
|
||||
*
|
||||
* @return NULL on timeout
|
||||
*/
|
||||
GEvent *geventEventWait(GListener *pl, systime_t timeout);
|
||||
|
||||
/* Register a callback for an event on a listener from an assigned source.
|
||||
* The type of the event should be checked (pevent->type) and then pevent should be typecast to the
|
||||
* actual event type if it needs to be processed.
|
||||
* Note: The GEvent buffer is valid only during the time of the callback. The callback MUST NOT save
|
||||
* a pointer to the buffer for use outside the callback.
|
||||
* Note: An existing callback function is de-registered by passing a NULL for 'fn'. Any existing
|
||||
* callback function is replaced. Any thread currently waiting using geventEventWait will be sent the exit event.
|
||||
* Note: Callbacks occur in a thread context but stack space must be kept to a minumum and
|
||||
* the callback must process quickly as all other events are performed on a single thread.
|
||||
* Note: In the callback function you should never call ANY event functions using your own GListener handle
|
||||
* as it WILL create a deadlock and lock the system up.
|
||||
* Note: Applications should not use this call - geventEventWait() is the preferred mechanism for an
|
||||
* application. This call is provided for GUI objects that may not have their own thread.
|
||||
/* @brief Register a callback for an event on a listener from an assigned source.
|
||||
* @details The type of the event should be checked (pevent->type) and then pevent should be typecast to the
|
||||
* actual event type if it needs to be processed.
|
||||
*
|
||||
* @params[in] pl The Listener
|
||||
* @params[in] fn The function to call back
|
||||
* @params[in] param A parameter to pass the callback function
|
||||
*
|
||||
* @note The GEvent buffer is valid only during the time of the callback. The callback MUST NOT save
|
||||
* a pointer to the buffer for use outside the callback.
|
||||
* @note An existing callback function is de-registered by passing a NULL for 'fn'. Any existing
|
||||
* callback function is replaced. Any thread currently waiting using geventEventWait will be sent the exit event.
|
||||
* @note Callbacks occur in a thread context but stack space must be kept to a minumum and
|
||||
* the callback must process quickly as all other events are performed on a single thread.
|
||||
* @note In the callback function you should never call ANY event functions using your own GListener handle
|
||||
* as it WILL create a deadlock and lock the system up.
|
||||
* @note Applications should not use this call - geventEventWait() is the preferred mechanism for an
|
||||
* application. This call is provided for GUI objects that may not have their own thread.
|
||||
*/
|
||||
void geventRegisterCallback(GListener *pl, GEventCallbackFn fn, void *param);
|
||||
|
||||
/*---------- Source Functions --------------------------------------------*/
|
||||
|
||||
/* Sources create their own GSourceHandles which are pointers to any arbitrary structure
|
||||
typecast to a GSourceHandle.
|
||||
*/
|
||||
|
||||
/* Called by a source with a possible event to get a listener record.
|
||||
* 'lastlr' should be NULL on the first call and thereafter the result of the previous call.
|
||||
* It will return NULL when there are no more listeners for this source.
|
||||
/**
|
||||
* @brief Called by a source with a possible event to get a listener record.
|
||||
* @details @p lastlr should be NULL on the first call and thereafter the result of the previous call.
|
||||
*
|
||||
* @param[in] gsh The source handler
|
||||
* @param[in] lastlr The source listener
|
||||
*
|
||||
* @return NULL when there are no more listeners for this source
|
||||
*/
|
||||
GSourceListener *geventGetSourceListener(GSourceHandle gsh, GSourceListener *lastlr);
|
||||
|
||||
/* Get the event buffer from the GSourceListener.
|
||||
* Returns NULL if the listener is not currently listening.
|
||||
* A NULL return allows the source to record (perhaps in glr->scrflags) that the listener has missed events.
|
||||
* This can then be notified as part of the next event for the listener.
|
||||
* The buffer can only be accessed untill the next call to geventGetSourceListener or geventSendEvent
|
||||
/**
|
||||
* @brief Get the event buffer from the GSourceListener.
|
||||
* @details A NULL return allows the source to record (perhaps in glr->scrflags) that the listener
|
||||
* has missed events. This can then be notified as part of the next event for the listener.
|
||||
* The buffer can only be accessed untill the next call to geventGetSourceListener
|
||||
* or geventSendEvent
|
||||
*
|
||||
* @param[in] psl The source listener
|
||||
*
|
||||
* @return NULL if the listener is not currently listening.
|
||||
*/
|
||||
GEvent *geventGetEventBuffer(GSourceListener *psl);
|
||||
|
||||
/* Called by a source to indicate the listener's event buffer has been filled.
|
||||
* After calling this function the source must not reference in fields in the GSourceListener or the event buffer.
|
||||
/**
|
||||
* @brief Called by a source to indicate the listener's event buffer has been filled.
|
||||
* @details After calling this function the source must not reference in fields in the GSourceListener or the event buffer.
|
||||
*
|
||||
* @param[in] psl The source listener
|
||||
*/
|
||||
void geventSendEvent(GSourceListener *psl);
|
||||
|
||||
/* Detach any listener that has this source attached */
|
||||
/**
|
||||
* @brief Detach any listener that has this source attached
|
||||
*
|
||||
* @param[in] gsh The source handle
|
||||
*/
|
||||
void geventDetachSourceListeners(GSourceHandle gsh);
|
||||
|
||||
#ifdef __cplusplus
|
||||
|
|
@ -209,3 +248,4 @@ void geventDetachSourceListeners(GSourceHandle gsh);
|
|||
|
||||
#endif /* _GEVENT_H */
|
||||
/** @} */
|
||||
|
||||
|
|
|
|||
|
|
@ -61,13 +61,6 @@ static void deleteAssignments(GListener *pl, GSourceHandle gsh) {
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Create a Listener
|
||||
* @details If insufficient resources are available it will either assert or return NULL
|
||||
* depending on the value of GEVENT_ASSERT_NO_RESOURCE.
|
||||
*
|
||||
* @param[in] pl A listener
|
||||
*/
|
||||
void geventListenerInit(GListener *pl) {
|
||||
chSemInit(&pl->waitqueue, 0); // Next wait'er will block
|
||||
chBSemInit(&pl->eventlock, FALSE); // Only one thread at a time looking at the event buffer
|
||||
|
|
@ -75,19 +68,6 @@ void geventListenerInit(GListener *pl) {
|
|||
pl->event.type = GEVENT_NULL; // Always safety
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Attach a source to a listener
|
||||
* @details Flags are interpreted by the source when generating events for each listener.
|
||||
* If this source is already assigned to the listener it will update the flags.
|
||||
* If insufficient resources are available it will either assert or return FALSE
|
||||
* depending on the value of GEVENT_ASSERT_NO_RESOURCE.
|
||||
*
|
||||
* @param[in] pl The listener
|
||||
* @param[in] gsh The source which has to be attached to the listener
|
||||
* @param[in] flags The flags
|
||||
*
|
||||
* @return TRUE if succeeded, FALSE otherwise
|
||||
*/
|
||||
bool_t geventAttachSource(GListener *pl, GSourceHandle gsh, unsigned flags) {
|
||||
GSourceListener *psl, *pslfree;
|
||||
|
||||
|
|
@ -127,14 +107,6 @@ bool_t geventAttachSource(GListener *pl, GSourceHandle gsh, unsigned flags) {
|
|||
return pslfree != 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Detach a source from a listener
|
||||
* @details If gsh is NULL detach all sources from this listener and if there is still
|
||||
* a thread waiting for events on this listener, it is sent the exit event.
|
||||
*
|
||||
* @param[in] pl The listener
|
||||
* @param[in] gsh The source
|
||||
*/
|
||||
void geventDetachSource(GListener *pl, GSourceHandle gsh) {
|
||||
if (pl && gsh) {
|
||||
chMtxLock(&geventMutex);
|
||||
|
|
@ -149,47 +121,12 @@ void geventDetachSource(GListener *pl, GSourceHandle gsh) {
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Wait for an event on a listener from an assigned source.
|
||||
* @details The type of the event should be checked (pevent->type) and then pevent should
|
||||
* be typecast to the actual event type if it needs to be processed.
|
||||
* timeout specifies the time to wait in system ticks.
|
||||
* TIME_INFINITE means no timeout - wait forever for an event.
|
||||
* TIME_IMMEDIATE means return immediately
|
||||
* @note The GEvent buffer is staticly allocated within the GListener so the event does not
|
||||
* need to be dynamicly freed however it will get overwritten by the next call to
|
||||
* this routine.
|
||||
*
|
||||
* @param[in] pl The listener
|
||||
* @param[in] timeout The timeout
|
||||
*
|
||||
* @return NULL on timeout
|
||||
*/
|
||||
GEvent *geventEventWait(GListener *pl, systime_t timeout) {
|
||||
if (pl->callback || chSemGetCounterI(&pl->waitqueue) < 0)
|
||||
return 0;
|
||||
return chSemWaitTimeout(&pl->waitqueue, timeout) == RDY_OK ? &pl->event : 0;
|
||||
}
|
||||
|
||||
/* @brief Register a callback for an event on a listener from an assigned source.
|
||||
* @details The type of the event should be checked (pevent->type) and then pevent should be typecast to the
|
||||
* actual event type if it needs to be processed.
|
||||
*
|
||||
* @params[in] pl The Listener
|
||||
* @params[in] fn The function to call back
|
||||
* @params[in] param A parameter to pass the callback function
|
||||
*
|
||||
* @note The GEvent buffer is valid only during the time of the callback. The callback MUST NOT save
|
||||
* a pointer to the buffer for use outside the callback.
|
||||
* @note An existing callback function is de-registered by passing a NULL for 'fn'. Any existing
|
||||
* callback function is replaced. Any thread currently waiting using geventEventWait will be sent the exit event.
|
||||
* @note Callbacks occur in a thread context but stack space must be kept to a minumum and
|
||||
* the callback must process quickly as all other events are performed on a single thread.
|
||||
* @note In the callback function you should never call ANY event functions using your own GListener handle
|
||||
* as it WILL create a deadlock and lock the system up.
|
||||
* @note Applications should not use this call - geventEventWait() is the preferred mechanism for an
|
||||
* application. This call is provided for GUI objects that may not have their own thread.
|
||||
*/
|
||||
void geventRegisterCallback(GListener *pl, GEventCallbackFn fn, void *param) {
|
||||
if (pl) {
|
||||
chMtxLock(&geventMutex);
|
||||
|
|
@ -205,15 +142,6 @@ void geventRegisterCallback(GListener *pl, GEventCallbackFn fn, void *param) {
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Called by a source with a possible event to get a listener record.
|
||||
* @details @p lastlr should be NULL on the first call and thereafter the result of the previous call.
|
||||
*
|
||||
* @param[in] gsh The source handler
|
||||
* @param[in] lastlr The source listener
|
||||
*
|
||||
* @return NULL when there are no more listeners for this source
|
||||
*/
|
||||
GSourceListener *geventGetSourceListener(GSourceHandle gsh, GSourceListener *lastlr) {
|
||||
GSourceListener *psl;
|
||||
|
||||
|
|
@ -239,28 +167,11 @@ GSourceListener *geventGetSourceListener(GSourceHandle gsh, GSourceListener *las
|
|||
return 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Get the event buffer from the GSourceListener.
|
||||
* @details A NULL return allows the source to record (perhaps in glr->scrflags) that the listener
|
||||
* has missed events. This can then be notified as part of the next event for the listener.
|
||||
* The buffer can only be accessed untill the next call to geventGetSourceListener
|
||||
* or geventSendEvent
|
||||
*
|
||||
* @param[in] psl The source listener
|
||||
*
|
||||
* @return NULL if the listener is not currently listening.
|
||||
*/
|
||||
GEvent *geventGetEventBuffer(GSourceListener *psl) {
|
||||
// We already know we have the event lock
|
||||
return &psl->pListener->callback || chSemGetCounterI(&psl->pListener->waitqueue) < 0 ? &psl->pListener->event : 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Called by a source to indicate the listener's event buffer has been filled.
|
||||
* @details After calling this function the source must not reference in fields in the GSourceListener or the event buffer.
|
||||
*
|
||||
* @param[in] psl The source listener
|
||||
*/
|
||||
void geventSendEvent(GSourceListener *psl) {
|
||||
chMtxLock(&geventMutex);
|
||||
if (psl->pListener->callback) { // This test needs to be taken inside the mutex
|
||||
|
|
@ -276,11 +187,6 @@ void geventSendEvent(GSourceListener *psl) {
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Detach any listener that has this source attached
|
||||
*
|
||||
* @param[in] gsh The source handle
|
||||
*/
|
||||
void geventDetachSourceListeners(GSourceHandle gsh) {
|
||||
chMtxLock(&geventMutex);
|
||||
deleteAssignments(0, gsh);
|
||||
|
|
|
|||
Loading…
Reference in New Issue