Queue.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2019 ARM Limited
00003  *
00004  * Permission is hereby granted, free of charge, to any person obtaining a copy
00005  * of this software and associated documentation files (the "Software"), to deal
00006  * in the Software without restriction, including without limitation the rights
00007  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00008  * copies of the Software, and to permit persons to whom the Software is
00009  * furnished to do so, subject to the following conditions:
00010  *
00011  * The above copyright notice and this permission notice shall be included in
00012  * all copies or substantial portions of the Software.
00013  *
00014  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00015  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00016  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00017  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00018  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00019  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
00020  * SOFTWARE.
00021  */
00022 #ifndef QUEUE_H
00023 #define QUEUE_H
00024 
00025 #include "rtos/mbed_rtos_types.h"
00026 #include "rtos/mbed_rtos1_types.h"
00027 #include "rtos/mbed_rtos_storage.h"
00028 #include "platform/mbed_error.h"
00029 #include "platform/NonCopyable.h"
00030 
00031 #if MBED_CONF_RTOS_PRESENT || defined(DOXYGEN_ONLY)
00032 
00033 namespace rtos {
00034 /** \addtogroup rtos-public-api */
00035 /** @{*/
00036 
00037 /**
00038  * \defgroup rtos_Queue Queue class
00039  * @{
00040  */
00041 
00042 /** The Queue class represents a collection of objects that are stored first by
00043  *  order of priority, and then in first-in, first-out (FIFO) order.
00044  *
00045  * You can use a queue when you need to store data and then access it in the same
00046  * order that it has been stored. The order in which you retrieve the data is in
00047  * order of descending priority. If multiple elements have the same priority,
00048  * they are retrieved in FIFO order.
00049  *
00050  * The object type stored in the queue can be an integer, pointer or a generic
00051  * type given by the template parameter T.
00052  *
00053  * @tparam T        Specifies the type of elements stored in the queue.
00054  * @tparam queue_sz Maximum number of messages that you can store in the queue.
00055  *
00056  * @note Memory considerations: The queue control structures are created on the
00057  *       current thread's stack, both for the Mbed OS and underlying RTOS
00058  *       objects (static or dynamic RTOS memory pools are not being used).
00059  *
00060  */
00061 template<typename T, uint32_t queue_sz>
00062 class Queue : private mbed::NonCopyable<Queue<T, queue_sz> > {
00063 public:
00064     /** Create and initialize a message Queue of objects of the parameterized
00065      * type `T` and maximum capacity specified by `queue_sz`.
00066      *
00067      * @note You cannot call this function from ISR context.
00068     */
00069     Queue()
00070     {
00071         osMessageQueueAttr_t attr = { 0 };
00072         attr.mq_mem = _queue_mem;
00073         attr.mq_size = sizeof(_queue_mem);
00074         attr.cb_mem = &_obj_mem;
00075         attr.cb_size = sizeof(_obj_mem);
00076         _id = osMessageQueueNew(queue_sz, sizeof(T *), &attr);
00077         MBED_ASSERT(_id);
00078     }
00079 
00080     /** Queue destructor
00081      *
00082      * @note You cannot call this function from ISR context.
00083      */
00084     ~Queue()
00085     {
00086         osMessageQueueDelete(_id);
00087     }
00088 
00089     /** Check if the queue is empty.
00090      *
00091      * @return True if the queue is empty, false if not
00092      *
00093      * @note You may call this function from ISR context.
00094      */
00095     bool empty() const
00096     {
00097         return osMessageQueueGetCount(_id) == 0;
00098     }
00099 
00100     /** Check if the queue is full.
00101      *
00102      * @return True if the queue is full, false if not
00103      *
00104      * @note You may call this function from ISR context.
00105      */
00106     bool full() const
00107     {
00108         return osMessageQueueGetSpace(_id) == 0;
00109     }
00110 
00111     /** Get number of queued messages in the queue.
00112      *
00113      * @return Number of items in the queue
00114      *
00115      * @note You may call this function from ISR context.
00116      */
00117     uint32_t count() const
00118     {
00119         return osMessageQueueGetCount(_id);
00120     }
00121 
00122     /** Inserts the given element to the end of the queue.
00123      *
00124      * This function puts the message pointed to by `data` into the queue. The
00125      * parameter `prio` is used to sort the message according to their priority
00126      * (higher numbers indicate higher priority) on insertion.
00127      *
00128      * The timeout indicated by the parameter `millisec` specifies how long the
00129      * function blocks waiting for the message to be inserted into the
00130      * queue.
00131      *
00132      * The parameter `millisec` can have the following values:
00133      *  - When the timeout is 0 (the default), the function returns instantly.
00134      *  - When the timeout is osWaitForever, the function waits for an
00135      *    infinite time.
00136      *  - For all other values, the function waits for the given number of
00137      *    milliseconds.
00138      *
00139      * @param  data      Pointer to the element to insert into the queue.
00140      * @param  millisec  Timeout for the operation to be executed, or 0 in case
00141      *                   of no timeout. (default: 0)
00142      * @param  prio      Priority of the operation or 0 in case of default.
00143      *                   (default: 0)
00144      *
00145      * @return Status code that indicates the execution status of the function:
00146      *         @a osOK              The message has been successfully inserted
00147      *                              into the queue.
00148      *         @a osErrorTimeout    The message could not be inserted into the
00149      *                              queue in the given time.
00150      *         @a osErrorResource   The message could not be inserted because
00151      *                              the queue is full.
00152      *         @a osErrorParameter  Internal error or nonzero timeout specified
00153      *                              in an ISR.
00154      *
00155      * @note You may call this function from ISR context if the millisec
00156      *       parameter is set to 0.
00157      *
00158      */
00159     osStatus put(T *data, uint32_t millisec = 0, uint8_t prio = 0)
00160     {
00161         return osMessageQueuePut(_id, &data, prio, millisec);
00162     }
00163 
00164     /** Get a message or wait for a message from the queue.
00165      *
00166      * This function retrieves a message from the queue. The message is stored
00167      * in the value field of the returned `osEvent` object.
00168      *
00169      * The timeout specified by the parameter `millisec` specifies how long the
00170      * function waits to retrieve the message from the queue.
00171      *
00172      * The timeout parameter can have the following values:
00173      *  - When the timeout is 0, the function returns instantly.
00174      *  - When the timeout is osWaitForever (default), the function waits
00175      *    infinite time until the message is retrieved.
00176      *  - When the timeout is any other value, the function waits for the
00177      *    specified time before returning a timeout error.
00178      *
00179      * Messages are retrieved in descending priority order. If two messages
00180      * share the same priority level, they are retrieved in first-in, first-out
00181      * (FIFO) order.
00182      *
00183      * @param   millisec  Timeout value.
00184      *                    (default: osWaitForever).
00185      *
00186      * @return Event information that includes the message in event. Message
00187      *         value and the status code in event.status:
00188      *         @a osEventMessage   Message successfully received.
00189      *         @a osOK             No message is available in the queue, and no
00190      *                             timeout was specified.
00191      *         @a osEventTimeout   No message was received before a timeout
00192      *                             event occurred.
00193      *         @a osErrorParameter A parameter is invalid or outside of a
00194      *                             permitted range.
00195      *
00196      * @note  You may call this function from ISR context if the millisec
00197      *        parameter is set to 0.
00198      */
00199     osEvent get(uint32_t millisec = osWaitForever)
00200     {
00201         osEvent event;
00202         T *data = nullptr;
00203         osStatus_t  res = osMessageQueueGet(_id, &data, nullptr, millisec);
00204 
00205         switch (res) {
00206             case osOK:
00207                 event.status = (osStatus)osEventMessage;
00208                 event.value.p = data;
00209                 break;
00210             case osErrorResource:
00211                 event.status = osOK;
00212                 break;
00213             case osErrorTimeout:
00214                 event.status = (osStatus)osEventTimeout;
00215                 break;
00216             case osErrorParameter:
00217             default:
00218                 event.status = osErrorParameter;
00219                 break;
00220         }
00221         event.def.message_id = _id;
00222 
00223         return event;
00224     }
00225 
00226 private:
00227     osMessageQueueId_t            _id;
00228     char                          _queue_mem[queue_sz * (sizeof(T *) + sizeof(mbed_rtos_storage_message_t))];
00229     mbed_rtos_storage_msg_queue_t _obj_mem;
00230 };
00231 /** @}*/
00232 /** @}*/
00233 
00234 } // namespace rtos
00235 
00236 #endif
00237 
00238 #endif // QUEUE_H