RKH
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages

Files

file  rkhrq.h
 Platform - independent interface for supporting queue services.
 

Data Structures

struct  RKH_RQ_T
 Defines the data structure used to maintain information about the queue. More...
 

Macros

#define RKH_RQ_IS_EMPTY(q)   (rbool_t)(rkh_rq_get_num((RKH_RQ_T *)(q)) == 0)
 This macro query the queue. More...
 

Functions

void rkh_rq_init (RKH_RQ_T *q, const void **sstart, RKH_RQNE_T ssize, const struct RKH_SMA_T *sma)
 Initializes the previously allocated queue data structure RKH_RQ_T. More...
 
rbool_t rkh_rq_is_full (RKH_RQ_T *q)
 This function query the queue. More...
 
RKH_RQNE_T rkh_rq_get_num (RKH_RQ_T *q)
 Returns the number of elements currently in the queue. More...
 
RKH_RQNE_T rkh_rq_get_lwm (RKH_RQ_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_rq_get (RKH_RQ_T *q)
 Get and remove an element from a queue. More...
 
void rkh_rq_put_fifo (RKH_RQ_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_rq_put_lifo (RKH_RQ_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_rq_deplete (RKH_RQ_T *q)
 Depletes a queue. Empties the contents of the queue and eliminates all stored elements. More...
 
ruint rkh_rq_read (RKH_RQ_T *q, void *pe)
 Read an element from a queue without remove it. More...
 
void rkh_rq_get_info (RKH_RQ_T *q, RKH_RQI_T *pqi)
 Retrieves performance information for a particular queue. More...
 
void rkh_rq_clear_info (RKH_RQ_T *q)
 Clear performance information for a particular queue. More...
 

Detailed Description

Macro Definition Documentation

#define RKH_RQ_IS_EMPTY (   q)    (rbool_t)(rkh_rq_get_num((RKH_RQ_T *)(q)) == 0)

This macro query the queue.

Parameters
[in]qpointer to previously created queue.
Returns
'1' (RKH_TRUE) if queue is empty, otherwise '0' (RKH_FALSE).

Definition at line 81 of file rkhrq.h.

Function Documentation

void rkh_rq_init ( RKH_RQ_T q,
const void **  sstart,
RKH_RQNE_T  ssize,
const struct RKH_SMA_T sma 
)

Initializes the previously allocated queue data structure RKH_RQ_T.

A queue is declared with the RKH_RQ_T data type and is defined with the rkh_rq_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]qpointer to previously allocated queue structure.
[in]sstartstorage start. Pointer to an array of pointers that holds the elements. This array must be declared as an array of void pointers.
[in]ssizestorage size [in the units of void pointers].
[in]smapointer 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_RQ_T structure for more information.
rbool_t rkh_rq_is_full ( RKH_RQ_T q)

This function query the queue.

Parameters
[in]qpointer 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_RQ_IS_FULL_EN.
RKH_RQNE_T rkh_rq_get_num ( RKH_RQ_T q)

Returns the number of elements currently in the queue.

Parameters
[in]qpointer to previously created queue.
Note
This function is optional, thus it could be eliminated in compile-time with RKH_CFG_RQ_GET_NELEMS_EN.
RKH_RQNE_T rkh_rq_get_lwm ( RKH_RQ_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]qpointer 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_RQ_GET_LWMARK_EN.
void* rkh_rq_get ( RKH_RQ_T q)

Get and remove an element from a queue.

Parameters
[in]qpointer to previously created queue from which the elements are received.
void rkh_rq_put_fifo ( RKH_RQ_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]qpointer to previously created queue into which the element is deposited.
[in]pepointer-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_rq_put_lifo ( RKH_RQ_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]qpointer to previously created queue into which the element is deposited.
[in]pepointer-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_RQ_PUT_LIFO_EN.
void rkh_rq_deplete ( RKH_RQ_T q)

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

Parameters
[in]qpointer 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_rq_get().
This function is optional, thus it could be eliminated in compile-time with RKH_CFG_RQ_DEPLETE_EN.
ruint rkh_rq_read ( RKH_RQ_T q,
void *  pe 
)

Read an element from a queue without remove it.

Parameters
[in]qpointer to previously created queue from which the elements are received.
[in]pepointer to the buffer into which the received item will be copied.
Returns
RKH_RQ_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_RQ_READ_EN.
void rkh_rq_get_info ( RKH_RQ_T q,
RKH_RQI_T pqi 
)

Retrieves performance information for a particular queue.

The user application must allocate an RKH_RQI_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]qpointer to previously created queue.
[in]pqipointer to the buffer into which the performance information will be copied.
Note
See RKH_RQI_T structure for more information. This function is optional, thus it could be eliminated in compile-time with RKH_CFG_RQ_GET_INFO_EN.
void rkh_rq_clear_info ( RKH_RQ_T q)

Clear performance information for a particular queue.

Parameters
[in]qpointer to previously created queue.
Note
This function is optional, thus it could be eliminated in compile-time with RKH_CFG_RQ_GET_INFO_EN.