XDK API  3.6.0
Documentation
Files | Data Structures | Functions
Queue

Defines the interface for message queue (FIFO data structure) with variable size of elements. More...

+ Collaboration diagram for Queue:

Files

file  BCDS_Queue.h
 

Data Structures

struct  Queue_T
 The queue structure. More...
 
struct  QueueItem_T
 The queue item. More...
 

Functions

void Queue_Clear (Queue_T *Queue)
 Cleans the queue buffer from all messages. More...
 
uint32_t Queue_Count (const Queue_T *Queue)
 Gets number of messages available for receiving from the queue. More...
 
Retcode_T Queue_Create (Queue_T *Queue, uint8_t *Buffer, uint32_t BufferSize)
 Creates a queue by initializing its structure with provided buffer where queue items to be stored. More...
 
Retcode_T Queue_Delete (Queue_T *Queue)
 Deletes a queue by deinitializing its structure members. More...
 
Retcode_T Queue_Get (Queue_T *Queue, void **Data, uint32_t *DataSize, uint32_t Timeout)
 Gets an item with payload from the queue. More...
 
Retcode_T Queue_Purge (Queue_T *Queue)
 Purges a room in the queue buffer (dequeues message) occupied by received data. More...
 
Retcode_T Queue_Put (Queue_T *Queue, const void *Item, uint32_t ItemSize, const void *Payload, uint32_t PayloadSize)
 Puts an item with/without payload to the queue. More...
 

Detailed Description

This queue is thread safe, so can be used with multiple senders and receivers. Though, the most efficient design should have only one receiver and one/multiple senders. There is no ISR API extension, so the queue should not be used from interrupts. A message data is copied only once, i.e. when it is added to the queue. When the message data is received from the queue with Queue_Get(), the receiver must release (dequeue) the message from the queue by Queue_Purge() when it is no longer used, this will make next message available for receiver. The message data can have two variable size parts: item and payload. The item can be fixed size header where a length of variable size payload is stored.

// example of usage the queue
typedef struct
{
uint32_t Type;
uint32_t PayloadSize;
uint8_t Payload[];
} ItemHead_T;
static Queue_T Queue;
static uint8_t QueueBuffer[128];
void sender_task()
{
ItemHead_T m;
while(1)
{
// Get some data (type, payload etc.)
...
m.Type = type;
m.PayloadSize = payloadSize;
// Send the message
if (Queue_Put(&q, &m, sizeof(m), payload, payloadSize) != RETCODE_OK)
{
// Do error handling
...
}
}
}
void receiver_task()
{
ItemHead_T *m;
uint32_t size;
while(1)
{
// Receive a message
Queue_Get(&Queue, &m, &size, portMAX_DELAY);
// Process received message
if (m->type == something)
{
process_message(m->Payload, m->PayloadSize);
...
}
// Free the message
Queue_Purge(&Queue);
}
}
void init()
{
// Create the queue
Queue_Create(&Queue, QueueBuffer, sizeof(QueueBuffer));
// Create sender_task() and receiver_task()
...
}

Data Structure Documentation

struct Queue_T
+ Collaboration diagram for Queue_T:

Data Fields

uint8_t * Buffer
 
uint32_t BufferSize
 
uint32_t Count
 
QueueItem_TLast
 
xSemaphoreHandle Lock
 
uint8_t * PosRead
 
uint8_t * PosWrite
 
xSemaphoreHandle Wakeup
 

Field Documentation

uint8_t* Buffer
uint32_t BufferSize
uint32_t Count
QueueItem_T* Last
uint8_t* PosRead
uint8_t* PosWrite
struct QueueItem_T

Data Fields

uint8_t Data []
 
uint8_t * Next
 
uint32_t Size
 

Field Documentation

uint8_t Data[]
uint8_t* Next
uint32_t Size

Function Documentation

void Queue_Clear ( Queue_T Queue)
Parameters
[in]QueueThe queue structure (must not be equal to NULL).
uint32_t Queue_Count ( const Queue_T Queue)
Parameters
[in]QueueThe queue structure (must not be equal to NULL).
Returns
number of messages available in the queue
Retcode_T Queue_Create ( Queue_T Queue,
uint8_t *  Buffer,
uint32_t  BufferSize 
)
Parameters
[out]QueueThe queue structure to be initialized (must not be equal to NULL).
[in]BufferThe buffer to be used for storing queue items (must not be equal to NULL).
[in]BufferSizeThe size of provided buffer (must not be equal to zero).
Return values
RETCODE_OKIf the queue was successfully initialized
RETCODE_INVALID_PARAMIf one of the parameters is invalid (NULL pointer or 0 as Buffer Size)
RETCODE_OUT_OF_RESOURCESIf the Queue associated semaphores (Lock and Wakeup, see Queue_T) can't be created
Retcode_T Queue_Delete ( Queue_T Queue)
Parameters
[in]QueueThe queue structure to be deleted (must not be equal to NULL).
Return values
RETCODE_OKIf the queue was successfully deleted
RETCODE_INVALID_PARAMIf the Queue pointer parameter is NULL
Retcode_T Queue_Get ( Queue_T Queue,
void **  Data,
uint32_t *  DataSize,
uint32_t  Timeout 
)
Parameters
[in]QueueThe queue structure (must not be equal to NULL).
[out]DataThe data (item including payload) received from the queue (must not be equal to NULL).
[out]DataSizeThe size of received data (must not be equal to NULL).
[in]TimeoutThe time to wait for a data from the queue in tick periods
Return values
RETCODE_OKIf the data was successfully received from the queue
RETCODE_SEMAPHORE_ERRORIf no data was received within the waiting time
RETCODE_UNEXPECTED_BEHAVIORIf queue is empty
Retcode_T Queue_Purge ( Queue_T Queue)
Parameters
[in]QueueThe queue structure (must not be equal to NULL).
Return values
RETCODE_OKIf received data was successfully purged from the queue
RETCODE_FAILUREIf no data left to be purged
Retcode_T Queue_Put ( Queue_T Queue,
const void *  Item,
uint32_t  ItemSize,
const void *  Payload,
uint32_t  PayloadSize 
)
Parameters
[in]QueueThe queue structure (must not be equal to NULL).
[in]ItemThe item to be added to the queue (must not be equal to NULL)
[in]ItemSizeThe size of given item (must not be equal to zero)
[in]PayloadThe item payload (can be NULL) to be added to the queue
[in]PayloadSizeThe payload size (can be zero)
Return values
RETCODE_OKIf the item with payload was successfully added to the queue
RETCODE_OUT_OF_RESOURCESIf there is no room in the queue buffer to store the item with the payload

All rights reserved. The use is subject to the XDK SDK EULA by Bosch Connected Devices and Solutions GmbH.
This documentation file has been automatically generated on Thu Mar 14 2019 19:12:52 by doxygen 1.8.8