mbed-os5 only for TYBLE16
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
Diff: rtos/Queue.h
- Revision:
- 0:5b88d5760320
- Child:
- 1:9db0e321a9f4
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/rtos/Queue.h Tue Dec 17 23:23:45 2019 +0000 @@ -0,0 +1,222 @@ +/* mbed Microcontroller Library + * Copyright (c) 2006-2012 ARM Limited + * + * 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 "cmsis_os2.h" +#include "mbed_rtos1_types.h" +#include "mbed_rtos_storage.h" +#include "platform/mbed_error.h" +#include "platform/NonCopyable.h" + +namespace rtos { +/** \addtogroup rtos */ +/** @{*/ +/** + * \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). + * + */ +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; + } + + /** 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 default), 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. (default: 0) + * @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. + * + */ + osStatus put(T *data, uint32_t millisec = 0, uint8_t prio = 0) + { + return osMessageQueuePut(_id, &data, prio, millisec); + } + + /** 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. + * (default: osWaitForever). + * + * @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. + */ + osEvent get(uint32_t millisec = osWaitForever) + { + osEvent event; + T *data = NULL; + osStatus_t res = osMessageQueueGet(_id, &data, NULL, 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 // QUEUE_H