Ok

Dependencies:   mbed_rtos_types Mutex mbed_rtos_storage mbed Semaphore

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers Mail.h Source File

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