Mistake on this page?
Report an issue in GitHub or email us
Mail.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2017 ARM Limited
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a copy
5  * of this software and associated documentation files (the "Software"), to deal
6  * in the Software without restriction, including without limitation the rights
7  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8  * copies of the Software, and to permit persons to whom the Software is
9  * furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice shall be included in
12  * all copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20  * SOFTWARE.
21  */
22 #ifndef MAIL_H
23 #define MAIL_H
24 
25 #include <stdint.h>
26 #include <string.h>
27 
28 #include "Queue.h"
29 #include "MemoryPool.h"
30 #include "cmsis_os2.h"
31 #include "mbed_rtos_storage.h"
32 #include "mbed_rtos1_types.h"
33 
34 #include "platform/NonCopyable.h"
35 
36 using namespace rtos;
37 
38 namespace rtos {
39 /** \addtogroup rtos */
40 /** @{*/
41 /**
42  * \defgroup rtos_Mail Mail class
43  * @{
44  */
45 
46 /** The Mail class allow to control, send, receive, or wait for mail.
47  A mail is a memory block that is send to a thread or interrupt service routine.
48  @tparam T data type of a single message element.
49  @tparam queue_sz maximum number of messages in queue.
50 
51  @note
52  Memory considerations: The mail data store and control structures will be created on current thread's stack,
53  both for the mbed OS and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).
54 */
55 template<typename T, uint32_t queue_sz>
56 class Mail : private mbed::NonCopyable<Mail<T, queue_sz> > {
57 public:
58  /** Create and Initialize Mail queue.
59  *
60  * @note You cannot call this function from ISR context.
61  */
62  Mail() { };
63 
64  /** Check if the mail queue is empty
65  *
66  * @return True if the mail queue is empty, false if not
67  *
68  * @note You may call this function from ISR context.
69  */
70  bool empty() const {
71  return _queue.empty();
72  }
73 
74  /** Check if the mail queue is full
75  *
76  * @return True if the mail queue is full, false if not
77  *
78  * @note You may call this function from ISR context.
79  */
80  bool full() const {
81  return _queue.full();
82  }
83 
84  /** Allocate a memory block of type T
85  @param millisec timeout value or 0 in case of no time-out. (default: 0).
86  @return pointer to memory block that can be filled with mail or NULL in case error.
87 
88  @note You may call this function from ISR context if the millisec parameter is set to 0.
89  */
90  T* alloc(uint32_t millisec=0) {
91  return _pool.alloc();
92  }
93 
94  /** Allocate a memory block of type T and set memory block to zero.
95  @param millisec timeout value or 0 in case of no time-out. (default: 0).
96  @return pointer to memory block that can be filled with mail or NULL in case error.
97 
98  @note You may call this function from ISR context if the millisec parameter is set to 0.
99  */
100  T* calloc(uint32_t millisec=0) {
101  return _pool.calloc();
102  }
103 
104  /** Put a mail in the queue.
105  @param mptr memory block previously allocated with Mail::alloc or Mail::calloc.
106  @return status code that indicates the execution status of the function.
107 
108  @note You may call this function from ISR context.
109  */
110  osStatus put(T *mptr) {
111  return _queue.put(mptr);
112  }
113 
114  /** Get a mail from a queue.
115  @param millisec timeout value or 0 in case of no time-out. (default: osWaitForever).
116  @return event that contains mail information or error code.
117 
118  @note You may call this function from ISR context if the millisec parameter is set to 0.
119  */
120  osEvent get(uint32_t millisec=osWaitForever) {
121  osEvent evt = _queue.get(millisec);
122  if (evt.status == osEventMessage) {
123  evt.status = osEventMail;
124  }
125  return evt;
126  }
127 
128  /** Free a memory block from a mail.
129  @param mptr pointer to the memory block that was obtained with Mail::get.
130  @return status code that indicates the execution status of the function.
131 
132  @note You may call this function from ISR context.
133  */
134  osStatus free(T *mptr) {
135  return _pool.free(mptr);
136  }
137 
138 private:
139  Queue<T, queue_sz> _queue;
141 };
142 
143 /** @}*/
144 /** @}*/
145 
146 }
147 
148 #endif
149 
150 
151 
bool empty() const
Definition: Mail.h:70
osStatus free(T *block)
Definition: MemoryPool.h:107
T * calloc(uint32_t millisec=0)
Definition: Mail.h:100
T * alloc(void)
Definition: MemoryPool.h:82
Definition: Queue.h:53
T * alloc(uint32_t millisec=0)
Definition: Mail.h:90
bool full() const
Definition: Mail.h:80
Definition: NonCopyable.h:150
Definition: cmsis_os.h:27
osStatus put(T *mptr)
Definition: Mail.h:110
Definition: Mail.h:56
Mail()
Definition: Mail.h:62
T * calloc(void)
Definition: MemoryPool.h:91
osStatus free(T *mptr)
Definition: Mail.h:134
Definition: Kernel.cpp:19
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.