ugfx/include/gqueue/gqueue.h
2013-08-01 14:53:13 +10:00

261 lines
8.4 KiB
C

/*
* 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:
*
* http://ugfx.org/license.html
*/
/**
* @file include/gqueue/gqueue.h
* @brief GQUEUE header file.
*
* @addtogroup GQUEUE
*
* @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.
* @{
*/
#ifndef _GQUEUE_H
#define _GQUEUE_H
#if GFX_USE_GQUEUE || defined(__DOXYGEN__)
/**
* @brief A queue
* @{
*/
typedef struct gfxQueueASync {
struct gfxQueueASyncItem *head;
struct gfxQueueASyncItem *tail;
} gfxQueueASync;
typedef struct gfxQueueGSync {
struct gfxQueueGSyncItem *head;
struct gfxQueueGSyncItem *tail;
gfxSem sem;
} gfxQueueGSync;
typedef struct gfxQueueFSync {
struct gfxQueueFSyncItem *head;
struct gfxQueueFSyncItem *tail;
gfxSem sem;
} gfxQueueFSync;
/* @} */
/**
* @brief A queue item
* @{
*/
typedef struct gfxQueueASyncItem {
struct gfxQueueASyncItem *next;
} gfxQueueASyncItem;
typedef struct gfxQueueGSyncItem {
struct gfxQueueGSyncItem *next;
} gfxQueueGSyncItem;
typedef struct gfxQueueFSyncItem {
struct gfxQueueFSyncItem *next;
gfxSem sem;
} gfxQueueFSyncItem;
/* @} */
/*===========================================================================*/
/* Function declarations. */
/*===========================================================================*/
#ifdef __cplusplus
extern "C" {
#endif
/**
* @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);
/* @} */
/**
* @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.
*
* @api
* @{
*/
gfxQueueASyncItem *gfxQueueASyncGet(gfxQueueASync *pqueue);
gfxQueueGSyncItem *gfxQueueGSyncGet(gfxQueueGSync *pqueue, delaytime_t ms);
gfxQueueFSyncItem *gfxQueueFSyncGet(gfxQueueFSync *pqueue, delaytime_t ms);
/* @} */
/**
* @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.
*
* @api
* @{
*/
void gfxQueueASyncPut(gfxQueueASync *pqueue, gfxQueueASyncItem *pitem);
void gfxQueueGSyncPut(gfxQueueGSync *pqueue, gfxQueueGSyncItem *pitem);
bool_t gfxQueueFSyncPut(gfxQueueFSync *pqueue, gfxQueueFSyncItem *pitem, delaytime_t ms);
/* @} */
/**
* @brief Pop an item from the head of the queue (and remove it from the queue).
* @details This is exactly the same as the Get operation above.
*
* @api
* @{
*/
#define gfxQueueASyncPop(pqueue) gfxQueueASyncGet(pqueue)
#define gfxQueueGSyncPop(pqueue, ms) gfxQueueGSyncGet(pqueue, ms)
#define gfxQueueFSyncPop(pqueue, ms) gfxQueueFSyncGet(pqueue, ms)
/* @} */
/**
* @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.
*
* @api
* @{
*/
void gfxQueueASyncPush(gfxQueueASync *pqueue, gfxQueueASyncItem *pitem);
void gfxQueueGSyncPush(gfxQueueGSync *pqueue, gfxQueueGSyncItem *pitem);
bool_t gfxQueueFSyncPush(gfxQueueFSync *pqueue, gfxQueueFSyncItem *pitem, delaytime_t ms);
/* @} */
/**
* @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.
*
* @api
* @{
*/
void gfxQueueASyncRemove(gfxQueueASync *pqueue, gfxQueueASyncItem *pitem);
void gfxQueueGSyncRemove(gfxQueueGSync *pqueue, gfxQueueGSyncItem *pitem);
void gfxQueueFSyncRemove(gfxQueueFSync *pqueue, gfxQueueFSyncItem *pitem);
/* @} */
/**
* @brief Is the queue empty?
* @return TRUE if the queue is empty
*
* @param[in] pqueue A pointer to the queue
*
* @api
* @{
*/
bool_t gfxQueueASyncIsEmpty(gfxQueueASync *pqueue);
bool_t gfxQueueGSyncIsEmpty(gfxQueueGSync *pqueue);
bool_t gfxQueueFSyncIsEmpty(gfxQueueFSync *pqueue);
/* @} */
/**
* @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.
*
* @api
* @{
*/
bool_t gfxQueueASyncIsIn(gfxQueueASync *pqueue, const gfxQueueASyncItem *pitem);
bool_t gfxQueueGSyncIsIn(gfxQueueGSync *pqueue, const gfxQueueGSyncItem *pitem);
bool_t gfxQueueFSyncIsIn(gfxQueueFSync *pqueue, const gfxQueueFSyncItem *pitem);
/* @} */
/**
* @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).
*
* @api
* @{
*/
#define gfxQueueASyncPeek(pqueue) ((const gfxQueueASyncItem *)((pqueue)->head))
#define gfxQueueGSyncPeek(pqueue) ((const gfxQueueGSyncItem *)((pqueue)->head))
#define gfxQueueFSyncPeek(pqueue) ((const gfxQueueFSyncItem *)((pqueue)->head))
/* @} */
/**
* @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).
*
* @api
* @{
*/
#define gfxQueueASyncNext(pitem) ((const gfxQueueASyncItem *)((pitem)->next))
#define gfxQueueGSyncNext(pitem) ((const gfxQueueGSyncItem *)((pitem)->next))
#define gfxQueueFSyncNext(pitem) ((const gfxQueueFSyncItem *)((pitem)->next))
/* @} */
#ifdef __cplusplus
}
#endif
#endif /* GFX_USE_GQUEUE */
#endif /* _GQUEUE_H */
/** @} */