Files
file	rkhqueue.h
	Specifies the interface of the queue services.

Data Structures
struct	RKH_QUEUE_T
	Defines the data structure used to maintain information about the queue. More...

Macros
#define	RKH_QUEUE_IS_EMPTY(q) (rbool_t)(rkh_queue_get_num((RKH_QUEUE_T *)(q)) == 0)
	This macro query the queue. More...

Functions
void	rkh_queue_init (RKH_QUEUE_T q, const void sstart, RKH_QUENE_T ssize, void sma)
	Initializes the previously allocated queue data structure RKH_QUEUE_T. More...

rbool_t	rkh_queue_is_full (RKH_QUEUE_T *q)
	This function query the queue. More...

RKH_QUENE_T	rkh_queue_get_num (RKH_QUEUE_T *q)
	Returns the number of elements currently in the queue. More...

RKH_QUENE_T	rkh_queue_get_lwm (RKH_QUEUE_T *q)
	This function returns the lowest number of free elements ever present in the pool. This number provides valuable empirical data for proper sizing of the queue. More...

void *	rkh_queue_get (RKH_QUEUE_T *q)
	Get and remove an element from a queue. More...

void	rkh_queue_put_fifo (RKH_QUEUE_T q, const void pe)
	Puts an element on a queue in a FIFO manner. The element is queued by reference, not by copy. More...

void	rkh_queue_put_lifo (RKH_QUEUE_T q, const void pe)
	Puts an element on a queue in a LIFO manner. The element is queued by reference, not by copy. More...

void	rkh_queue_deplete (RKH_QUEUE_T *q)
	Depletes a queue. Empties the contents of the queue and eliminates all stored elements. More...

ruint	rkh_queue_read (RKH_QUEUE_T q, void pe)
	Read an element from a queue without remove it. More...

void	rkh_queue_get_info (RKH_QUEUE_T q, RKH_QUEI_T pqi)
	Retrieves performance information for a particular queue. More...

void	rkh_queue_clear_info (RKH_QUEUE_T *q)
	Clear performance information for a particular queue. More...

Detailed Description

Macro Definition Documentation

#define RKH_QUEUE_IS_EMPTY ( q ) (rbool_t)(rkh_queue_get_num((RKH_QUEUE_T *)(q)) == 0)

This macro query the queue.

Parameters

[in] q pointer to previously created queue.

Returns: '1' (RKH_TRUE) if queue is empty, otherwise '0' (RKH_FALSE).

Definition at line 81 of file rkhqueue.h.

Function Documentation

void rkh_queue_init	(	RKH_QUEUE_T *	q,
		const void **	sstart,
		RKH_QUENE_T	ssize,
		void *	sma
	)

Initializes the previously allocated queue data structure RKH_QUEUE_T.

A queue is declared with the RKH_QUEUE_T data type and is defined with the rkh_queue_init() service. The total number of messages is calculated from the specified message size (pointer size) and the total number of bytes in the queue. Note that if the total number of bytes specified in the queue's memory area is not evenly divisible by the specified message size, the remaining bytes in the memory area are not used.

Parameters

[in]	q	pointer to previously allocated queue structure.
[in]	sstart	storage start. Pointer to an array of pointers that holds the elements. This array must be declared as an array of void pointers.
[in]	ssize	storage size [in the units of void pointers].
[in]	sma	pointer to associated SMA that receives the enqueued events. If sma is set to NULL they never block. When using a queue to store deferred events the sma parameter must be set to NULL.

See also: RKH_QUEUE_T structure for more information.

rbool_t rkh_queue_is_full ( RKH_QUEUE_T * q )

This function query the queue.

Parameters

[in] q pointer to previously created queue.

Returns: '1' (RKH_TRUE) if queue is full, otherwise '0' (RKH_FALSE).

Note: This function is optional, thus it could be eliminated in compile-time with RKH_CFG_QUE_IS_FULL_EN.

RKH_QUENE_T rkh_queue_get_num ( RKH_QUEUE_T * q )

Returns the number of elements currently in the queue.

Parameters

[in] q pointer to previously created queue.

Note: This function is optional, thus it could be eliminated in compile-time with RKH_CFG_QUE_GET_NELEMS_EN.

RKH_QUENE_T rkh_queue_get_lwm ( RKH_QUEUE_T * q )

This function returns the lowest number of free elements ever present in the pool. This number provides valuable empirical data for proper sizing of the queue.

Parameters

[in] q pointer to previously created queue.

Returns: Lowest number of free elements ever present in the queue.

Note: This function is optional, thus it could be eliminated in compile-time with RKH_CFG_QUE_GET_LWMARK_EN.

void* rkh_queue_get ( RKH_QUEUE_T * q )

Get and remove an element from a queue.

Parameters

[in] q pointer to previously created queue from which the elements are received.

void rkh_queue_put_fifo	(	RKH_QUEUE_T *	q,
		const void *	pe
	)

Puts an element on a queue in a FIFO manner. The element is queued by reference, not by copy.

Parameters

[in]	q	pointer to previously created queue into which the element is deposited.
[in]	pe	pointer-sized variable and is application specific.

Note: This function must be invoked within a critical section.; The function raises an assertion if the queue becomes full and cannot accept the element.

void rkh_queue_put_lifo	(	RKH_QUEUE_T *	q,
		const void *	pe
	)

Puts an element on a queue in a LIFO manner. The element is queued by reference, not by copy.

Parameters

[in]	q	pointer to previously created queue into which the element is deposited.
[in]	pe	pointer-sized variable and is application specific.

Note: This function must be invoked within a critical section.; The function raises an assertion if the queue becomes full and cannot accept the element.; This function is optional, thus it could be eliminated in compile-time with RKH_CFG_QUE_PUT_LIFO_EN.

void rkh_queue_deplete ( RKH_QUEUE_T * q )

Depletes a queue. Empties the contents of the queue and eliminates all stored elements.

Parameters

[in] q pointer to previously created queue.

Note: This function should be used with great care because, when to flush the queue, the references are LOOSE to what the queue entries are pointing to and thus, could cause 'memory leaks'. In other words, the data pointing to that's being referenced by the queue entries should, most likely, need to be deallocated. To flush a queue that contains entries, is much safer instead repeateadly use rkh_queue_get().; This function is optional, thus it could be eliminated in compile-time with RKH_CFG_QUE_DEPLETE_EN.

ruint rkh_queue_read	(	RKH_QUEUE_T *	q,
		void *	pe
	)

Read an element from a queue without remove it.

Parameters

[in]	q	pointer to previously created queue from which the elements are received.
[in]	pe	pointer to the buffer into which the received item will be copied.

Returns: RKH_QUE_OK if an element was successfully readed from the queue, otherwise error code.

Note: This function is optional, thus it could be eliminated in compile-time with RKH_CFG_QUE_READ_EN.

void rkh_queue_get_info	(	RKH_QUEUE_T *	q,
		RKH_QUEI_T *	pqi
	)

Retrieves performance information for a particular queue.

The user application must allocate an RKH_QUEI_T data structure used to receive data. The performance information is available during run-time for each of the RKH services. This can be useful in determining whether the application is performing properly, as well as helping to optimize the application. This information provides a "snapshot" a particular instant in time, i.e., when the service is invoked.

Parameters

[in]	q	pointer to previously created queue.
[in]	pqi	pointer to the buffer into which the performance information will be copied.

Note: See RKH_QUEI_T structure for more information. This function is optional, thus it could be eliminated in compile-time with RKH_CFG_QUE_GET_INFO_EN.

void rkh_queue_clear_info ( RKH_QUEUE_T * q )

Clear performance information for a particular queue.

Parameters

[in] q pointer to previously created queue.

Note: This function is optional, thus it could be eliminated in compile-time with RKH_CFG_QUE_GET_INFO_EN.

Files

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation