diff options
| -rw-r--r-- | include/gevent/gevent.h | 130 | ||||
| -rw-r--r-- | src/gevent/gevent.c | 94 |
2 files changed, 85 insertions, 139 deletions
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);
|