/* mbed Microcontroller Library
* Copyright (c) 2006-2019 ARM Limited
* SPDX-License-Identifier: MIT
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
#ifndef QUEUE_H
#define QUEUE_H
#include "rtos/mbed_rtos_types.h"
#include "rtos/internal/mbed_rtos1_types.h"
#include "rtos/internal/mbed_rtos_storage.h"
#include "rtos/Kernel.h"
#include "platform/mbed_error.h"
#include "platform/NonCopyable.h"
#include "platform/mbed_assert.h"
#if MBED_CONF_RTOS_PRESENT || defined(DOXYGEN_ONLY)
namespace rtos {
/** \addtogroup rtos-public-api */
/** @{*/
/**
* \defgroup rtos_Queue Queue class
* @{
*/
/** 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.
*
* @tparam T Specifies the type of elements stored in the queue.
* @tparam 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).
*
* @note Bare metal profile: This class is not supported.
*/
template<typename T, uint32_t queue_sz>
class Queue : private mbed::NonCopyable<Queue<T, queue_sz> > {
public:
/** 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.
*/
Queue()
{
osMessageQueueAttr_t attr = { 0 };
attr.mq_mem = _queue_mem;
attr.mq_size = sizeof(_queue_mem);
attr.cb_mem = &_obj_mem;
attr.cb_size = sizeof(_obj_mem);
_id = osMessageQueueNew(queue_sz, sizeof(T *), &attr);
MBED_ASSERT(_id);
}
/** Queue destructor
*
* @note You cannot call this function from ISR context.
*/
~Queue()
{
osMessageQueueDelete(_id);
}
/** Check if the queue is empty.
*
* @return True if the queue is empty, false if not
*
* @note You may call this function from ISR context.
*/
bool empty() const
{
return osMessageQueueGetCount(_id) == 0;
}
/** Check if the queue is full.
*
* @return True if the queue is full, false if not
*
* @note You may call this function from ISR context.
*/
bool full() const
{
return osMessageQueueGetSpace(_id) == 0;
}
/** Get number of queued messages in the queue.
*
* @return Number of items in the queue
*
* @note You may call this function from ISR context.
*/
uint32_t count() const
{
return osMessageQueueGetCount(_id);
}
/** 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.
*
* @param data Pointer to the element to insert into the queue.
* @param prio Priority of the operation or 0 in case of default.
* (default: 0)
*
* @return true if the element was inserted, false otherwise.
*
* @note You may call this function from ISR context.
*/
bool try_put(T *data, uint8_t prio = 0)
{
return try_put_for(Kernel::Clock::duration_u32::zero(), data, prio);
}
/** 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.
*
* @param rel_time Timeout for the operation to be executed.
* @param data Pointer to the element to insert into the queue.
* @param prio Priority of the operation or 0 in case of default.
* (default: 0)
*
* @return 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.
*
*/
bool try_put_for(Kernel::Clock::duration_u32 rel_time, T *data, uint8_t prio = 0)
{
osStatus status = osMessageQueuePut(_id, &data, prio, rel_time.count());
return status == osOK;
}
/** 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.
*
* @param data Pointer to the element to insert into the queue.
* @param millisec Timeout for the operation to be executed, or 0 in case
* of no timeout.
* @param prio Priority of the operation or 0 in case of default.
* (default: 0)
*
* @return Status code that indicates the execution status of the function:
* @a osOK The message has been successfully inserted
* into the queue.
* @a osErrorTimeout The message could not be inserted into the
* queue in the given time.
* @a osErrorResource The message could not be inserted because
* the queue is full.
* @a 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.
*/
MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Replaced with try_put and try_put_for. In future put will be an untimed blocking call.")
osStatus put(T *data, uint32_t millisec = 0, uint8_t prio = 0)
{
return osMessageQueuePut(_id, &data, prio, millisec);
}
/** 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.
*
* @param[out] data_out Pointer to location to write the element retrieved from the queue.
*
* @return true if an element was received and written to data_out.
*
* @note You may call this function from ISR context.
*/
bool try_get(T **data_out)
{
return try_get_for(Kernel::Clock::duration_u32::zero(), 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.
*
* @param rel_time Timeout value.
* @param[out] data_out Pointer to location to write the element retrieved from the queue.
*
* @return 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.
*/
bool try_get_for(Kernel::Clock::duration_u32 rel_time, T **data_out)
{
osStatus status = osMessageQueueGet(_id, data_out, nullptr, rel_time.count());
return status == osOK;
}
/** 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.
*
* @param millisec Timeout value.
*
* @return Event information that includes the message in event. Message
* value and the status code in event.status:
* @a osEventMessage Message successfully received.
* @a osOK No message is available in the queue, and no
* timeout was specified.
* @a osEventTimeout No message was received before a timeout
* event occurred.
* @a 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.
*/
MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Replaced with try_get and try_get_for. In future get will be an untimed blocking call.")
osEvent get(uint32_t millisec = osWaitForever)
{
osEvent event;
T *data = nullptr;
osStatus_t res = osMessageQueueGet(_id, &data, nullptr, millisec);
switch (res) {
case osOK:
event.status = (osStatus)osEventMessage;
event.value.p = data;
break;
case osErrorResource:
event.status = osOK;
break;
case osErrorTimeout:
event.status = (osStatus)osEventTimeout;
break;
case osErrorParameter:
default:
event.status = osErrorParameter;
break;
}
event.def.message_id = _id;
return event;
}
private:
osMessageQueueId_t _id;
char _queue_mem[queue_sz * (sizeof(T *) + sizeof(mbed_rtos_storage_message_t))];
mbed_rtos_storage_msg_queue_t _obj_mem;
};
/** @}*/
/** @}*/
} // namespace rtos
#endif
#endif // QUEUE_H
