version 2.8
gqueue.h File Reference

Detailed Description

GQUEUE header file.

Definition in file gqueue.h.

Go to the source code of this file.

Data Structures

struct  gfxQueueASyncItem
 A queue item. More...
 
struct  gfxQueueASync
 A queue. More...
 
struct  GDataBuffer
 A Data Buffer Queue. More...
 

Functions

Initialisation functions

Initialise a queue.

Parameters
[in]pqueueA pointer to the queue
Note
Whilst queues are normally FIFO, a GFX queue also supports push and pop operations. A pop operation is the same as normal get from the queue but a push places the item at the head of the queue instead of the tail (as a put would).
Function Class:
Normal API, this function can be invoked by regular system threads.
void gfxQueueASyncInit (gfxQueueASync *pqueue)
 
void gfxQueueGSyncInit (gfxQueueGSync *pqueue)
 
void gfxQueueFSyncInit (gfxQueueFSync *pqueue)
 
Get() Functions

Get an item from the head of the queue (and remove it from the queue).

Returns
NULL if the timeout expires before an item is available
Parameters
[in]pqueueA pointer to the queue
[in]msThe maxmimum time to wait for an item. For ASync queues this parameter is not specified as TIME_IMMEDIATE is assumed.
Note
The routines ending in "I" are interrupt/system/iclass level routines.
Function Class:
Normal API, this function can be invoked by regular system threads.
gfxQueueASyncItemgfxQueueASyncGet (gfxQueueASync *pqueue)
 
gfxQueueASyncItemgfxQueueASyncGetI (gfxQueueASync *pqueue)
 
gfxQueueGSyncItemgfxQueueGSyncGet (gfxQueueGSync *pqueue, delaytime_t ms)
 
gfxQueueGSyncItemgfxQueueGSyncGetI (gfxQueueGSync *pqueue)
 
gfxQueueFSyncItem * gfxQueueFSyncGet (gfxQueueFSync *pqueue, delaytime_t ms)
 
Put() Functions

Put an item on the end of the queue.

Returns
none for ASync and GSync queues; For FSync queues - FALSE on timeout, otherwise TRUE
Parameters
[in]pqueueA pointer to the queue
[in]pitemA pointer to the queue item
[in]msThe maxmimum time to wait for an item to be removed from the queue (only for FSync queues)
Note
FSync: Use a delay time of TIME_IMMEDIATE if you don't want to wait until the item is removed from the queue. Note that even if the timeout occurs - the item remains in the queue.
The routines ending in "I" are interrupt/system/iclass level routines.
Function Class:
Normal API, this function can be invoked by regular system threads.
void gfxQueueASyncPut (gfxQueueASync *pqueue, gfxQueueASyncItem *pitem)
 
void gfxQueueASyncPutI (gfxQueueASync *pqueue, gfxQueueASyncItem *pitem)
 
void gfxQueueGSyncPut (gfxQueueGSync *pqueue, gfxQueueGSyncItem *pitem)
 
void gfxQueueGSyncPutI (gfxQueueGSync *pqueue, gfxQueueGSyncItem *pitem)
 
bool_t gfxQueueFSyncPut (gfxQueueFSync *pqueue, gfxQueueFSyncItem *pitem, delaytime_t ms)
 
Push() Functions

Push an item into the start of the queue.

Returns
none for ASync and GSync queues; For FSync queues - FALSE on timeout, otherwise TRUE
Parameters
[in]pqueueA pointer to the queue
[in]pitemA pointer to the queue item
[in]msThe maxmimum time to wait for an item to be popped (only for FSync queues)
Note
FSync: Use a delay time of TIME_IMMEDIATE if you don't want to wait until the item is removed from the queue. Note that even if the timeout occurs - the item remains in the queue.
The routines ending in "I" are interrupt/system/iclass level routines.
Function Class:
Normal API, this function can be invoked by regular system threads.
void gfxQueueASyncPush (gfxQueueASync *pqueue, gfxQueueASyncItem *pitem)
 
void gfxQueueASyncPushI (gfxQueueASync *pqueue, gfxQueueASyncItem *pitem)
 
void gfxQueueGSyncPush (gfxQueueGSync *pqueue, gfxQueueGSyncItem *pitem)
 
void gfxQueueGSyncPushI (gfxQueueGSync *pqueue, gfxQueueGSyncItem *pitem)
 
bool_t gfxQueueFSyncPush (gfxQueueFSync *pqueue, gfxQueueFSyncItem *pitem, delaytime_t ms)
 
Insert() Functions

Insert an item on the queue after the specified item.

Returns
none for ASync and GSync queues; For FSync queues - FALSE on timeout, otherwise TRUE
Parameters
[in]pqueueA pointer to the queue
[in]pitemA pointer to the queue item
[in]pafterA pointer to the queue item this new item must be inserted after. If NULL or pafter can't be found in the queue, it puts the new item at the end of the queue.
[in]msThe maxmimum time to wait for an item to be removed from the queue (only for FSync queues)
Note
FSync: Use a delay time of TIME_IMMEDIATE if you don't want to wait until the item is removed from the queue. Note that even if the timeout occurs - the item remains in the queue.
The routines ending in "I" are interrupt/system/iclass level routines.
Function Class:
Normal API, this function can be invoked by regular system threads.
void gfxQueueASyncInsert (gfxQueueASync *pqueue, gfxQueueASyncItem *pitem, gfxQueueASyncItem *pafter)
 
void gfxQueueASyncInsertI (gfxQueueASync *pqueue, gfxQueueASyncItem *pitem, gfxQueueASyncItem *pafter)
 
void gfxQueueGSyncInsert (gfxQueueGSync *pqueue, gfxQueueGSyncItem *pitem, gfxQueueASyncItem *pafter)
 
void gfxQueueGSyncInsertI (gfxQueueGSync *pqueue, gfxQueueGSyncItem *pitem, gfxQueueASyncItem *pafter)
 
bool_t gfxQueueFSyncInsert (gfxQueueFSync *pqueue, gfxQueueFSyncItem *pitem, gfxQueueASyncItem *pafter, delaytime_t ms)
 
Remove() Functions

Remove an item from the queue.

Note
Removes the specified item from the queue where-ever it is in the queue
Parameters
[in]pqueueA pointer to the queue
[in]pitemA pointer to the queue item
Note
If the item isn't in the queue the routine just returns.
If a process is waiting on the Put/Push operation for the item, that process will be signaled.
The routines ending in "I" are interrupt/system/iclass level routines.
Function Class:
Normal API, this function can be invoked by regular system threads.
void gfxQueueASyncRemove (gfxQueueASync *pqueue, gfxQueueASyncItem *pitem)
 
void gfxQueueASyncRemoveI (gfxQueueASync *pqueue, gfxQueueASyncItem *pitem)
 
void gfxQueueGSyncRemove (gfxQueueGSync *pqueue, gfxQueueGSyncItem *pitem)
 
void gfxQueueGSyncRemoveI (gfxQueueGSync *pqueue, gfxQueueGSyncItem *pitem)
 
void gfxQueueFSyncRemove (gfxQueueFSync *pqueue, gfxQueueFSyncItem *pitem)
 
IsInQueue() Functions

Is an item in the queue?

Returns
TRUE if the item is in the queue?
Parameters
[in]pqueueA pointer to the queue
[in]pitemA pointer to the queue item
Note
This operation may be expensive.
The routines ending in "I" are interrupt/system/iclass level routines.
Function Class:
Normal API, this function can be invoked by regular system threads.
bool_t gfxQueueASyncIsIn (gfxQueueASync *pqueue, const gfxQueueASyncItem *pitem)
 
bool_t gfxQueueASyncIsInI (gfxQueueASync *pqueue, const gfxQueueASyncItem *pitem)
 
bool_t gfxQueueGSyncIsIn (gfxQueueGSync *pqueue, const gfxQueueGSyncItem *pitem)
 
bool_t gfxQueueGSyncIsInI (gfxQueueGSync *pqueue, const gfxQueueGSyncItem *pitem)
 
bool_t gfxQueueFSyncIsIn (gfxQueueFSync *pqueue, const gfxQueueFSyncItem *pitem)
 
bool_t gfxQueueFSyncIsInI (gfxQueueFSync *pqueue, const gfxQueueFSyncItem *pitem)
 
BufferAlloc() Functions

Allocate some buffers and put them on the free list

Returns
TRUE is it succeeded. FALSE on allocation failure.
Parameters
[in]numThe number of buffers to allocate
[in]sizeThe size (in bytes) of each buffer
Function Class:
Normal API, this function can be invoked by regular system threads.
bool_t gfxBufferAlloc (unsigned num, size_t size)
 
BufferIsAvailable() Functions

Is there one or more buffers currently available on the free list

Returns
TRUE if there are buffers in the free list
Function Class:
Normal API, this function can be invoked by regular system threads.
bool_t gfxBufferIsAvailable (void)
 
BufferGet() Functions

Get a buffer from the free list

Returns
A GDataBuffer pointer or NULL if the timeout is exceeded
Parameters
[in]msThe maximum amount of time in milliseconds to wait for a buffer if one is not available.
Function Class:
Normal API, this function can be invoked by regular system threads.
GDataBuffergfxBufferGet (delaytime_t ms)
 
GDataBuffergfxBufferGetI (void)
 
BufferRelease() Functions

Release a buffer back to the free list

Parameters
[in]pdThe buffer to put (back) on the free-list.
Note
This call should be used to return any buffers that were taken from the free-list once they have been finished with. It can also be used to put new buffers onto the free-list. Just make sure the "size" field of the GDataBuffer structure has been filled in first.
Function Class:
Normal API, this function can be invoked by regular system threads.
void gfxBufferRelease (GDataBuffer *pd)
 
void gfxBufferReleaseI (GDataBuffer *pd)
 

Macros

Pop() Functions

Pop an item from the head of the queue (and remove it from the queue).

This is exactly the same as the Get operation above.

Function Class:
Normal API, this function can be invoked by regular system threads.
#define gfxQueueASyncPop(pqueue)   gfxQueueASyncGet(pqueue)
 
#define gfxQueueASyncPopI(pqueue)   gfxQueueASyncGetI(pqueue)
 
#define gfxQueueGSyncPop(pqueue, ms)   gfxQueueGSyncGet(pqueue, ms)
 
#define gfxQueueFSyncPop(pqueue, ms)   gfxQueueFSyncGet(pqueue, ms)
 
isEmpty() Functions

Is the queue empty?

Returns
TRUE if the queue is empty
Parameters
[in]pqueueA pointer to the queue
Note
The routines ending in "I" are interrupt/system/iclass level routines.
Function Class:
Normal API, this function can be invoked by regular system threads.
#define gfxQueueASyncIsEmpty(pqueue)   ((pqueue)->head == 0)
 
#define gfxQueueASyncIsEmptyI(pqueue)   ((pqueue)->head == 0)
 
#define gfxQueueGSyncIsEmpty(pqueue)   ((pqueue)->head == 0)
 
#define gfxQueueGSyncIsEmptyI(pqueue)   ((pqueue)->head == 0)
 
#define gfxQueueFSyncIsEmpty(pqueue)   ((pqueue)->head == 0)
 
#define gfxQueueFSyncIsEmptyI(pqueue)   ((pqueue)->head == 0)
 
Peek() Functions

Get the first item from the head of the queue but do not remove it from the queue.

Returns
NULL if no item is available.
Parameters
[in]pqueueA pointer to the queue
Note
This call does not block.
This can be used as the first call to iterate all the elements in the queue.
As that item is still on the queue, it should be treated as read-only. It could also be removed from the queue at any time by another thread (thereby altering the queue item).
The routines ending in "I" are interrupt/system/iclass level routines.
Function Class:
Normal API, this function can be invoked by regular system threads.
#define gfxQueueASyncPeek(pqueue)   ((const gfxQueueASyncItem *)((pqueue)->head))
 
#define gfxQueueASyncPeekI(pqueue)   ((const gfxQueueASyncItem *)((pqueue)->head))
 
#define gfxQueueGSyncPeek(pqueue)   ((const gfxQueueGSyncItem *)((pqueue)->head))
 
#define gfxQueueGSyncPeekI(pqueue)   ((const gfxQueueGSyncItem *)((pqueue)->head))
 
#define gfxQueueFSyncPeek(pqueue)   ((const gfxQueueFSyncItem *)((pqueue)->head))
 
#define gfxQueueFSyncPeekI(pqueue)   ((const gfxQueueFSyncItem *)((pqueue)->head))
 
Next() Functions

Get the next item in the queue (but do not remove it from the queue).

Returns
NULL if no item is available.
Parameters
[in]pitemThe previous item in the queue
Note
This call does not block.
This can be used as subsequent calls to iterate all the elements in the queue.
As that item is still on the queue, it should be treated as read-only. It could also be removed from the queue at any time by another thread (thereby altering the queue item).
The routines ending in "I" are interrupt/system/iclass level routines.
Function Class:
Normal API, this function can be invoked by regular system threads.
#define gfxQueueASyncNext(pitem)   ((const gfxQueueASyncItem *)((pitem)->next))
 
#define gfxQueueASyncNextI(pitem)   ((const gfxQueueASyncItem *)((pitem)->next))
 
#define gfxQueueGSyncNext(pitem)   ((const gfxQueueGSyncItem *)((pitem)->next))
 
#define gfxQueueGSyncNextI(pitem)   ((const gfxQueueGSyncItem *)((pitem)->next))
 
#define gfxQueueFSyncNext(pitem)   ((const gfxQueueFSyncItem *)((pitem)->next))
 
#define gfxQueueFSyncNextI(pitem)   ((const gfxQueueFSyncItem *)((pitem)->next))
 

Typedefs

typedef struct GDataBuffer GDataBuffer
 A Data Buffer Queue. More...
 
typedef struct gfxQueueASyncItem gfxQueueASyncItem
 A queue item. More...
 
typedef struct gfxQueueASync gfxQueueASync
 A queue. More...
 

Deinitialisation functions

De-Initialise a queue.

Parameters
[in]pqueueA pointer to the queue
Function Class:
Normal API, this function can be invoked by regular system threads.
#define gfxQueueASyncDeinit(pqueue)
 
void gfxQueueGSyncDeinit (gfxQueueGSync *pqueue)
 
void gfxQueueFSyncDeinit (gfxQueueFSync *pqueue)