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 "Queue.h"
00029 #include "MemoryPool.h"
00030 #include "cmsis_os2.h"
00031 #include "mbed_rtos_storage.h"
00032 #include "mbed_rtos1_types.h"
00033 
00034 #include "platform/NonCopyable.h"
00035 
00036 using namespace rtos;
00037 
00038 namespace rtos {
00039 /** \addtogroup rtos */
00040 /** @{*/
00041 /**
00042  * \defgroup rtos_Mail Mail class
00043  * @{
00044  */
00045  
00046 /** The Mail class allow to control, send, receive, or wait for mail.
00047  A mail is a memory block that is send to a thread or interrupt service routine.
00048   @tparam  T         data type of a single message element.
00049   @tparam  queue_sz  maximum number of messages in queue.
00050 
00051  @note
00052  Memory considerations: The mail data store and control structures will be created on current thread's stack,
00053  both for the mbed OS and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).
00054 */
00055 template<typename T, uint32_t queue_sz>
00056 class Mail : private mbed::NonCopyable<Mail<T, queue_sz> > {
00057 public:
00058     /** Create and Initialize Mail queue.
00059      *
00060      * @note You cannot call this function from ISR context.
00061     */
00062     Mail() { };
00063 
00064     /** Check if the mail queue is empty
00065      *
00066      * @return True if the mail queue is empty, false if not
00067      *
00068      * @note You may call this function from ISR context.
00069      */
00070     bool empty() const {
00071         return _queue.empty();
00072     }
00073 
00074     /** Check if the mail queue is full
00075      *
00076      * @return True if the mail queue is full, false if not
00077      *
00078      * @note You may call this function from ISR context.
00079      */
00080     bool full() const {
00081         return _queue.full();
00082     }
00083 
00084     /** Allocate a memory block of type T
00085       @param   millisec  timeout value or 0 in case of no time-out. (default: 0).
00086       @return  pointer to memory block that can be filled with mail or NULL in case error.
00087 
00088       @note You may call this function from ISR context if the millisec parameter is set to 0.
00089     */
00090     T* alloc(uint32_t millisec=0) {
00091         return _pool.alloc();
00092     }
00093 
00094     /** Allocate a memory block of type T and set memory block to zero.
00095       @param   millisec  timeout value or 0 in case of no time-out.  (default: 0).
00096       @return  pointer to memory block that can be filled with mail or NULL in case error.
00097 
00098       @note You may call this function from ISR context if the millisec parameter is set to 0.
00099     */
00100     T* calloc(uint32_t millisec=0) {
00101         return _pool.calloc();
00102     }
00103 
00104     /** Put a mail in the queue.
00105       @param   mptr  memory block previously allocated with Mail::alloc or Mail::calloc.
00106       @return  status code that indicates the execution status of the function.
00107 
00108       @note You may call this function from ISR context.
00109     */
00110     osStatus put(T *mptr) {
00111         return _queue.put(mptr);
00112     }
00113 
00114     /** Get a mail from a queue.
00115       @param   millisec  timeout value or 0 in case of no time-out. (default: osWaitForever).
00116       @return  event that contains mail information or error code.
00117 
00118       @note You may call this function from ISR context if the millisec parameter is set to 0.
00119     */
00120     osEvent get(uint32_t millisec=osWaitForever) {
00121         osEvent evt = _queue.get(millisec);
00122         if (evt.status == osEventMessage) {
00123             evt.status = osEventMail;
00124         }
00125         return evt;
00126     }
00127 
00128     /** Free a memory block from a mail.
00129       @param   mptr  pointer to the memory block that was obtained with Mail::get.
00130       @return  status code that indicates the execution status of the function.
00131 
00132       @note You may call this function from ISR context.
00133     */
00134     osStatus free(T *mptr) {
00135         return _pool.free(mptr);
00136     }
00137 
00138 private:
00139     Queue<T, queue_sz> _queue;
00140     MemoryPool<T, queue_sz>  _pool;
00141 };
00142 
00143 /** @}*/
00144 /** @}*/
00145 
00146 }
00147 
00148 #endif
00149 
00150 
00151