Queue

Features Supported

APIs to create and destroy Queues
APIs to Put element in Queue
APIs to Get element from Queue
APIs to Check if Queue is Empty

Features NOT Supported

NA

Important Usage Guidelines

For creating the Queue application needs to provide the #QueueP_Object and it should not be modified by the applicaion.
A field of type #QueueP_Elem should be placed at the head of client structs passed as Queue Elements to function #QueueP_put.
It is recommended not to place the QueueP Object and QueueP Element objects in stack as they will be accessed by the driver till they are released.

Example Usage

Include the below file to access the APIs,

//! [include]
#include <kernel/dpl/QueueP.h>
//! [include]
#include <kernel/dpl/DebugP.h>
#include <drivers/hw_include/csl_types.h>

//! [define]
/* Define a client structure for the queue elements.
   The object of type QueueP_Elem should be placed at the head of the structure. */

Example usage to define Queue Object and Elements:

{
    QueueP_Elem lnk;
    uint32_t    index;
} Test_Queue_Elem;

Test_Queue_Elem  elem1, elem2;
QueueP_Object    qObj;
//! [define]

void samples()
{
{
//! [queue_usage]
    QueueP_Handle   handle;

Example to create and use the Queue:

    /* Create the Queue. */
    handle = QueueP_create(&qObj);

    /* Put elements in a Queue. */
    QueueP_put(handle, (QueueP_Elem *)&elem1);
    QueueP_put(handle, (QueueP_Elem *)&elem2);

    /* Get elements from the queue. */
    pElem = (Test_Queue_Elem *)QueueP_get(handle);
    pElem = (Test_Queue_Elem *)QueueP_get(handle);
    /* Typically pElem would be processed by application. 
     * In sample typecast to void to kill warning 
     * regarding variable set but not used 
     */

API Reference

State codes for current queue state

QueueP_NOTEMPTY

QueueP_EMPTY

Defines

QueueP_OBJECT_SIZE_MAX: Max size of task object across all OS’s.

Typedefs

typedef void *QueueP_Handle

Opaque client reference to an instance of a QueueP.

A QueueP_Handle returned from the QueueP_create represents that instance and is used in the other instance based functions

Functions

QueueP_Handle QueueP_create(QueueP_Object *obj)

Function to create a queue.

Parameters:: obj – [in] Pointer to QueueP_Object.
Returns:: A QueueP_Handle on success or a NULL on an error

int32_t QueueP_delete(QueueP_Handle handle)

Function to delete a queue.

Parameters:

handle – [in] A QueueP_Handle returned from QueueP_create

Returns:

Status of the functions

QueueP_OK: Deleted the queue instance
QueueP_FAILURE: Failed to delete the queue instance

void *QueueP_get(QueueP_Handle handle)

Function to Get the element at the front of the queue. This function removes an element from the front of a queue and returns it.

Parameters:: handle – [in] A QueueP_Handle returned from QueueP_create
Returns:: pointer to the element or pointer to queue itself incase of empty queue

int32_t QueueP_put(QueueP_Handle handle, void *elem)

Function to Put an element at end of queue.

Parameters:

handle – [in] A QueueP_Handle returned from QueueP_create
elem – [in] Pointer to new queue element

Returns:

Status of the functions

QueueP_OK: Put the element at end of queue
QueueP_FAILURE: Failed to Put the element at end of queue

uint32_t QueueP_isEmpty(QueueP_Handle handle)

Function to perform queue empty check.

Parameters:

handle – [in] A QueueP_Handle returned from QueueP_create

Returns:

Current state of the Queue

QueueP_NOTEMPTY: queue is not empty
QueueP_EMPTY: queue is empty

uint32_t QueueP_getSize(QueueP_Handle handle)

Function to get the number of elements in the queue.

Parameters:: handle – [in] A QueueP_Handle returned from QueueP_create
Returns:: Number of elements currently in the queue

void *QueueP_peekHead(QueueP_Handle handle)

Function to peek at the head element without removing it.

Parameters:: handle – [in] A QueueP_Handle returned from QueueP_create
Returns:: Pointer to the head element, or NULL if the queue is empty

struct QueueP_Elem

#include <QueueP.h>

Opaque QueueP element.

Structure that defines a single queue element and/or a list of queue elements. A field of this type is placed at the head of client structs.

Public Members

struct QueueP_Elem_s *next: Pointer to the next queue element

struct QueueP_Elem_s *prev: Pointer to the previous queue element

struct QueueP_Object

#include <QueueP.h>

Opaque task object used with the task APIs.

Public Members

uintptr_t rsv[QueueP_OBJECT_SIZE_MAX / sizeof(uint32_t)]: reserved, should NOT be modified by end users