EtcPal  0.4.1
ETC Platform Abstraction Layer (EtcPal)
View other versions:
queue (RTOS queues)

Overview

Platform-neutral blocking RTOS queues.

#include "etcpal/queue.h"

Provides a platform-neutral API to RTOS queue functionality.

#include "etcpal/queue.h"
typedef struct Foo
{
int value;
} Foo;
void main_task(void* arg)
{
etcpal_error_t res = etcpal_queue_create(&queue, 10, sizeof(Foo));
if (res != kEtcPalErrOk)
{
printf("Queue creation failed: '%s'\n", etcpal_strerror(res));
return;
}
while (true)
{
Foo foo;
// Blocks until a new Foo is retrieved from the queue
if (etcpal_queue_receive(&queue, &foo))
{
printf("Got new Foo with value %d\n", foo.value);
}
else
{
printf("Error receiving from queue.\n");
}
}
}
// Send a new Foo to the queue when an interrupt comes in.
void interrupt_handler(void)
{
Foo foo;
foo.value = REG_READ();
}
const char * etcpal_strerror(etcpal_error_t code)
Get a string representation of an error code.
Definition: error.c:69
etcpal_error_t
A set of error codes that can be returned by library functions.
Definition: error.h:49
@ kEtcPalErrOk
The call was successful, no error occurred.
Definition: error.h:51
bool etcpal_queue_send_from_isr(etcpal_queue_t *id, const void *data)
Add an item to a queue from an interrupt context.
Definition: queue.c:256
PLATFORM_DEFINED etcpal_queue_t
The queue identifier.
Definition: queue.dox:82
bool etcpal_queue_receive(etcpal_queue_t *id, void *data)
Retrieve the first item from a queue.
Definition: queue.c:238
void etcpal_queue_destroy(etcpal_queue_t *id)
Destroy a queue.
Definition: queue.c:191
bool etcpal_queue_create(etcpal_queue_t *id, size_t size, size_t item_size)
Create a new queue.
Definition: queue.c:142

There are also functions for sending and receiving with a timeout, and for checking to see if the queue is empty.

Queues are implemented using native constructs on RTOS platforms, and using other EtcPal constructs such as semaphores on full OS platforms. The current availability is as follows:

Platform Queues Available ETCPAL_QUEUE_HAS_TIMED_FUNCTIONS ETCPAL_QUEUE_HAS_ISR_FUNCTIONS
FreeRTOS Yes Yes Yes
Linux Yes No No
macOS No N/A N/A
MQX No N/A N/A
Windows Yes Yes No

Macros

#define ETCPAL_QUEUE_HAS_TIMED_FUNCTIONS   /* platform-defined */
 Whether etcpal_queue_timed_send() and etcpal_queue_timed_receive() are meaningful on this platform. More...
 
#define ETCPAL_QUEUE_HAS_ISR_FUNCTIONS   /* platform-defined */
 Whether etcpal_queue_send_from_isr() and etcpal_queue_receive_from_isr() are meaningful on this platform. More...
 

Typedefs

typedef PLATFORM_DEFINED etcpal_queue_t
 The queue identifier. More...
 

Functions

bool etcpal_queue_create (etcpal_queue_t *id, size_t size, size_t item_size)
 Create a new queue. More...
 
void etcpal_queue_destroy (etcpal_queue_t *id)
 Destroy a queue. More...
 
bool etcpal_queue_send (etcpal_queue_t *id, const void *data)
 Add an item to a queue. More...
 
bool etcpal_queue_timed_send (etcpal_queue_t *id, const void *data, int timeout_ms)
 Add an item to a queue, giving up after a timeout. More...
 
bool etcpal_queue_send_from_isr (etcpal_queue_t *id, const void *data)
 Add an item to a queue from an interrupt context. More...
 
bool etcpal_queue_receive (etcpal_queue_t *id, void *data)
 Retrieve the first item from a queue. More...
 
bool etcpal_queue_timed_receive (etcpal_queue_t *id, void *data, int timeout_ms)
 Retrieve the first item from a queue, giving up after a timeout. More...
 
bool etcpal_queue_receive_from_isr (etcpal_queue_t *id, void *data)
 Retrieve the first item from a queue from an interrupt context. More...
 
bool etcpal_queue_reset (const etcpal_queue_t *id)
 Resets queue to empty state. More...
 
bool etcpal_queue_is_empty (const etcpal_queue_t *id)
 Determine whether a queue is currently empty. More...
 
bool etcpal_queue_is_empty_from_isr (const etcpal_queue_t *id)
 Determine whether a queue is currently empty from an interrupt context. More...
 
bool etcpal_queue_is_full (const etcpal_queue_t *id)
 Determine whether a queue is currently full. More...
 
bool etcpal_queue_is_full_from_isr (const etcpal_queue_t *id)
 Determine whether a queue is currently full from an interrupt context. More...
 
size_t etcpal_queue_slots_used (const etcpal_queue_t *id)
 Get number of slots being stored in the queue. More...
 
size_t etcpal_queue_slots_used_from_isr (const etcpal_queue_t *id)
 Get number of slots being stored in the queue from an interrupt context. More...
 
size_t etcpal_queue_slots_available (const etcpal_queue_t *id)
 Get number of remaining slots in the queue. More...
 

Macro Definition Documentation

◆ ETCPAL_QUEUE_HAS_ISR_FUNCTIONS

#define ETCPAL_QUEUE_HAS_ISR_FUNCTIONS   /* platform-defined */

Whether etcpal_queue_send_from_isr() and etcpal_queue_receive_from_isr() are meaningful on this platform.

Some platforms have a different method for interacting with a queue from an interrupt context. If defined to 0, etcpal_queue_send_from_isr() and etcpal_queue_receive_from_isr() execute the equivalent of etcpal_queue_send() and etcpal_queue_receive(), respectively.

◆ ETCPAL_QUEUE_HAS_TIMED_FUNCTIONS

#define ETCPAL_QUEUE_HAS_TIMED_FUNCTIONS   /* platform-defined */

Whether etcpal_queue_timed_send() and etcpal_queue_timed_receive() are meaningful on this platform.

If defined to 0, etcpal_queue_timed_send() and etcpal_queue_timed_receive() execute the equivalent of etcpal_queue_send() and etcpal_queue_receive(), respectively, if given nonzero timeouts. With a timeout of 0, they check the queue's availability to send or receive an item and return success or failure immediately.

Typedef Documentation

◆ etcpal_queue_t

typedef PLATFORM_DEFINED etcpal_queue_t

The queue identifier.

Depending on the platform, this could be a scalar type or a struct.

Function Documentation

◆ etcpal_queue_create()

bool etcpal_queue_create ( etcpal_queue_t id,
size_t  size,
size_t  item_size 
)

Create a new queue.

Parameters
[out]idQueue identifier on which to create a queue. If this function returns true, id becomes valid for calls to other etcpal_queue API functions.
[in]sizeThe maximum number of items that can be held in the queue.
[in]item_sizeThe size in bytes of the item type to be held in the queue.
Returns
true: The queue was created.
false: The queue was not created.

◆ etcpal_queue_destroy()

void etcpal_queue_destroy ( etcpal_queue_t id)

Destroy a queue.

Frees the queue's resources back to the operating system.

Parameters
[in]idIdentifier for the queue to destroy.

◆ etcpal_queue_is_empty()

bool etcpal_queue_is_empty ( const etcpal_queue_t id)

Determine whether a queue is currently empty.

Parameters
[in]idIdentifier for the queue to check the status of.
Returns
true: The queue is empty.
false: The queue is not empty.

◆ etcpal_queue_is_empty_from_isr()

bool etcpal_queue_is_empty_from_isr ( const etcpal_queue_t id)

Determine whether a queue is currently empty from an interrupt context.

This function is meaningful on platforms which have a different method for interacting with queues from an interrupt context.

Parameters
[in]idIdentifier for the queue to check the status of.
Returns
true: The queue is empty.
false: The queue is not empty.

◆ etcpal_queue_is_full()

bool etcpal_queue_is_full ( const etcpal_queue_t id)

Determine whether a queue is currently full.

Parameters
[in]idIdentifier for the queue to check the status of.
Returns
true: The queue is full.
false: The queue is not full.

◆ etcpal_queue_is_full_from_isr()

bool etcpal_queue_is_full_from_isr ( const etcpal_queue_t id)

Determine whether a queue is currently full from an interrupt context.

This function is meaningful on platforms which have a different method for interacting with queues from an interrupt context.

Parameters
[in]idIdentifier for the queue to check the status of.
Returns
true: The queue is full.
false: The queue is not full.

◆ etcpal_queue_receive()

bool etcpal_queue_receive ( etcpal_queue_t id,
void *  data 
)

Retrieve the first item from a queue.

Blocks until there is an item available to retrieve from the queue.

Parameters
[in]idIdentifier for the queue from which to retrieve an item.
[out]dataPointer to a location to write the object's data.
Returns
true: Item retrieved successfully.
false: Error occurred while trying to retrieve an item from the queue.

◆ etcpal_queue_receive_from_isr()

bool etcpal_queue_receive_from_isr ( etcpal_queue_t id,
void *  data 
)

Retrieve the first item from a queue from an interrupt context.

This function is meaningful on platforms which have a different method for interacting with queues from an interrupt context. This function never blocks, i.e. the behavior is similar to calling etcpal_queue_timed_receive() with a value of 0 for the timeout_ms parameter.

Parameters
[in]idIdentifier for the queue from which to retrieve an item.
[out]dataPointer to a location to write the object's data.
Returns
true: Item retrieved successfully.
false: Error occurred while trying to retrieve an item from the queue.

◆ etcpal_queue_reset()

bool etcpal_queue_reset ( const etcpal_queue_t id)

Resets queue to empty state.

Parameters
[in]idIdentifier for the queue to check the status of.
Returns
true: On reset success.
false: On reset failure.

◆ etcpal_queue_send()

bool etcpal_queue_send ( etcpal_queue_t id,
const void *  data 
)

Add an item to a queue.

Blocks until there is room in the queue to add a new item.

Parameters
[in]idIdentifier for the queue to which to add an item.
[in]dataPointer to item to add to the queue.
Returns
true: Item added successfully.
false: An error occurred while trying to add an item to the queue.

◆ etcpal_queue_send_from_isr()

bool etcpal_queue_send_from_isr ( etcpal_queue_t id,
const void *  data 
)

Add an item to a queue from an interrupt context.

This function is meaningful on platforms which have a different method for interacting with queues from an interrupt context. This function never blocks, i.e. the behavior is similar to calling etcpal_queue_timed_send() with a value of 0 for the timeout_ms parameter.

Parameters
[in]idIdentifier for the queue to which to add an item.
[in]dataPointer to item to add to the queue.
Returns
true: Item added successfully.
false: Timeout or error occurred while trying to add an item to the queue.

◆ etcpal_queue_slots_available()

size_t etcpal_queue_slots_available ( const etcpal_queue_t id)

Get number of remaining slots in the queue.

Parameters
[in]idIdentifier for the queue to check the status of.
Returns
Number of remaining slots in queue.

◆ etcpal_queue_slots_used()

size_t etcpal_queue_slots_used ( const etcpal_queue_t id)

Get number of slots being stored in the queue.

Parameters
[in]idIdentifier for the queue to check the status of.
Returns
Number of slots in queue.

◆ etcpal_queue_slots_used_from_isr()

size_t etcpal_queue_slots_used_from_isr ( const etcpal_queue_t id)

Get number of slots being stored in the queue from an interrupt context.

This function is meaningful on platforms which have a different method for interacting with queues from an interrupt context.

Parameters
[in]idIdentifier for the queue to check the status of.
Returns
Number of slots in queue.

◆ etcpal_queue_timed_receive()

bool etcpal_queue_timed_receive ( etcpal_queue_t id,
void *  data,
int  timeout_ms 
)

Retrieve the first item from a queue, giving up after a timeout.

Parameters
[in]idIdentifier for the queue from which to retrieve an item.
[out]dataPointer to a location to write the object's data.
[in]timeout_msMaximum amount of time to wait for an item to be available, in milliseconds. If ETCPAL_WAIT_FOREVER is given, the result is the same as if etcpal_queue_receive() was called.
Returns
true: Item retrieved successfully.
false: Timeout or error occurred while trying to retrieve an item from the queue.

◆ etcpal_queue_timed_send()

bool etcpal_queue_timed_send ( etcpal_queue_t id,
const void *  data,
int  timeout_ms 
)

Add an item to a queue, giving up after a timeout.

Parameters
[in]idIdentifier for the queue to which to add an item.
[in]dataPointer to item to add to the queue.
[in]timeout_msMaximum amount of time to wait for space to be available, in milliseconds. If ETCPAL_WAIT_FOREVER is given, the result is the same as if etcpal_queue_send() was called.
Returns
true: Item added successfully.
false: Timeout or error occurred while trying to add an item to the queue.