Ok

Dependencies:   mbed_rtos_types Mutex mbed_rtos_storage mbed Semaphore

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers Queue.h Source File

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