uGFX
/
ugfx
2
0
Fork 0
Code Issues 2 Pull Requests Projects Releases Wiki Activity

GEVENT doxygen

remotes/origin_old/ugfx_release_2.6
Joel Bodenmann 2012-11-19 21:43:22 +01:00
parent 19d45eaeda
commit cafb454745
1 changed files with 70 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

104
src/gevent.c
View File

@ -40,14 +40,14 @@
#define GEVENT_ASSERT(x) #define GEVENT_ASSERT(x)
#endif #endif
// This mutex protects access to our tables /* This mutex protects access to our tables */
static MUTEX_DECL(geventMutex); static MUTEX_DECL(geventMutex);
// Our table of listener/source pairs /* Our table of listener/source pairs */
static GSourceListener Assignments[MAX_SOURCE_LISTENERS]; static GSourceListener Assignments[MAX_SOURCE_LISTENERS];
// Loop through the assignment table deleting this listener/source pair. /* Loop through the assignment table deleting this listener/source pair. */
// Null is treated as a wildcard. /* Null is treated as a wildcard. */
static void deleteAssignments(GListener *pl, GSourceHandle gsh) { static void deleteAssignments(GListener *pl, GSourceHandle gsh) {
GSourceListener *psl; GSourceListener *psl;
@ -64,9 +64,12 @@ static void deleteAssignments(GListener *pl, GSourceHandle gsh) {
} }
} }
/* Create a Listener. /**
* If insufficient resources are available it will either assert or return NULL * @brief Create a Listener
* depending on the value of GEVENT_ASSERT_NO_RESOURCE. * @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) { void geventListenerInit(GListener *pl) {
chSemInit(&pl->waitqueue, 0); // Next wait'er will block chSemInit(&pl->waitqueue, 0); // Next wait'er will block
@ -74,11 +77,18 @@ void geventListenerInit(GListener *pl) {
pl->event.type = GEVENT_NULL; // Always safety pl->event.type = GEVENT_NULL; // Always safety
} }
/* Attach a source to a listener. /**
* Flags are interpreted by the source when generating events for each listener. * @brief Attach a source to a listener
* If this source is already assigned to the listener it will update the flags. * @details Flags are interpreted by the source when generating events for each listener.
* If insufficient resources are available it will either assert or return FALSE * If this source is already assigned to the listener it will update the flags.
* depending on the value of GEVENT_ASSERT_NO_RESOURCE. * 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) { bool_t geventAttachSource(GListener *pl, GSourceHandle gsh, unsigned flags) {
GSourceListener *psl, *pslfree; GSourceListener *psl, *pslfree;
@ -119,9 +129,13 @@ bool_t geventAttachSource(GListener *pl, GSourceHandle gsh, unsigned flags) {
return pslfree != 0; return pslfree != 0;
} }
/* Detach a source from a listener /**
* If gsh is NULL detach all sources from this listener and if there is still * @brief Detach a source from a listener
* a thread waiting for events on this listener, it is sent the exit event. * @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) { void geventDetachSource(GListener *pl, GSourceHandle gsh) {
if (pl && gsh) { if (pl && gsh) {
@ -137,24 +151,34 @@ 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 * @brief Wait for an event on a listener from an assigned source.
* actual event type if it needs to be processed. * @details The type of the event should be checked (pevent->type) and then pevent should
* timeout specifies the time to wait in system ticks. * be typecast to the actual event type if it needs to be processed.
* TIME_INFINITE means no timeout - wait forever for an event. * timeout specifies the time to wait in system ticks.
* TIME_IMMEDIATE means return immediately * TIME_INFINITE means no timeout - wait forever for an event.
* Returns NULL on timeout. * TIME_IMMEDIATE means return immediately
* Note: The GEvent buffer is staticly allocated within the GListener so the event does not * @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 * need to be dynamicly freed however it will get overwritten by the next call to
* this routine. * this routine.
*
* @param[in] pl The listener
* @param[in] timeout The timeout
*
* @return NULL on timeout
*/ */
GEvent *geventEventWait(GListener *pl, systime_t timeout) { GEvent *geventEventWait(GListener *pl, systime_t timeout) {
return chSemWaitTimeout(&pl->waitqueue, timeout) == RDY_OK ? &pl->event : 0; return chSemWaitTimeout(&pl->waitqueue, timeout) == RDY_OK ? &pl->event : 0;
} }
/* 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. * @brief Called by a source with a possible event to get a listener record.
* It will return NULL when there are no more listeners for this source. * @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 *geventGetSourceListener(GSourceHandle gsh, GSourceListener *lastlr) {
GSourceListener *psl; GSourceListener *psl;
@ -181,19 +205,27 @@ GSourceListener *geventGetSourceListener(GSourceHandle gsh, GSourceListener *las
return 0; return 0;
} }
/* Get the event buffer from the GSourceListener. /**
* Returns NULL if the listener is not currently listening. * @brief Get the event buffer from the GSourceListener.
* A NULL return allows the source to record (perhaps in glr->scrflags) that the listener has missed events. * @details A NULL return allows the source to record (perhaps in glr->scrflags) that the listener
* This can then be notified as part of the next event for 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 * 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) { GEvent *geventGetEventBuffer(GSourceListener *psl) {
// We already know we have the event lock // We already know we have the event lock
return chSemGetCounterI(&psl->pListener->waitqueue) < 0 ? &psl->pListener->event : 0; return chSemGetCounterI(&psl->pListener->waitqueue) < 0 ? &psl->pListener->event : 0;
} }
/* 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) { void geventSendEvent(GSourceListener *psl) {
chMtxLock(&geventMutex); chMtxLock(&geventMutex);
@ -203,7 +235,11 @@ void geventSendEvent(GSourceListener *psl) {
chMtxUnlock(); chMtxUnlock();
} }
/* 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) { void geventDetachSourceListeners(GSourceHandle gsh) {
chMtxLock(&geventMutex); chMtxLock(&geventMutex);
deleteAssignments(0, gsh); deleteAssignments(0, gsh);