Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
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
Generated on Tue Jul 12 2022 13:54:46 by
