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;
etcpal_queue_t queue;
 
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");
    }
  }
 
  etcpal_queue_destroy(&queue);
}
 
// Send a new Foo to the queue when an interrupt comes in.
void interrupt_handler(void)
{
  Foo foo;
  foo.value = REG_READ();
  etcpal_queue_send_from_isr(&queue, &foo);
}

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

Queues are only available on RTOS platforms. The current availability is as follows:

Platform	Queue Functions Available
FreeRTOS	Yes
Linux	No
macOS	No
MQX	No
Windows	No

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_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...

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]	id	Queue identifier on which to create a queue. If this function returns true, id becomes valid for calls to other etcpal_queue API functions.
[in]	size	The maximum number of items that can be held in the queue.
[in]	item_size	The 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]

id

Identifier 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]

id

Identifier 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]

id

Identifier for the queue to check the status of.

Returns

true: The queue is empty.

false: The queue is not empty.

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]	id	Identifier for the queue from which to retrieve an item.
[out]	data	Pointer 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_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]	id	Identifier for the queue to which to add an item.
[in]	data	Pointer 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]	id	Identifier for the queue to which to add an item.
[in]	data	Pointer 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_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]	id	Identifier for the queue from which to retrieve an item.
[out]	data	Pointer to a location to write the object's data.
[in]	timeout_ms	Maximum 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]	id	Identifier for the queue to which to add an item.
[in]	data	Pointer to item to add to the queue.
[in]	timeout_ms	Maximum 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.