Queue< T, queue_sz > Class Template Reference

The Queue class represents a collection of objects that are stored first by order of priority, and then in first-in, first-out (FIFO) order. More...

#include <Queue.h>

Inheritance diagram for Queue< T, queue_sz >:

Public Member Functions
	Queue ()
	Create and initialize a message Queue of objects of the parameterized type T and maximum capacity specified by queue_sz. More...
	~Queue ()
	Queue destructor. More...
bool	empty () const
	Check if the queue is empty. More...
bool	full () const
	Check if the queue is full. More...
uint32_t	count () const
	Get number of queued messages in the queue. More...
bool	try_put (T *data, uint8_t prio=0)
	Inserts the given element to the end of the queue. More...
bool	try_put_for (Kernel::Clock::duration_u32 rel_time, T *data, uint8_t prio=0)
	Inserts the given element to the end of the queue. More...
osStatus	put (T *data, uint32_t millisec=0, uint8_t prio=0)
	Inserts the given element to the end of the queue. More...
bool	try_get (T **data_out)
	Get a message from the queue. More...
bool	try_get_for (Kernel::Clock::duration_u32 rel_time, T **data_out)
	Get a message or wait for a message from the queue. More...
osEvent	get (uint32_t millisec=osWaitForever)
	Get a message or wait for a message from the queue. More...

Detailed Description

template<typename T, uint32_t queue_sz>
class rtos::Queue< T, queue_sz >

The Queue class represents a collection of objects that are stored first by order of priority, and then in first-in, first-out (FIFO) order.

You can use a queue when you need to store data and then access it in the same order that it has been stored. The order in which you retrieve the data is in order of descending priority. If multiple elements have the same priority, they are retrieved in FIFO order.

The object type stored in the queue can be an integer, pointer or a generic type given by the template parameter T.

Template Parameters

T	Specifies the type of elements stored in the queue.
queue_sz	Maximum number of messages that you can store in the queue.

Note

Memory considerations: The queue control structures are created on the current thread's stack, both for the Mbed OS and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).

Bare metal profile: This class is not supported.

Definition at line 66 of file Queue.h.

Constructor & Destructor Documentation

Queue()

Queue

(

)

Create and initialize a message Queue of objects of the parameterized type T and maximum capacity specified by queue_sz.

Note

You cannot call this function from ISR context.

Definition at line 73 of file Queue.h.

~Queue()

~Queue

(

)

Queue destructor.

Note

You cannot call this function from ISR context.

Definition at line 88 of file Queue.h.

Member Function Documentation

empty()

bool empty

(

)

const

Check if the queue is empty.

Returns

True if the queue is empty, false if not

Note

You may call this function from ISR context.

Definition at line 99 of file Queue.h.

full()

bool full

(

)

const

Check if the queue is full.

Returns

True if the queue is full, false if not

Note

You may call this function from ISR context.

Definition at line 110 of file Queue.h.

count()

uint32_t count

(

)

const

Get number of queued messages in the queue.

Returns

Number of items in the queue

Note

You may call this function from ISR context.

Definition at line 121 of file Queue.h.

try_put()

bool try_put	(	T *	data,
		uint8_t	prio = 0
	)

Inserts the given element to the end of the queue.

This function puts the message pointed to by data into the queue. The parameter prio is used to sort the message according to their priority (higher numbers indicate higher priority) on insertion.

The function does not block, and returns immediately if the queue is full.

Parameters

data	Pointer to the element to insert into the queue.
prio	Priority of the operation or 0 in case of default. (default: 0)

Returns

true if the element was inserted, false otherwise.

Note

You may call this function from ISR context.

Definition at line 142 of file Queue.h.

try_put_for()

bool try_put_for	(	Kernel::Clock::duration_u32	rel_time,
		T *	data,
		uint8_t	prio = 0
	)

Inserts the given element to the end of the queue.

This function puts the message pointed to by data into the queue. The parameter prio is used to sort the message according to their priority (higher numbers indicate higher priority) on insertion.

The timeout indicated by the parameter rel_time specifies how long the function blocks waiting for the message to be inserted into the queue.

The parameter rel_time can have the following values:

• When the duration is 0, the function returns instantly. You could use try_put instead.
• When the duration is Kernel::wait_for_u32_forever, the function waits for an infinite time.
• For all other values, the function waits for the given duration.

Parameters

rel_time	Timeout for the operation to be executed.
data	Pointer to the element to insert into the queue.
prio	Priority of the operation or 0 in case of default. (default: 0)

Returns

true if the element was inserted, false otherwise.

Note

You may call this function from ISR context if the rel_time parameter is set to 0.

Definition at line 175 of file Queue.h.

put()

osStatus put	(	T *	data,
		uint32_t	millisec = 0,
		uint8_t	prio = 0
	)

Inserts the given element to the end of the queue.

This function puts the message pointed to by data into the queue. The parameter prio is used to sort the message according to their priority (higher numbers indicate higher priority) on insertion.

The timeout indicated by the parameter millisec specifies how long the function blocks waiting for the message to be inserted into the queue.

The parameter millisec can have the following values:

• When the timeout is 0, the function returns instantly.
• When the timeout is osWaitForever, the function waits for an infinite time.
• For all other values, the function waits for the given number of milliseconds.

Parameters

data	Pointer to the element to insert into the queue.
millisec	Timeout for the operation to be executed, or 0 in case of no timeout.
prio	Priority of the operation or 0 in case of default. (default: 0)

Returns

Status code that indicates the execution status of the function: osOK The message has been successfully inserted into the queue. osErrorTimeout The message could not be inserted into the queue in the given time. osErrorResource The message could not be inserted because the queue is full. osErrorParameter Internal error or nonzero timeout specified in an ISR.

Note

You may call this function from ISR context if the millisec parameter is set to 0.

Deprecated:

Replaced with try_put and try_put_for. In future put will be an untimed blocking call.

Definition at line 219 of file Queue.h.

try_get()

bool try_get

(

T **

data_out

)

Get a message from the queue.

This function retrieves a message from the queue. The message is stored in the location pointed to be the parameter data_out.

The function does not block, and returns immediately if the queue is empty.

Parameters

[out]

data_out

Pointer to location to write the element retrieved from the queue.

Returns

true if an element was received and written to data_out.

Note

You may call this function from ISR context.

Definition at line 237 of file Queue.h.

try_get_for()

bool try_get_for	(	Kernel::Clock::duration_u32	rel_time,
		T **	data_out
	)

Get a message or wait for a message from the queue.

This function retrieves a message from the queue. The message is stored in the location pointed to be the parameter data_out.

The timeout specified by the parameter rel_time specifies how long the function waits to retrieve the message from the queue.

The timeout parameter can have the following values:

• When the timeout is 0, the function returns instantly.
• When the timeout is Kernel::wait_for_u32_forever, the function waits infinite time until the message is retrieved.
• When the timeout is any other value, the function waits for the specified time before returning a timeout error.

Messages are retrieved in descending priority order. If two messages share the same priority level, they are retrieved in first-in, first-out (FIFO) order.

Parameters

	rel_time	Timeout value.
[out]	data_out	Pointer to location to write the element retrieved from the queue.

Returns

true if an element was received and written to data_out.

Note

You may call this function from ISR context if the rel_time parameter is set to 0.

Definition at line 269 of file Queue.h.

get()

osEvent get

(

uint32_t

millisec = osWaitForever

)

Get a message or wait for a message from the queue.

This function retrieves a message from the queue. The message is stored in the value field of the returned osEvent object.

The timeout specified by the parameter millisec specifies how long the function waits to retrieve the message from the queue.

The timeout parameter can have the following values:

• When the timeout is 0, the function returns instantly.
• When the timeout is osWaitForever (default), the function waits infinite time until the message is retrieved.
• When the timeout is any other value, the function waits for the specified time before returning a timeout error.

Messages are retrieved in descending priority order. If two messages share the same priority level, they are retrieved in first-in, first-out (FIFO) order.

Parameters

millisec

Timeout value.

Returns

Event information that includes the message in event. Message value and the status code in event.status: osEventMessage Message successfully received. osOK No message is available in the queue, and no timeout was specified. osEventTimeout No message was received before a timeout event occurred. osErrorParameter A parameter is invalid or outside of a permitted range.

Note

You may call this function from ISR context if the millisec parameter is set to 0.

Deprecated:

Replaced with try_get and try_get_for. In future get will be an untimed blocking call.

Definition at line 311 of file Queue.h.