diff --git a/include/gevent/gevent.h b/include/gevent/gevent.h index 6acfac01..ad386746 100644 --- a/include/gevent/gevent.h +++ b/include/gevent/gevent.h @@ -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 */ /** @} */ + diff --git a/src/gevent/gevent.c b/src/gevent/gevent.c index 8aa40b58..f3d909f0 100644 --- a/src/gevent/gevent.c +++ b/src/gevent/gevent.c @@ -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);