Detailed Description

GQUEUE header file.

Definition in file gqueue.h.

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] pqueue A 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]	pqueue	A pointer to the queue
[in]	ms	The maxmimum time to wait for an item. For ASync queues this parameter is not specified as gDelayNone 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.

gfxQueueASyncItem * gfxQueueASyncGet (gfxQueueASync *pqueue)

gfxQueueASyncItem * gfxQueueASyncGetI (gfxQueueASync *pqueue)

gfxQueueGSyncItem * gfxQueueGSyncGet (gfxQueueGSync *pqueue, gDelay ms)

gfxQueueGSyncItem * gfxQueueGSyncGetI (gfxQueueGSync *pqueue)

gfxQueueFSyncItem * gfxQueueFSyncGet (gfxQueueFSync *pqueue, gDelay ms)

Put() Functions

Put an item on the end of the queue.

Returns: none for ASync and GSync queues; For FSync queues - gFalse on timeout, otherwise gTrue

Parameters

[in]	pqueue	A pointer to the queue
[in]	pitem	A pointer to the queue item
[in]	ms	The maxmimum time to wait for an item to be removed from the queue (only for FSync queues)

Note: FSync: Use a delay time of gDelayNone 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)

gBool gfxQueueFSyncPut (gfxQueueFSync *pqueue, gfxQueueFSyncItem *pitem, gDelay ms)

Push() Functions

Push an item into the start of the queue.

Returns: none for ASync and GSync queues; For FSync queues - gFalse on timeout, otherwise gTrue

Parameters

[in]	pqueue	A pointer to the queue
[in]	pitem	A pointer to the queue item
[in]	ms	The maxmimum time to wait for an item to be popped (only for FSync queues)

Note: FSync: Use a delay time of gDelayNone 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)

gBool gfxQueueFSyncPush (gfxQueueFSync *pqueue, gfxQueueFSyncItem *pitem, gDelay ms)

Insert() Functions

Insert an item on the queue after the specified item.

Returns: none for ASync and GSync queues; For FSync queues - gFalse on timeout, otherwise gTrue

Parameters

[in]	pqueue	A pointer to the queue
[in]	pitem	A pointer to the queue item
[in]	pafter	A 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]	ms	The maxmimum time to wait for an item to be removed from the queue (only for FSync queues)

Note: FSync: Use a delay time of gDelayNone 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)

gBool gfxQueueFSyncInsert (gfxQueueFSync *pqueue, gfxQueueFSyncItem *pitem, gfxQueueFSyncItem *pafter, gDelay 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]	pqueue	A pointer to the queue
[in]	pitem	A 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: gTrue if the item is in the queue?

Parameters

[in]	pqueue	A pointer to the queue
[in]	pitem	A 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.

gBool gfxQueueASyncIsIn (gfxQueueASync *pqueue, const gfxQueueASyncItem *pitem)

gBool gfxQueueASyncIsInI (gfxQueueASync *pqueue, const gfxQueueASyncItem *pitem)

gBool gfxQueueGSyncIsIn (gfxQueueGSync *pqueue, const gfxQueueGSyncItem *pitem)

gBool gfxQueueGSyncIsInI (gfxQueueGSync *pqueue, const gfxQueueGSyncItem *pitem)

gBool gfxQueueFSyncIsIn (gfxQueueFSync *pqueue, const gfxQueueFSyncItem *pitem)

gBool gfxQueueFSyncIsInI (gfxQueueFSync *pqueue, const gfxQueueFSyncItem *pitem)

BufferAlloc() Functions

Allocate some buffers and put them on the free list

Returns: gTrue is it succeeded. gFalse on allocation failure.

Parameters

[in]	num	The number of buffers to allocate
[in]	size	The size (in bytes) of each buffer

Function Class: Normal API, this function can be invoked by regular system threads.

gBool gfxBufferAlloc (unsigned num, gMemSize size)

BufferIsAvailable() Functions

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

Returns: gTrue if there are buffers in the free list

Function Class: Normal API, this function can be invoked by regular system threads.

gBool gfxBufferIsAvailable (void)

BufferGet() Functions

Get a buffer from the free list

Returns: A GDataBuffer pointer or NULL if the timeout is exceeded

Parameters

[in] ms The 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.

GDataBuffer * gfxBufferGet (gDelay ms)

GDataBuffer * gfxBufferGetI (void)

BufferRelease() Functions

Release a buffer back to the free list

Parameters

[in] pd The 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: gTrue if the queue is empty

Parameters

[in] pqueue A 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] pqueue A 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] pitem The 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] pqueue A 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)

Detailed Description

Data Structures

Functions

Macros

Typedefs

Deinitialisation functions