version 2.8
GEVENT

Detailed Description

Module to build a complete many-to-many event system.

GEVENT provides a simple to use but yet powerful event system.

Precondition
GFX_USE_GEVENT must be set to TRUE in your gfxconf.h

Functions

void geventListenerInit (GListener *pl)
 Create a Listener. More...
 
bool_t geventAttachSource (GListener *pl, GSourceHandle gsh, uint32_t flags)
 Attach a source to a listener. More...
 
void geventDetachSource (GListener *pl, GSourceHandle gsh)
 Detach a source from a listener. More...
 
GEvent * geventEventWait (GListener *pl, delaytime_t timeout)
 Wait for an event on a listener from an assigned source. More...
 
void geventEventComplete (GListener *pl)
 Release the GEvent buffer associated with a listener. More...
 
GSourceListener * geventGetSourceListener (GSourceHandle gsh, GSourceListener *lastlr)
 Called by a source with a possible event to get a listener record. More...
 
GEvent * geventGetEventBuffer (GSourceListener *psl)
 Get the event buffer from the GSourceListener. More...
 
void geventSendEvent (GSourceListener *psl)
 Called by a source to indicate the listener's event buffer has been filled. More...
 
void geventDetachSourceListeners (GSourceHandle gsh)
 Detach any listener that has this source attached. More...
 

GEVENT Functionality to be included

#define GEVENT_ASSERT_NO_RESOURCE   FALSE
 Should routines assert() if they run out of resources. More...
 

GEVENT Optional Sizing Parameters

#define GEVENT_MAXIMUM_SIZE   32
 Defines the maximum size of an event status variable. More...
 
#define GEVENT_MAX_SOURCE_LISTENERS   32
 Defines the maximum Source/Listener pairs in the system. More...
 

Function Documentation

bool_t geventAttachSource ( GListener *  pl,
GSourceHandle  gsh,
uint32_t  flags 
)

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.

Parameters
[in]plThe listener
[in]gshThe source which has to be attached to the listener
[in]flagsThe flags
Returns
TRUE if succeeded, FALSE otherwise

Definition at line 71 of file gevent.c.

References FALSE, GEVENT_MAX_SOURCE_LISTENERS, gfxMutexEnter(), gfxMutexExit(), and TRUE.

void geventDetachSource ( GListener *  pl,
GSourceHandle  gsh 
)

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.

Parameters
[in]plThe listener
[in]gshThe source

Definition at line 108 of file gevent.c.

References gfxMutexEnter(), and gfxMutexExit().

void geventDetachSourceListeners ( GSourceHandle  gsh)

Detach any listener that has this source attached.

Parameters
[in]gshThe source handle

Definition at line 220 of file gevent.c.

References gfxMutexEnter(), and gfxMutexExit().

void geventEventComplete ( GListener *  pl)

Release the GEvent buffer associated with a listener.

The GEvent returned by geventEventWait() is released.

Note
The GEvent pointer returned by geventEventWait() is released when geventEventWait() is called again or when this function is called. The GEvent object MUST NOT be used after this function is called.
Parameters
[in]plThe listener

Definition at line 146 of file gevent.c.

References gfxMutexEnter(), and gfxMutexExit().

GEvent* geventEventWait ( GListener *  pl,
delaytime_t  timeout 
)

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. TIME_INFINITE means no timeout - wait forever for an event. TIME_IMMEDIATE means return immediately

Note
The returned GEvent is released when this routine is called again or when optionally geventEventComplete() is called. Calling geventEventComplete() allows the GEvent object to be reused earlier which can reduce missed events. The GEvent object MUST NOT be used after this function is called (and is blocked waiting for the next event) or after geventEventComplete() is called. The one listener object should not be waited on using more than one thread simultanously because of the implicit geventEventComplete() that occurs when this function is called.
Parameters
[in]plThe listener
[in]timeoutThe timeout in milliseconds
Returns
NULL on timeout

Definition at line 118 of file gevent.c.

References gfxSemWait().

GEvent* geventGetEventBuffer ( GSourceListener *  psl)

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. 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()

Parameters
[in]pslThe source listener
Returns
NULL if the event buffer for this listener is currently in use.

Definition at line 187 of file gevent.c.

References gfxMutexEnter(), and gfxMutexExit().

GSourceListener* geventGetSourceListener ( GSourceHandle  gsh,
GSourceListener *  lastlr 
)

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.

Parameters
[in]gshThe source handler
[in]lastlrThe source listener
Returns
NULL when there are no more listeners for this source

Definition at line 163 of file gevent.c.

References GEVENT_MAX_SOURCE_LISTENERS, gfxMutexEnter(), and gfxMutexExit().

void geventListenerInit ( GListener *  pl)

Create a Listener.

If insufficient resources are available it will either assert or return NULL depending on the value of GEVENT_ASSERT_NO_RESOURCE.

Parameters
[in]plA listener

Definition at line 64 of file gevent.c.

References gfxSemInit().

void geventSendEvent ( 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.

Parameters
[in]pslThe source listener

Definition at line 200 of file gevent.c.

References gfxMutexEnter(), gfxMutexExit(), and gfxSemSignal().

Macro Definition Documentation

#define GEVENT_ASSERT_NO_RESOURCE   FALSE

Should routines assert() if they run out of resources.

Defaults to FALSE.

If FALSE the application must be prepared to handle these failures.

Definition at line 30 of file gevent_options.h.

#define GEVENT_MAX_SOURCE_LISTENERS   32

Defines the maximum Source/Listener pairs in the system.

Defaults to 32

Definition at line 50 of file gevent_options.h.

Referenced by geventAttachSource(), and geventGetSourceListener().

#define GEVENT_MAXIMUM_SIZE   32

Defines the maximum size of an event status variable.

Defaults to 32 bytes

Definition at line 43 of file gevent_options.h.