Kev Mann / mbed-dev-OS5_10_4

RTC auf true

rtos/Queue.h@2:7aab896b1a3b, 2019-03-13 (annotated)

Committer:
kevman
Date:
Wed Mar 13 11:03:24 2019 +0000
Revision:
2:7aab896b1a3b
Parent:
0:38ceb79fef03 
2019-03-13

Who changed what in which revision?

UserRevisionLine numberNew contents of line
kevman 0:38ceb79fef03 1 /* mbed Microcontroller Library
kevman 0:38ceb79fef03 2 * Copyright (c) 2006-2012 ARM Limited
kevman 0:38ceb79fef03 3 *
kevman 0:38ceb79fef03 4 * Permission is hereby granted, free of charge, to any person obtaining a copy
kevman 0:38ceb79fef03 5 * of this software and associated documentation files (the "Software"), to deal
kevman 0:38ceb79fef03 6 * in the Software without restriction, including without limitation the rights
kevman 0:38ceb79fef03 7 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
kevman 0:38ceb79fef03 8 * copies of the Software, and to permit persons to whom the Software is
kevman 0:38ceb79fef03 9 * furnished to do so, subject to the following conditions:
kevman 0:38ceb79fef03 10 *
kevman 0:38ceb79fef03 11 * The above copyright notice and this permission notice shall be included in
kevman 0:38ceb79fef03 12 * all copies or substantial portions of the Software.
kevman 0:38ceb79fef03 13 *
kevman 0:38ceb79fef03 14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
kevman 0:38ceb79fef03 15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
kevman 0:38ceb79fef03 16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
kevman 0:38ceb79fef03 17 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
kevman 0:38ceb79fef03 18 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
kevman 0:38ceb79fef03 19 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
kevman 0:38ceb79fef03 20 * SOFTWARE.
kevman 0:38ceb79fef03 21 */
kevman 0:38ceb79fef03 22 #ifndef QUEUE_H
kevman 0:38ceb79fef03 23 #define QUEUE_H
kevman 0:38ceb79fef03 24
kevman 0:38ceb79fef03 25 #include "cmsis_os2.h"
kevman 0:38ceb79fef03 26 #include "mbed_rtos1_types.h"
kevman 0:38ceb79fef03 27 #include "mbed_rtos_storage.h"
kevman 0:38ceb79fef03 28 #include "platform/mbed_error.h"
kevman 0:38ceb79fef03 29 #include "platform/NonCopyable.h"
kevman 0:38ceb79fef03 30
kevman 0:38ceb79fef03 31 namespace rtos {
kevman 0:38ceb79fef03 32 /** \addtogroup rtos */
kevman 0:38ceb79fef03 33 /** @{*/
kevman 0:38ceb79fef03 34 /**
kevman 0:38ceb79fef03 35 * \defgroup rtos_Queue Queue class
kevman 0:38ceb79fef03 36 * @{
kevman 0:38ceb79fef03 37 */
kevman 0:38ceb79fef03 38
kevman 0:38ceb79fef03 39 /** The Queue class represents a collection of objects that are stored first by
kevman 0:38ceb79fef03 40 * order of priority, and then in first-in, first-out (FIFO) order.
kevman 0:38ceb79fef03 41 *
kevman 0:38ceb79fef03 42 * You can use a queue when you need to store data and then access it in the same
kevman 0:38ceb79fef03 43 * order that it has been stored. The order in which you retrieve the data is in
kevman 0:38ceb79fef03 44 * order of descending priority. If multiple elements have the same priority,
kevman 0:38ceb79fef03 45 * they are retrieved in FIFO order.
kevman 0:38ceb79fef03 46 *
kevman 0:38ceb79fef03 47 * The object type stored in the queue can be an integer, pointer or a generic
kevman 0:38ceb79fef03 48 * type given by the template parameter T.
kevman 0:38ceb79fef03 49 *
kevman 0:38ceb79fef03 50 * @tparam T Specifies the type of elements stored in the queue.
kevman 0:38ceb79fef03 51 * @tparam queue_sz Maximum number of messages that you can store in the queue.
kevman 0:38ceb79fef03 52 *
kevman 0:38ceb79fef03 53 * @note Memory considerations: The queue control structures are created on the
kevman 0:38ceb79fef03 54 * current thread's stack, both for the Mbed OS and underlying RTOS
kevman 0:38ceb79fef03 55 * objects (static or dynamic RTOS memory pools are not being used).
kevman 0:38ceb79fef03 56 *
kevman 0:38ceb79fef03 57 */
kevman 0:38ceb79fef03 58 template<typename T, uint32_t queue_sz>
kevman 0:38ceb79fef03 59 class Queue : private mbed::NonCopyable<Queue<T, queue_sz> > {
kevman 0:38ceb79fef03 60 public:
kevman 0:38ceb79fef03 61 /** Create and initialize a message Queue of objects of the parameterized
kevman 0:38ceb79fef03 62 * type `T` and maximum capacity specified by `queue_sz`.
kevman 0:38ceb79fef03 63 *
kevman 0:38ceb79fef03 64 * @note You cannot call this function from ISR context.
kevman 0:38ceb79fef03 65 */
kevman 0:38ceb79fef03 66 Queue() {
kevman 0:38ceb79fef03 67 memset(&_obj_mem, 0, sizeof(_obj_mem));
kevman 0:38ceb79fef03 68 osMessageQueueAttr_t attr = { 0 };
kevman 0:38ceb79fef03 69 attr.mq_mem = _queue_mem;
kevman 0:38ceb79fef03 70 attr.mq_size = sizeof(_queue_mem);
kevman 0:38ceb79fef03 71 attr.cb_mem = &_obj_mem;
kevman 0:38ceb79fef03 72 attr.cb_size = sizeof(_obj_mem);
kevman 0:38ceb79fef03 73 _id = osMessageQueueNew(queue_sz, sizeof(T*), &attr);
kevman 0:38ceb79fef03 74 MBED_ASSERT(_id);
kevman 0:38ceb79fef03 75 }
kevman 0:38ceb79fef03 76
kevman 0:38ceb79fef03 77 /** Queue destructor
kevman 0:38ceb79fef03 78 *
kevman 0:38ceb79fef03 79 * @note You cannot call this function from ISR context.
kevman 0:38ceb79fef03 80 */
kevman 0:38ceb79fef03 81 ~Queue() {
kevman 0:38ceb79fef03 82 osMessageQueueDelete(_id);
kevman 0:38ceb79fef03 83 }
kevman 0:38ceb79fef03 84
kevman 0:38ceb79fef03 85 /** Check if the queue is empty.
kevman 0:38ceb79fef03 86 *
kevman 0:38ceb79fef03 87 * @return True if the queue is empty, false if not
kevman 0:38ceb79fef03 88 *
kevman 0:38ceb79fef03 89 * @note You may call this function from ISR context.
kevman 0:38ceb79fef03 90 */
kevman 0:38ceb79fef03 91 bool empty() const {
kevman 0:38ceb79fef03 92 return osMessageQueueGetCount(_id) == 0;
kevman 0:38ceb79fef03 93 }
kevman 0:38ceb79fef03 94
kevman 0:38ceb79fef03 95 /** Check if the queue is full.
kevman 0:38ceb79fef03 96 *
kevman 0:38ceb79fef03 97 * @return True if the queue is full, false if not
kevman 0:38ceb79fef03 98 *
kevman 0:38ceb79fef03 99 * @note You may call this function from ISR context.
kevman 0:38ceb79fef03 100 */
kevman 0:38ceb79fef03 101 bool full() const {
kevman 0:38ceb79fef03 102 return osMessageQueueGetSpace(_id) == 0;
kevman 0:38ceb79fef03 103 }
kevman 0:38ceb79fef03 104
kevman 0:38ceb79fef03 105 /** Inserts the given element to the end of the queue.
kevman 0:38ceb79fef03 106 *
kevman 0:38ceb79fef03 107 * This function puts the message pointed to by `data` into the queue. The
kevman 0:38ceb79fef03 108 * parameter `prio` is used to sort the message according to their priority
kevman 0:38ceb79fef03 109 * (higher numbers indicate higher priority) on insertion.
kevman 0:38ceb79fef03 110 *
kevman 0:38ceb79fef03 111 * The timeout indicated by the parameter `millisec` specifies how long the
kevman 0:38ceb79fef03 112 * function blocks waiting for the message to be inserted into the
kevman 0:38ceb79fef03 113 * queue.
kevman 0:38ceb79fef03 114 *
kevman 0:38ceb79fef03 115 * The parameter `millisec` can have the following values:
kevman 0:38ceb79fef03 116 * - When the timeout is 0 (the default), the function returns instantly.
kevman 0:38ceb79fef03 117 * - When the timeout is osWaitForever, the function waits for an
kevman 0:38ceb79fef03 118 * infinite time.
kevman 0:38ceb79fef03 119 * - For all other values, the function waits for the given number of
kevman 0:38ceb79fef03 120 * milliseconds.
kevman 0:38ceb79fef03 121 *
kevman 0:38ceb79fef03 122 * @param data Pointer to the element to insert into the queue.
kevman 0:38ceb79fef03 123 * @param millisec Timeout for the operation to be executed, or 0 in case
kevman 0:38ceb79fef03 124 * of no timeout. (default: 0)
kevman 0:38ceb79fef03 125 * @param prio Priority of the operation or 0 in case of default.
kevman 0:38ceb79fef03 126 * (default: 0)
kevman 0:38ceb79fef03 127 *
kevman 0:38ceb79fef03 128 * @return Status code that indicates the execution status of the function:
kevman 0:38ceb79fef03 129 * @a osOK The message has been successfully inserted
kevman 0:38ceb79fef03 130 * into the queue.
kevman 0:38ceb79fef03 131 * @a osErrorTimeout The message could not be inserted into the
kevman 0:38ceb79fef03 132 * queue in the given time.
kevman 0:38ceb79fef03 133 * @a osErrorResource The message could not be inserted because
kevman 0:38ceb79fef03 134 * the queue is full.
kevman 0:38ceb79fef03 135 * @a osErrorParameter Internal error or nonzero timeout specified
kevman 0:38ceb79fef03 136 * in an ISR.
kevman 0:38ceb79fef03 137 *
kevman 0:38ceb79fef03 138 * @note You may call this function from ISR context if the millisec
kevman 0:38ceb79fef03 139 * parameter is set to 0.
kevman 0:38ceb79fef03 140 *
kevman 0:38ceb79fef03 141 */
kevman 0:38ceb79fef03 142 osStatus put(T* data, uint32_t millisec=0, uint8_t prio=0) {
kevman 0:38ceb79fef03 143 return osMessageQueuePut(_id, &data, prio, millisec);
kevman 0:38ceb79fef03 144 }
kevman 0:38ceb79fef03 145
kevman 0:38ceb79fef03 146 /** Get a message or wait for a message from the queue.
kevman 0:38ceb79fef03 147 *
kevman 0:38ceb79fef03 148 * This function retrieves a message from the queue. The message is stored
kevman 0:38ceb79fef03 149 * in the value field of the returned `osEvent` object.
kevman 0:38ceb79fef03 150 *
kevman 0:38ceb79fef03 151 * The timeout specified by the parameter `millisec` specifies how long the
kevman 0:38ceb79fef03 152 * function waits to retrieve the message from the queue.
kevman 0:38ceb79fef03 153 *
kevman 0:38ceb79fef03 154 * The timeout parameter can have the following values:
kevman 0:38ceb79fef03 155 * - When the timeout is 0, the function returns instantly.
kevman 0:38ceb79fef03 156 * - When the timeout is osWaitForever (default), the function waits
kevman 0:38ceb79fef03 157 * infinite time until the message is retrieved.
kevman 0:38ceb79fef03 158 * - When the timeout is any other value, the function waits for the
kevman 0:38ceb79fef03 159 * specified time before returning a timeout error.
kevman 0:38ceb79fef03 160 *
kevman 0:38ceb79fef03 161 * Messages are retrieved in descending priority order. If two messages
kevman 0:38ceb79fef03 162 * share the same priority level, they are retrieved in first-in, first-out
kevman 0:38ceb79fef03 163 * (FIFO) order.
kevman 0:38ceb79fef03 164 *
kevman 0:38ceb79fef03 165 * @param millisec Timeout value or 0 in case of no time-out.
kevman 0:38ceb79fef03 166 * (default: osWaitForever).
kevman 0:38ceb79fef03 167 *
kevman 0:38ceb79fef03 168 * @return Event information that includes the message in event. Message
kevman 0:38ceb79fef03 169 * value and the status code in event.status:
kevman 0:38ceb79fef03 170 * @a osEventMessage Message successfully received.
kevman 0:38ceb79fef03 171 * @a osOK No message is available in the queue, and no
kevman 0:38ceb79fef03 172 * timeout was specified.
kevman 0:38ceb79fef03 173 * @a osEventTimeout No message was received before a timeout
kevman 0:38ceb79fef03 174 * event occurred.
kevman 0:38ceb79fef03 175 * @a osErrorParameter A parameter is invalid or outside of a
kevman 0:38ceb79fef03 176 * permitted range.
kevman 0:38ceb79fef03 177 *
kevman 0:38ceb79fef03 178 * @note You may call this function from ISR context if the millisec
kevman 0:38ceb79fef03 179 * parameter is set to 0.
kevman 0:38ceb79fef03 180 */
kevman 0:38ceb79fef03 181 osEvent get(uint32_t millisec=osWaitForever) {
kevman 0:38ceb79fef03 182 osEvent event;
kevman 0:38ceb79fef03 183 T *data = NULL;
kevman 0:38ceb79fef03 184 osStatus_t res = osMessageQueueGet(_id, &data, NULL, millisec);
kevman 0:38ceb79fef03 185
kevman 0:38ceb79fef03 186 switch (res) {
kevman 0:38ceb79fef03 187 case osOK:
kevman 0:38ceb79fef03 188 event.status = (osStatus)osEventMessage;
kevman 0:38ceb79fef03 189 event.value.p = data;
kevman 0:38ceb79fef03 190 break;
kevman 0:38ceb79fef03 191 case osErrorResource:
kevman 0:38ceb79fef03 192 event.status = osOK;
kevman 0:38ceb79fef03 193 break;
kevman 0:38ceb79fef03 194 case osErrorTimeout:
kevman 0:38ceb79fef03 195 event.status = (osStatus)osEventTimeout;
kevman 0:38ceb79fef03 196 break;
kevman 0:38ceb79fef03 197 case osErrorParameter:
kevman 0:38ceb79fef03 198 default:
kevman 0:38ceb79fef03 199 event.status = osErrorParameter;
kevman 0:38ceb79fef03 200 break;
kevman 0:38ceb79fef03 201 }
kevman 0:38ceb79fef03 202 event.def.message_id = _id;
kevman 0:38ceb79fef03 203
kevman 0:38ceb79fef03 204 return event;
kevman 0:38ceb79fef03 205 }
kevman 0:38ceb79fef03 206
kevman 0:38ceb79fef03 207 private:
kevman 0:38ceb79fef03 208 osMessageQueueId_t _id;
kevman 0:38ceb79fef03 209 char _queue_mem[queue_sz * (sizeof(T*) + sizeof(mbed_rtos_storage_message_t))];
kevman 0:38ceb79fef03 210 mbed_rtos_storage_msg_queue_t _obj_mem;
kevman 0:38ceb79fef03 211 };
kevman 0:38ceb79fef03 212 /** @}*/
kevman 0:38ceb79fef03 213 /** @}*/
kevman 0:38ceb79fef03 214
kevman 0:38ceb79fef03 215 } // namespace rtos
kevman 0:38ceb79fef03 216
kevman 0:38ceb79fef03 217 #endif // QUEUE_H