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