Module which provides queue management (only internally used)
There are 3 types of queues:
-
Asynchronous Queues (ASync) - Queue operations never block
-
Get Synchronous Queues (GSync) - Queue Get operations block until something is placed in the Queue
-
Put Synchronous Queues (PSync) - Queue Put operations block until the element is removed from the Queue
-
Fully Synchronous Queues (FSync) - Queue GET and Put operations block
We need 4 types of queues even though fully synchronous queues support all operations including asynchronous operations because fully synchronous queues have the highest storage requirements. The other queue types are optimizations. Efficiency IS important to use (particularly RAM efficiency). In practice we only implement ASync, GSync and FSync queues as PSync queues are of dubious value.
We also define GDataBuffer which is a data buffer that supports being queued.
|
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) |
|
|
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.
|
void | gfxQueueGSyncDeinit (gfxQueueGSync *pqueue) |
|
void | gfxQueueFSyncDeinit (gfxQueueFSync *pqueue) |
|
#define | gfxQueueASyncDeinit(pqueue) |
|
|
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 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 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 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 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) |
|
|
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) |
|
|
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) |
|
|
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) |
|
|
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) |
|
|
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) |
|
|
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) |
|
|
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) |
|
|
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)) |
|
|
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)) |
|
◆ GQUEUE_NEED_ASYNC
#define GQUEUE_NEED_ASYNC GFXOFF |
Enable Asynchronous Queues.
Defaults to GFXOFF
Definition at line 28 of file gqueue_options.h.
◆ GQUEUE_NEED_BUFFERS
#define GQUEUE_NEED_BUFFERS GFXOFF |
◆ GQUEUE_NEED_FSYNC
#define GQUEUE_NEED_FSYNC GFXOFF |
Enable Fully Synchronous Queues.
Defaults to GFXOFF
Definition at line 42 of file gqueue_options.h.
◆ GQUEUE_NEED_GSYNC
#define GQUEUE_NEED_GSYNC GFXOFF |
Enable Get-Synchronous Queues.
Defaults to GFXOFF
Definition at line 35 of file gqueue_options.h.
◆ GDataBuffer
A Data Buffer Queue.
- Note
- This structure is followed immediately by the data itself. When allocating the buffers for the data put this structure at the beginning of the buffer.
◆ gfxQueueASync
◆ gfxQueueASyncItem