Mbed OS Reference
Loading...
Searching...
No Matches
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 >:
NonCopyable< 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
TSpecifies the type of elements stored in the queue.
queue_szMaximum 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
dataPointer to the element to insert into the queue.
prioPriority 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_timeTimeout for the operation to be executed.
dataPointer to the element to insert into the queue.
prioPriority 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
dataPointer to the element to insert into the queue.
millisecTimeout for the operation to be executed, or 0 in case of no timeout.
prioPriority 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_outPointer 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_timeTimeout value.
[out]data_outPointer 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
millisecTimeout 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.