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 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_STATIC	ETCPAL_QUEUE_HAS_TIMED_FUNCTIONS	ETCPAL_QUEUE_HAS_ISR_FUNCTIONS
FreeRTOS	Yes	No	Yes	Yes
Linux	Yes	No	No	No
macOS	No	No	N/A	N/A
MQX	No	No	N/A	N/A
Windows	Yes	No	Yes	No
Zephyr	Yes	Yes	Yes	Yes

IMPORTANT NOTES FOR ZEPHYR USERS: Some EtcPal features are dependent on Zephyr configuration see: Targeting Zephyr

Macros
#define	ETCPAL_QUEUE_HAS_STATIC   /* platform-defined */
	Whether etcpal_queue_create_static() is meaningful on this platform. More...
#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...
bool	etcpal_queue_create_static (etcpal_queue_t *id, size_t size, size_t item_size, uint8_t *buffer)
	Create a new queue with a buffer provided by the user. 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_STATIC

#define ETCPAL_QUEUE_HAS_STATIC   /* platform-defined */

Whether etcpal_queue_create_static() is meaningful on this platform.

If defined to 0, etcpal_queue_create_static() does nothing and returns false.

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]	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_create_static()

bool etcpal_queue_create_static	(	etcpal_queue_t *	id,
		size_t	size,
		size_t	item_size,
		uint8_t *	buffer
	)

Create a new queue with a buffer provided by the user.

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.
[in]	buffer	The buffer to use for 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_is_full()

bool etcpal_queue_is_full

(

const etcpal_queue_t *

id

)

Determine whether a queue is currently full.

Parameters

[in]

id

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

id

Identifier 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]	id	Identifier for the queue from which to retrieve an item.
[out]	data	Pointer to a location to write the object's data. Must not be NULL.

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]	id	Identifier for the queue from which to retrieve an item.
[out]	data	Pointer to a location to write the object's data. Must not be NULL.

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]

id

Identifier 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]	id	Identifier for the queue to which to add an item.
[in]	data	Pointer to item to add to the queue. Must not be NULL.

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. Must not be NULL.

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]

id

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

id

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

id

Identifier 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]	id	Identifier for the queue from which to retrieve an item.
[out]	data	Pointer to a location to write the object's data. Must not be NULL.
[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. Must not be NULL.
[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.