ugfx/src/gqueue/gqueue.h

413 lines
14 KiB
C
Raw Normal View History

/*
2013-06-15 11:09:02 +00:00
* This file is subject to the terms of the GFX License. If a copy of
* the license was not distributed with this file, you can obtain one at:
*
2013-07-21 20:20:37 +00:00
* http://ugfx.org/license.html
2013-06-15 11:09:02 +00:00
*/
/**
* @file src/gqueue/gqueue.h
* @brief GQUEUE header file.
*
* @addtogroup GQUEUE
2013-07-21 20:02:57 +00:00
*
* @brief Module which provides queue management (only internally used)
*
* @details There are 3 types of queues:
* <ul><li><b>Asynchronous Queues (ASync) </b> - Queue operations never block</li>
* <li><b>Get Synchronous Queues (GSync) </b> - Queue Get operations block until something is placed in the Queue</li>
* <li><b>Put Synchronous Queues (PSync)</b> - Queue Put operations block until the element is removed from the Queue</li>
* <li><b>Fully Synchronous Queues (FSync)</b> - Queue GET and Put operations block</li>
* </ul>
* 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.
* <br>
* We also define GDataBuffer which is a data buffer that supports being queued.
* @{
*/
#ifndef _GQUEUE_H
#define _GQUEUE_H
#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 {
gfxQueueASyncItem *head;
gfxQueueASyncItem *tail;
2013-12-18 21:11:46 +00:00
} gfxQueueASync;
typedef struct gfxQueueGSync {
gfxQueueGSyncItem *head;
gfxQueueGSyncItem *tail;
gfxSem sem;
2013-12-18 21:11:46 +00:00
} gfxQueueGSync;
typedef struct gfxQueueFSync {
gfxQueueFSyncItem *head;
gfxQueueFSyncItem *tail;
gfxSem sem;
2013-12-18 21:11:46 +00:00
} gfxQueueFSync;
/** @} */
/**
* @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 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. */
/*===========================================================================*/
#ifdef __cplusplus
extern "C" {
#endif
/**
2014-11-28 18:55:36 +00:00
* @name Initialisation functions
* @brief Initialise a queue.
*
* @param[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).
*
* @api
* @{
*/
void gfxQueueASyncInit(gfxQueueASync *pqueue);
void gfxQueueGSyncInit(gfxQueueGSync *pqueue);
void gfxQueueFSyncInit(gfxQueueFSync *pqueue);
/** @} */
/**
2014-11-28 18:55:36 +00:00
* @name Deinitialisation functions
* @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);
/** @} */
/**
2014-11-28 18:55:36 +00:00
* @name Get() Functions
* @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
*
* @param[in] pqueue A pointer to the queue
* @param[in] ms The maxmimum time to wait for an item. For ASync queues this parameter is
* not specified as TIME_IMMEDIATE is assumed.
*
2014-03-02 21:38:57 +00:00
* @note The routines ending in "I" are interrupt/system/iclass level routines.
*
* @api
* @{
*/
gfxQueueASyncItem *gfxQueueASyncGet(gfxQueueASync *pqueue);
2014-03-02 21:38:57 +00:00
gfxQueueASyncItem *gfxQueueASyncGetI(gfxQueueASync *pqueue);
gfxQueueGSyncItem *gfxQueueGSyncGet(gfxQueueGSync *pqueue, delaytime_t ms);
2014-03-11 07:11:02 +00:00
gfxQueueGSyncItem *gfxQueueGSyncGetI(gfxQueueGSync *pqueue);
gfxQueueFSyncItem *gfxQueueFSyncGet(gfxQueueFSync *pqueue, delaytime_t ms);
/** @} */
/**
2014-11-28 18:55:36 +00:00
* @name Put() Functions
* @brief Put an item on the end of the queue.
* @return none for ASync and GSync queues; For FSync queues - FALSE on timeout, otherwise TRUE
*
* @param[in] pqueue A pointer to the queue
* @param[in] pitem A pointer to the queue item
* @param[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 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.
2014-03-02 21:38:57 +00:00
* @note The routines ending in "I" are interrupt/system/iclass level routines.
*
* @api
* @{
*/
void gfxQueueASyncPut(gfxQueueASync *pqueue, gfxQueueASyncItem *pitem);
2014-03-02 21:38:57 +00:00
void gfxQueueASyncPutI(gfxQueueASync *pqueue, gfxQueueASyncItem *pitem);
void gfxQueueGSyncPut(gfxQueueGSync *pqueue, gfxQueueGSyncItem *pitem);
2014-03-02 21:38:57 +00:00
void gfxQueueGSyncPutI(gfxQueueGSync *pqueue, gfxQueueGSyncItem *pitem);
bool_t gfxQueueFSyncPut(gfxQueueFSync *pqueue, gfxQueueFSyncItem *pitem, delaytime_t ms);
/** @} */
/**
2014-11-28 18:55:36 +00:00
* @name Pop() Functions
* @brief Pop an item from the head of the queue (and remove it from the queue).
2013-07-21 20:02:57 +00:00
* @details This is exactly the same as the Get operation above.
*
* @api
* @{
*/
#define gfxQueueASyncPop(pqueue) gfxQueueASyncGet(pqueue)
2014-03-02 21:38:57 +00:00
#define gfxQueueASyncPopI(pqueue) gfxQueueASyncGetI(pqueue)
#define gfxQueueGSyncPop(pqueue, ms) gfxQueueGSyncGet(pqueue, ms)
#define gfxQueueFSyncPop(pqueue, ms) gfxQueueFSyncGet(pqueue, ms)
/** @} */
/**
2014-11-28 18:55:36 +00:00
* @name Push() Functions
* @brief Push an item into the start of the queue.
* @return none for ASync and GSync queues; For FSync queues - FALSE on timeout, otherwise TRUE
*
* @param[in] pqueue A pointer to the queue
* @param[in] pitem A pointer to the queue item
* @param[in] ms The 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.
2014-03-02 21:38:57 +00:00
* @note The routines ending in "I" are interrupt/system/iclass level routines.
*
* @api
* @{
*/
void gfxQueueASyncPush(gfxQueueASync *pqueue, gfxQueueASyncItem *pitem);
2014-03-02 21:38:57 +00:00
void gfxQueueASyncPushI(gfxQueueASync *pqueue, gfxQueueASyncItem *pitem);
void gfxQueueGSyncPush(gfxQueueGSync *pqueue, gfxQueueGSyncItem *pitem);
2014-03-02 21:38:57 +00:00
void gfxQueueGSyncPushI(gfxQueueGSync *pqueue, gfxQueueGSyncItem *pitem);
bool_t gfxQueueFSyncPush(gfxQueueFSync *pqueue, gfxQueueFSyncItem *pitem, delaytime_t ms);
/** @} */
/**
2014-11-28 18:55:36 +00:00
* @name Insert() Functions
* @brief Insert an item on the queue after the specified item.
* @return none for ASync and GSync queues; For FSync queues - FALSE on timeout, otherwise TRUE
*
* @param[in] pqueue A pointer to the queue
* @param[in] pitem A pointer to the queue item
* @param[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.
* @param[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 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.
* @note The routines ending in "I" are interrupt/system/iclass level routines.
*
* @api
* @{
*/
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);
/** @} */
/**
2014-11-28 18:55:36 +00:00
* @name Remove() Functions
* @brief Remove an item from the queue.
* @note Removes the specified item from the queue where-ever it is in the queue
*
* @param[in] pqueue A pointer to the queue
* @param[in] pitem A pointer to the queue item
*
* @note If the item isn't in the queue the routine just returns.
* @note If a process is waiting on the Put/Push operation for the item, that process
* will be signaled.
2014-03-02 21:38:57 +00:00
* @note The routines ending in "I" are interrupt/system/iclass level routines.
*
* @api
* @{
*/
void gfxQueueASyncRemove(gfxQueueASync *pqueue, gfxQueueASyncItem *pitem);
2014-03-02 21:38:57 +00:00
void gfxQueueASyncRemoveI(gfxQueueASync *pqueue, gfxQueueASyncItem *pitem);
void gfxQueueGSyncRemove(gfxQueueGSync *pqueue, gfxQueueGSyncItem *pitem);
2014-03-02 21:38:57 +00:00
void gfxQueueGSyncRemoveI(gfxQueueGSync *pqueue, gfxQueueGSyncItem *pitem);
void gfxQueueFSyncRemove(gfxQueueFSync *pqueue, gfxQueueFSyncItem *pitem);
/** @} */
/**
2014-11-28 18:55:36 +00:00
* @name isEmpty() Functions
* @brief Is the queue empty?
* @return TRUE if the queue is empty
*
* @param[in] pqueue A pointer to the queue
*
2014-03-02 21:38:57 +00:00
* @note The routines ending in "I" are interrupt/system/iclass level routines.
*
* @api
* @{
*/
2014-03-11 07:11:02 +00:00
#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)
/** @} */
/**
2014-11-28 18:55:36 +00:00
* @name IsInQueue() Functions
* @brief Is an item in the queue?
* @return TRUE if the item is in the queue?
*
* @param[in] pqueue A pointer to the queue
* @param[in] pitem A pointer to the queue item
*
* @note This operation may be expensive.
2014-03-02 21:38:57 +00:00
* @note The routines ending in "I" are interrupt/system/iclass level routines.
*
* @api
* @{
*/
2013-08-01 04:53:13 +00:00
bool_t gfxQueueASyncIsIn(gfxQueueASync *pqueue, const gfxQueueASyncItem *pitem);
2014-03-02 21:38:57 +00:00
bool_t gfxQueueASyncIsInI(gfxQueueASync *pqueue, const gfxQueueASyncItem *pitem);
2013-08-01 04:53:13 +00:00
bool_t gfxQueueGSyncIsIn(gfxQueueGSync *pqueue, const gfxQueueGSyncItem *pitem);
2014-03-02 21:38:57 +00:00
bool_t gfxQueueGSyncIsInI(gfxQueueGSync *pqueue, const gfxQueueGSyncItem *pitem);
2013-08-01 04:53:13 +00:00
bool_t gfxQueueFSyncIsIn(gfxQueueFSync *pqueue, const gfxQueueFSyncItem *pitem);
2014-03-02 21:38:57 +00:00
bool_t gfxQueueFSyncIsInI(gfxQueueFSync *pqueue, const gfxQueueFSyncItem *pitem);
/** @} */
/**
2014-11-28 18:55:36 +00:00
* @name Peek() Functions
* @brief Get the first item from the head of the queue but do not remove it from the queue.
* @return NULL if no item is available.
*
* @param[in] pqueue A pointer to the queue
*
* @note This call does not block.
* @note This can be used as the first call to iterate all the elements in the queue.
* @note 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).
2014-03-02 21:38:57 +00:00
* @note The routines ending in "I" are interrupt/system/iclass level routines.
*
* @api
* @{
*/
#define gfxQueueASyncPeek(pqueue) ((const gfxQueueASyncItem *)((pqueue)->head))
2014-03-02 21:38:57 +00:00
#define gfxQueueASyncPeekI(pqueue) ((const gfxQueueASyncItem *)((pqueue)->head))
#define gfxQueueGSyncPeek(pqueue) ((const gfxQueueGSyncItem *)((pqueue)->head))
2014-03-02 21:38:57 +00:00
#define gfxQueueGSyncPeekI(pqueue) ((const gfxQueueGSyncItem *)((pqueue)->head))
#define gfxQueueFSyncPeek(pqueue) ((const gfxQueueFSyncItem *)((pqueue)->head))
2014-03-02 21:38:57 +00:00
#define gfxQueueFSyncPeekI(pqueue) ((const gfxQueueFSyncItem *)((pqueue)->head))
/** @} */
/**
2014-11-28 18:55:36 +00:00
* @name Next() Functions
* @brief Get the next item in the queue (but do not remove it from the queue).
* @return NULL if no item is available.
*
* @param[in] pitem The previous item in the queue
*
* @note This call does not block.
* @note This can be used as subsequent calls to iterate all the elements in the queue.
* @note 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).
2014-03-02 21:38:57 +00:00
* @note The routines ending in "I" are interrupt/system/iclass level routines.
*
* @api
* @{
*/
#define gfxQueueASyncNext(pitem) ((const gfxQueueASyncItem *)((pitem)->next))
2014-03-02 21:38:57 +00:00
#define gfxQueueASyncNextI(pitem) ((const gfxQueueASyncItem *)((pitem)->next))
#define gfxQueueGSyncNext(pitem) ((const gfxQueueGSyncItem *)((pitem)->next))
2014-03-02 21:38:57 +00:00
#define gfxQueueGSyncNextI(pitem) ((const gfxQueueGSyncItem *)((pitem)->next))
#define gfxQueueFSyncNext(pitem) ((const gfxQueueFSyncItem *)((pitem)->next))
2014-03-02 21:38:57 +00:00
#define gfxQueueFSyncNextI(pitem) ((const gfxQueueFSyncItem *)((pitem)->next))
/** @} */
/**
2014-11-28 18:55:36 +00:00
* @name BufferAlloc() Functions
* @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
2014-11-28 18:55:36 +00:00
* @{
*/
bool_t gfxBufferAlloc(unsigned num, size_t size);
2014-11-28 18:55:36 +00:00
/** @} */
/**
2014-11-28 18:55:36 +00:00
* @name BufferIsAvailable() Functions
* @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);
/** @} */
/**
2014-11-28 18:55:36 +00:00
* @name BufferGet() Functions
* @brief Get a buffer from the free list
* @return A GDataBuffer pointer or NULL if the timeout is exceeded
*
2014-03-28 19:18:03 +00:00
* @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);
/** @} */
/**
* @name BufferRelease() Functions
* @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
#endif /* GFX_USE_GQUEUE */
#endif /* _GQUEUE_H */
/** @} */