diff options
Diffstat (limited to 'src/gqueue/sys_defs.h')
-rw-r--r-- | src/gqueue/sys_defs.h | 122 |
1 files changed, 98 insertions, 24 deletions
diff --git a/src/gqueue/sys_defs.h b/src/gqueue/sys_defs.h index 4351d4ad..b97f2f4d 100644 --- a/src/gqueue/sys_defs.h +++ b/src/gqueue/sys_defs.h @@ -23,6 +23,8 @@ * 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. + * <br> + * We also define GDataBuffer which is a data buffer that supports being queued. * @{ */ @@ -32,45 +34,52 @@ #if GFX_USE_GQUEUE || defined(__DOXYGEN__) /** + * @brief A queue item + * @{ + */ +typedef struct gfxQueueASyncItem { + struct gfxQueueASyncItem *next; +} gfxQueueASyncItem, gfxQueueGSyncItem; + +typedef struct gfxQueueFSyncItem { + struct gfxQueueFSyncItem *next; + gfxSem sem; +} gfxQueueFSyncItem; +/* @} */ + +/** * @brief A queue * @{ */ typedef struct gfxQueueASync { - struct gfxQueueASyncItem *head; - struct gfxQueueASyncItem *tail; + gfxQueueASyncItem *head; + gfxQueueASyncItem *tail; } gfxQueueASync; typedef struct gfxQueueGSync { - struct gfxQueueGSyncItem *head; - struct gfxQueueGSyncItem *tail; - gfxSem sem; + gfxQueueGSyncItem *head; + gfxQueueGSyncItem *tail; + gfxSem sem; } gfxQueueGSync; typedef struct gfxQueueFSync { - struct gfxQueueFSyncItem *head; - struct gfxQueueFSyncItem *tail; - gfxSem sem; + gfxQueueFSyncItem *head; + gfxQueueFSyncItem *tail; + gfxSem sem; } gfxQueueFSync; /* @} */ /** - * @brief A queue item - * @{ + * @brief 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. */ -typedef struct gfxQueueASyncItem { - struct gfxQueueASyncItem *next; -} gfxQueueASyncItem; - -typedef struct gfxQueueGSyncItem { - struct gfxQueueGSyncItem *next; -} gfxQueueGSyncItem; - -typedef struct gfxQueueFSyncItem { - struct gfxQueueFSyncItem *next; - gfxSem sem; -} gfxQueueFSyncItem; -/* @} */ - +typedef struct GDataBuffer { + gfxQueueGSyncItem next; // @< Used for queueing the buffers + size_t size; // @< The size of the buffer area following this structure (in bytes) + size_t len; // @< The length of the data in the buffer area (in bytes) +} GDataBuffer; /*===========================================================================*/ /* Function declarations. */ @@ -98,6 +107,19 @@ void gfxQueueFSyncInit(gfxQueueFSync *pqueue); /* @} */ /** + * @brief De-Initialise a queue. + * + * @param[in] pqueue A pointer to the queue + * + * @api + * @{ + */ +#define gfxQueueASyncDeinit(pqueue) +void gfxQueueGSyncDeinit(gfxQueueGSync *pqueue); +void gfxQueueFSyncDeinit(gfxQueueFSync *pqueue); +/* @} */ + +/** * @brief Get an item from the head of the queue (and remove it from the queue). * @return NULL if the timeout expires before an item is available * @@ -286,6 +308,58 @@ bool_t gfxQueueFSyncIsInI(gfxQueueFSync *pqueue, const gfxQueueFSyncItem *pitem) #define gfxQueueFSyncNextI(pitem) ((const gfxQueueFSyncItem *)((pitem)->next)) /* @} */ +/** + * @brief Allocate some buffers and put them on the free list + * @return TRUE is it succeeded. FALSE on allocation failure. + * + * @param[in] num The number of buffers to allocate + * @param[in] size The size (in bytes) of each buffer + * + * @api + */ +bool_t gfxBufferAlloc(unsigned num, size_t size); + +/** + * @brief Is there one or more buffers currently available on the free list + * @return TRUE if there are buffers in the free list + * + * @api + * @{ + */ +bool_t gfxBufferIsAvailable(void); +/* @} */ + +/** + * @brief Get a buffer from the free list + * @return A GDataBuffer pointer or NULL if the timeout is exceeded + * + * @param[in] ms The maximum amount of time in milliseconds to wait for a buffer if one is not available. + * + * @api + * @{ + */ +GDataBuffer *gfxBufferGet(delaytime_t ms); +GDataBuffer *gfxBufferGetI(void); +/* @} */ + +/** + * @brief Release a buffer back to the free list + * + * @param[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. + * + * @api + * @{ + */ +void gfxBufferRelease(GDataBuffer *pd); +void gfxBufferReleaseI(GDataBuffer *pd); +/* @} */ + + #ifdef __cplusplus } #endif |