UTS6710/aps/include/gsl/gl_queue.h

#ifndef __GSL_QUEUE_H__
#define __GSL_QUEUE_H__

#include "gl_types.h"

/******************************************************************************/
/*!
 * @brief   Used to create a message queue. Space is separately reserved in the queue for normal and urgent messages. Urgent messages should be used sparingly during emergencies only - urgent messages cannot be written into the normal message space. However, if an urgent message is available, it will always be read before a normal message.
 *
 * @param	szName String identifier for the message queue. Limit to 16 characters. Used wherever supported.
 * @param	dElementSize size of each element in the message queue.
 * @param	dMaxElements maximum numbers of elements in the message queue.
 * @param	dMaxUrgentElements maximum number of urgent elements in the message queue. Use 0 if urgent messages are not required.
 * @param	pQueueId Queue object identifier returned by the API (on success)
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 *
 * @note	Cannot be used from ISR/DSR.
 *******************************************************************************/
GL_Status_t GL_QueueCreate(char *szName, GL_UINT32 dElementSize, GL_UINT32 dMaxElements,
						   GL_UINT32 dMaxUrgentElements, GL_Queue_t *pQueueId);

/******************************************************************************/
/*!
 * @brief   Used to delete a message queue. Regarding tasks waiting on a deleted message queue, the behavior depends on the underlying OS; the GSL does not guarantee a default behavior (hence, applications should avoid this scenario). Typically, an error is returned to the waiting tasks.
 *
 * @param	queueId Queue object identifier
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 *
 * @note	Cannot be used from ISR/DSR.
 *******************************************************************************/
GL_Status_t GL_QueueDelete(GL_Queue_t queueId);

/******************************************************************************/
/*!
 * @brief   Used to send a message. The size of the message buffer must match that specified during creation.
 *
 * @param	queueId Queue object identifierpBuffer: Pointer to message buffer
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 * @return	@a GL_QUEUE_FULL if queue has no free space
 *
 * @note	Cannot be used from ISR/DSR.
 *******************************************************************************/
GL_Status_t GL_QueueSend(GL_Queue_t queueId, void *pBuffer, GL_UINT32 dSize);

/******************************************************************************/
/*!
 * @brief   Used to send an urgent message. The size of the message buffer must match that specified during creation.
 *
 * @param	queueId Queue object identifierpBuffer: Pointer to message buffer
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 * @return	@a GL_QUEUE_FULL if queue has no free space
 *
 * @note	Cannot be used from ISR/DSR.
 *******************************************************************************/
GL_Status_t GL_QueueSendUrgent(GL_Queue_t queueId, void *pBuffer, GL_UINT32 dSize);

/******************************************************************************/
/*!
 * @brief   Used to send an urgent message. The size of the message buffer must match that specified during creation.
 *
 * @param	queueId Queue object identifierpBuffer: Pointer to message buffer
 * @param	sdTimeout timeout period to receive message. Measured in milliseconds. Set to:
 *			@li @a GL_INFINITE_WAIT
 *			@li @a GL_NO_WAIT (Any value between 1-2147483647 for finite wait)
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 * @return	@a GL_TIMEOUT on timeout
 * @return	@a GL_QUEUE_EMPTY if queue has no message and timeout=GL_NO_WAIT
 *
 * @note	Cannot be used from ISR/DSR.
 *******************************************************************************/
GL_Status_t GL_QueueReceive(GL_Queue_t queueId, void *pBuffer, GL_UINT32 dSize, GL_INT32 sdTimeout);

/******************************************************************************/
/*!
 * @brief   Drop normal messages in a queue
 *
 * @param	queueId Queue object identifier
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 *
 * @note	Cannot be used from ISR/DSR.
 *******************************************************************************/
GL_Status_t GL_QueueFlushNormal(GL_Queue_t queueId);

/******************************************************************************/
/*!
 * @brief   Drop urgent messages in a queue
 *
 * @param	queueId Queue object identifier
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 *
 * @note	Cannot be used from ISR/DSR.
 *******************************************************************************/
GL_Status_t GL_QueueFlushUrgent(GL_Queue_t queueId);

/******************************************************************************/
/*!
 * @brief   The queue will be reinitialized without caring inside messages.
 *
 * @param	queueId Queue object identifier
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 *
 * @note	Cannot be used from ISR/DSR.
 *******************************************************************************/
GL_Status_t GL_QueueFlush(GL_Queue_t queueId);

/******************************************************************************/
/*!
 * @brief   This returns the current number of FREE URGENT messages in the queue.
 *
 * @param	queueId Queue object identifier
 * @param	value container of the value of free urgent messages peek from GL_Queue_t
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 *
 * @note	None
 *******************************************************************************/
GL_Status_t GL_QueuePeekUrgent(GL_Queue_t queueId, UINT32 *value);
GL_Status_t GL_QueuePeek(GL_Queue_t queueId, GL_UINT32 *value);

#endif