Queue.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2012 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 "cmsis_os2.h"
00026 #include "mbed_rtos1_types.h"
00027 #include "mbed_rtos_storage.h"
00028 #include "platform/mbed_error.h"
00029 #include "platform/NonCopyable.h"
00030 
00031 namespace rtos {
00032 /** \addtogroup rtos */
00033 /** @{*/
00034 /**
00035  * \defgroup rtos_Queue Queue class
00036  * @{
00037  */
00038 
00039 /** The Queue class represents a collection of objects that are stored first by
00040  *  order of priority, and then in first-in, first-out (FIFO) order.
00041  *
00042  * You can use a queue when you need to store data and then access it in the same
00043  * order that it has been stored. The order in which you retrieve the data is in
00044  * order of descending priority. If multiple elements have the same priority,
00045  * they are retrieved in FIFO order.
00046  *
00047  * The object type stored in the queue can be an integer, pointer or a generic
00048  * type given by the template parameter T.
00049  *
00050  * @tparam T        Specifies the type of elements stored in the queue.
00051  * @tparam queue_sz Maximum number of messages that you can store in the queue.
00052  *
00053  * @note Memory considerations: The queue control structures are created on the
00054  *       current thread's stack, both for the Mbed OS and underlying RTOS
00055  *       objects (static or dynamic RTOS memory pools are not being used).
00056  *
00057  */
00058 template<typename T, uint32_t queue_sz>
00059 class Queue : private mbed::NonCopyable<Queue<T, queue_sz> > {
00060 public:
00061     /** Create and initialize a message Queue of objects of the parameterized
00062      * type `T` and maximum capacity specified by `queue_sz`.
00063      *
00064      * @note You cannot call this function from ISR context.
00065     */
00066     Queue() {
00067         memset(&_obj_mem, 0, sizeof(_obj_mem));
00068         osMessageQueueAttr_t attr = { 0 };
00069         attr.mq_mem = _queue_mem;
00070         attr.mq_size = sizeof(_queue_mem);
00071         attr.cb_mem = &_obj_mem;
00072         attr.cb_size = sizeof(_obj_mem);
00073         _id = osMessageQueueNew(queue_sz, sizeof(T*), &attr);
00074         MBED_ASSERT(_id);
00075     }
00076 
00077     /** Queue destructor
00078      *
00079      * @note You cannot call this function from ISR context.
00080      */
00081     ~Queue() {
00082         osMessageQueueDelete(_id);
00083     }
00084 
00085     /** Check if the queue is empty.
00086      *
00087      * @return True if the queue is empty, false if not
00088      *
00089      * @note You may call this function from ISR context.
00090      */
00091     bool empty() const {
00092         return osMessageQueueGetCount(_id) == 0;
00093     }
00094 
00095     /** Check if the queue is full.
00096      *
00097      * @return True if the queue is full, false if not
00098      *
00099      * @note You may call this function from ISR context.
00100      */
00101     bool full() const {
00102         return osMessageQueueGetSpace(_id) == 0;
00103     }
00104 
00105     /** Inserts the given element to the end of the queue.
00106      *
00107      * This function puts the message pointed to by `data` into the queue. The
00108      * parameter `prio` is used to sort the message according to their priority
00109      * (higher numbers indicate higher priority) on insertion.
00110      *
00111      * The timeout indicated by the parameter `millisec` specifies how long the
00112      * function blocks waiting for the message to be inserted into the
00113      * queue.
00114      *
00115      * The parameter `millisec` can have the following values:
00116      *  - When the timeout is 0 (the default), the function returns instantly.
00117      *  - When the timeout is osWaitForever, the function waits for an
00118      *    infinite time.
00119      *  - For all other values, the function waits for the given number of
00120      *    milliseconds.
00121      *
00122      * @param  data      Pointer to the element to insert into the queue.
00123      * @param  millisec  Timeout for the operation to be executed, or 0 in case
00124      *                   of no timeout. (default: 0)
00125      * @param  prio      Priority of the operation or 0 in case of default.
00126      *                   (default: 0)
00127      *
00128      * @return Status code that indicates the execution status of the function:
00129      *         @a osOK              The message has been successfully inserted
00130      *                              into the queue.
00131      *         @a osErrorTimeout    The message could not be inserted into the
00132      *                              queue in the given time.
00133      *         @a osErrorResource   The message could not be inserted because
00134      *                              the queue is full.
00135      *         @a osErrorParameter  Internal error or nonzero timeout specified
00136      *                              in an ISR.
00137      *
00138      * @note You may call this function from ISR context if the millisec
00139      *       parameter is set to 0.
00140      *
00141      */
00142     osStatus put(T* data, uint32_t millisec=0, uint8_t prio=0) {
00143         return osMessageQueuePut(_id, &data, prio, millisec);
00144     }
00145 
00146     /** Get a message or wait for a message from the queue.
00147      *
00148      * This function retrieves a message from the queue. The message is stored
00149      * in the value field of the returned `osEvent` object.
00150      *
00151      * The timeout specified by the parameter `millisec` specifies how long the
00152      * function waits to retrieve the message from the queue.
00153      *
00154      * The timeout parameter can have the following values:
00155      *  - When the timeout is 0, the function returns instantly.
00156      *  - When the timeout is osWaitForever (default), the function waits
00157      *    infinite time until the message is retrieved.
00158      *  - When the timeout is any other value, the function waits for the
00159      *    specified time before returning a timeout error.
00160      *
00161      * Messages are retrieved in descending priority order. If two messages
00162      * share the same priority level, they are retrieved in first-in, first-out
00163      * (FIFO) order.
00164      *
00165      * @param   millisec  Timeout value or 0 in case of no time-out.
00166      *                    (default: osWaitForever).
00167      *
00168      * @return Event information that includes the message in event. Message
00169      *         value and the status code in event.status:
00170      *         @a osEventMessage   Message successfully received.
00171      *         @a osOK             No message is available in the queue, and no
00172      *                             timeout was specified.
00173      *         @a osEventTimeout   No message was received before a timeout
00174      *                             event occurred.
00175      *         @a osErrorParameter A parameter is invalid or outside of a
00176      *                             permitted range.
00177      *
00178      * @note  You may call this function from ISR context if the millisec
00179      *        parameter is set to 0.
00180      */
00181     osEvent get(uint32_t millisec=osWaitForever) {
00182         osEvent event;
00183         T *data = NULL;
00184         osStatus_t res = osMessageQueueGet(_id, &data, NULL, millisec);
00185 
00186         switch (res) {
00187             case osOK:
00188                 event.status = (osStatus)osEventMessage;
00189                 event.value.p = data;
00190                 break;
00191             case osErrorResource:
00192                 event.status = osOK;
00193                 break;
00194             case osErrorTimeout:
00195                 event.status = (osStatus)osEventTimeout;
00196                 break;
00197             case osErrorParameter:
00198             default:
00199                 event.status = osErrorParameter;
00200                 break;
00201         }
00202         event.def.message_id = _id;
00203 
00204         return event;
00205     }
00206 
00207 private:
00208     osMessageQueueId_t            _id;
00209     char                          _queue_mem[queue_sz * (sizeof(T*) + sizeof(mbed_rtos_storage_message_t))];
00210     mbed_rtos_storage_msg_queue_t _obj_mem;
00211 };
00212 /** @}*/
00213 /** @}*/
00214 
00215 } // namespace rtos
00216 
00217 #endif // QUEUE_H