Ok
Dependencies: mbed_rtos_types Mutex mbed_rtos_storage mbed Semaphore
Mail.h
00001 /* mbed Microcontroller Library 00002 * Copyright (c) 2006-2017 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 MAIL_H 00023 #define MAIL_H 00024 00025 #include <stdint.h> 00026 #include <string.h> 00027 00028 #include "rtos/Queue.h" 00029 #include "rtos/MemoryPool.h" 00030 #include "rtos/mbed_rtos_types.h" 00031 #include "rtos/mbed_rtos_storage.h" 00032 #include "rtos/mbed_rtos1_types.h" 00033 00034 #include "platform/mbed_toolchain.h" 00035 #include "platform/NonCopyable.h" 00036 00037 #ifndef MBED_NO_GLOBAL_USING_DIRECTIVE 00038 using namespace rtos; 00039 #endif 00040 00041 #if MBED_CONF_RTOS_PRESENT || defined(DOXYGEN_ONLY) 00042 00043 namespace rtos { 00044 /** \addtogroup rtos */ 00045 /** @{*/ 00046 /** 00047 * \defgroup rtos_Mail Mail class 00048 * @{ 00049 */ 00050 00051 /** The Mail class allows you to control, send, receive or wait for mail. 00052 * A mail is a memory block that is sent to a thread or interrupt service routine (ISR). 00053 * @tparam T Data type of a single mail message element. 00054 * @tparam queue_sz Maximum number of mail messages in queue. 00055 * 00056 * @note 00057 * Memory considerations: The mail data store and control structures are part of this class - they do not (themselves) 00058 * allocate memory on the heap, both for the Mbed OS and underlying RTOS objects (static or dynamic RTOS memory 00059 * pools are not being used). 00060 */ 00061 template<typename T, uint32_t queue_sz> 00062 class Mail : private mbed::NonCopyable<Mail<T, queue_sz> > { 00063 public: 00064 /** Create and initialize Mail queue. 00065 * 00066 * @note You cannot call this function from ISR context. 00067 */ 00068 Mail() { }; 00069 00070 /** Check if the mail queue is empty. 00071 * 00072 * @return State of queue. 00073 * @retval true Mail queue is empty. 00074 * @retval false Mail queue contains mail. 00075 * 00076 * @note You may call this function from ISR context. 00077 */ 00078 bool empty() const 00079 { 00080 return _queue.empty(); 00081 } 00082 00083 /** Check if the mail queue is full. 00084 * 00085 * @return State of queue. 00086 * @retval true Mail queue is full. 00087 * @retval false Mail queue is not full. 00088 * 00089 * @note You may call this function from ISR context. 00090 */ 00091 bool full() const 00092 { 00093 return _queue.full(); 00094 } 00095 00096 /** Allocate a memory block of type T, without blocking. 00097 * 00098 * @param millisec Not used (see note). 00099 * 00100 * @return Pointer to memory block that you can fill with mail or nullptr in case error. 00101 * 00102 * @note You may call this function from ISR context. 00103 * @note If blocking is required, use Mail::alloc_for or Mail::alloc_until 00104 */ 00105 T *alloc(MBED_UNUSED uint32_t millisec = 0) 00106 { 00107 return _pool.alloc(); 00108 } 00109 00110 /** Allocate a memory block of type T, optionally blocking. 00111 * 00112 * @param millisec Timeout value, or osWaitForever. 00113 * 00114 * @return Pointer to memory block that you can fill with mail or nullptr in case error. 00115 * 00116 * @note You may call this function from ISR context if the millisec parameter is set to 0. 00117 */ 00118 T *alloc_for(uint32_t millisec) 00119 { 00120 return _pool.alloc_for(millisec); 00121 } 00122 00123 /** Allocate a memory block of type T, blocking. 00124 * 00125 * @param millisec Absolute timeout time, referenced to Kernel::get_ms_count(). 00126 * 00127 * @return Pointer to memory block that you can fill with mail or nullptr in case error. 00128 * 00129 * @note You cannot call this function from ISR context. 00130 * @note the underlying RTOS may have a limit to the maximum wait time 00131 * due to internal 32-bit computations, but this is guaranteed to work if the 00132 * wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded, 00133 * the wait will time out earlier than specified. 00134 */ 00135 T *alloc_until(uint64_t millisec) 00136 { 00137 return _pool.alloc_until(millisec); 00138 } 00139 00140 /** Allocate a memory block of type T, and set memory block to zero. 00141 * 00142 * @param millisec Not used (see note). 00143 * 00144 * @return Pointer to memory block that you can fill with mail or nullptr in case error. 00145 * 00146 * @note You may call this function from ISR context if the millisec parameter is set to 0. 00147 * @note If blocking is required, use Mail::calloc_for or Mail::calloc_until 00148 */ 00149 T *calloc(MBED_UNUSED uint32_t millisec = 0) 00150 { 00151 return _pool.calloc(); 00152 } 00153 00154 /** Allocate a memory block of type T, optionally blocking, and set memory block to zero. 00155 * 00156 * @param millisec Timeout value, or osWaitForever. 00157 * 00158 * @return Pointer to memory block that you can fill with mail or nullptr in case error. 00159 * 00160 * @note You may call this function from ISR context if the millisec parameter is set to 0. 00161 */ 00162 T *calloc_for(uint32_t millisec) 00163 { 00164 return _pool.calloc_for(millisec); 00165 } 00166 00167 /** Allocate a memory block of type T, blocking, and set memory block to zero. 00168 * 00169 * @param millisec Absolute timeout time, referenced to Kernel::get_ms_count(). 00170 * 00171 * @return Pointer to memory block that you can fill with mail or nullptr in case error. 00172 * 00173 * @note You cannot call this function from ISR context. 00174 * @note the underlying RTOS may have a limit to the maximum wait time 00175 * due to internal 32-bit computations, but this is guaranteed to work if the 00176 * wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded, 00177 * the wait will time out earlier than specified. 00178 */ 00179 T *calloc_until(uint64_t millisec) 00180 { 00181 return _pool.calloc_until(millisec); 00182 } 00183 00184 /** Put a mail in the queue. 00185 * 00186 * @param mptr Memory block previously allocated with Mail::alloc or Mail::calloc. 00187 * 00188 * @return Status code that indicates the execution status of the function (osOK on success). 00189 * 00190 * @note You may call this function from ISR context. 00191 */ 00192 osStatus put(T *mptr) 00193 { 00194 return _queue.put(mptr); 00195 } 00196 00197 /** Get a mail from the queue. 00198 * 00199 * @param millisec Timeout value (default: osWaitForever). 00200 * 00201 * @return Event that contains mail information or error code. 00202 * @retval osEventMessage Message received. 00203 * @retval osOK No mail is available (and no timeout was specified). 00204 * @retval osEventTimeout No mail has arrived during the given timeout period. 00205 * @retval osErrorParameter A parameter is invalid or outside of a permitted range. 00206 * 00207 * @note You may call this function from ISR context if the millisec parameter is set to 0. 00208 */ 00209 osEvent get(uint32_t millisec = osWaitForever) 00210 { 00211 osEvent evt = _queue.get(millisec); 00212 if (evt.status == osEventMessage) { 00213 evt.status = osEventMail; 00214 } 00215 return evt; 00216 } 00217 00218 /** Free a memory block from a mail. 00219 * 00220 * @param mptr Pointer to the memory block that was obtained with Mail::get. 00221 * 00222 * @return Status code that indicates the execution status of the function (osOK on success). 00223 * 00224 * @note You may call this function from ISR context. 00225 */ 00226 osStatus free(T *mptr) 00227 { 00228 return _pool.free(mptr); 00229 } 00230 00231 private: 00232 Queue<T, queue_sz> _queue; 00233 MemoryPool<T, queue_sz> _pool; 00234 }; 00235 00236 /** @}*/ 00237 /** @}*/ 00238 00239 } 00240 00241 #endif 00242 00243 #endif 00244 00245
Generated on Tue Jul 12 2022 22:06:19 by
1.7.2