cocoOS  4.0.0
docMessages.h
Go to the documentation of this file.
1 
24  uint8_t led;
25 } LedMsg_t;
26 
27 void task( void ) {
28  static LedMsg_t ledMsg;
29 
30  ledMsg.super.signal = LED_ON_SIG;
31  ledMsg.led = 0;
32 
33  task_open();
34  ...
35  task_close();
36 }
37 @endcode
38 
39 <b>Message passing</b> @n
40 Messages are passed between tasks by copying the message into a message queue. The posted message must
41 be of the same type that are held by the message queue. The application must allocate space for this
42 message queue and pass the address of the queue, the queue length and the message size when creating the task:
43 @code
44 static LedMsg_t msgpool[ Q_SIZE ];
45 
46 int main(void) {
47  task_create( task, prio, msgpool, Q_SIZE, sizeof(LedMsg_t) );
48 }
49 @endcode
50 
51 
52 <b>Mutual exclusion and synchronization</b> @n
53 For each message queue, cocoOS creates a binary semaphore and an event intended to be used for mutual exclusion
54 and synchronization. @n Before accessing the queue for either posting or receiving a message, the semaphore
55 should is automatically acquired by the OS. If the semaphore is already taken by another task, the task will be put
56 into the waiting state until the semaphore is released. @n @n
57 
58 The event associated with a message queue is automatically signaled when the queue contents changes,
59 i.e. a message is posted to or removed from the queue. A task will be put to wait for the event when a
60 message queue was full or empty when trying to post or receive a message respectively. Then when the
61 event is signalled, the task makes a new post/receive retry to the message queue. @n
62 When a message has been received or posted, the queue semaphore is finally automatically released by the OS. @n
63 
64 <b>Posting messages</b> @n
65 A message can be posted immediately into another task's message queue by using msg_post(). The message will be placed
66 in the receiving task's message queue fifo and will be processed as soon as possible.
67 With msg_post_in() it is possible to specify a delay before the message will be delivered to the receiving task.
68 See also <b>Asynchronous message posting</b> below.
69 @code
70 
71 static Msg_t msgpool[ 16 ];
72 
73 int main(void)
74 {
75  ...
76  task_create( task1, 1, NULL, 0, 0 );
77  task_create( task2, 2, msgpool, 16, sizeof(Msg_t) );
78  task_create( task3, 3, NULL, 0, 0 );
79  ...
80  os_start();
81  return 0;
82 }
83 
84 
85 static void task1(void) {
86  static Msg_t msg;
87 
88  msg.signal = 10MS_SIG;
89 
90  task_open();
91 
92  for (;;) {
93 
94  task_wait( 10 );
95 
96  /* Post the message into task2's queue */
97  msg_post( task2, msg) );
98 
99  }
100 
101  task_close();
102 
103 }
104 
105 
106 static void task3(void) {
107  static Msg_t msg;
108 
109  msg.signal = BUTTON_SIG;
110 
111  task_open();
112 
113  for (;;) {
114 
115  event_wait( buttonEvt );
116 
117  /* Post the message into task2's queue with 1000 ticks delay */
118  msg_post_in( task2, msg, 1000) );
119 
120  }
121 
122  task_close();
123 
124 }
125 
126 @endcode
127 
128 
129 
130 <b>Receiving messages</b>@n
131 Receiving messages is done in the same manner as posting messages, but using msg_receive() instead.
132 See also <b>Asynchronous message receiving</b> below.@n
133 @n
134 @code
135 static Msg_t msgpool[ 16 ];
136 
137 int main(void)
138 {
139  ...
140  task_create( task1, 1, NULL, 0, 0 );
141  task_create( task2, 2, msgpool, 16, sizeof(Msg_t) );
142  ...
143  os_start();
144  return 0;
145 }
146 
147 
148 static void task2(void) {
149  static Msg_t msg;
150 
151  task_open();
152 
153  for (;;) {
154 
155  /* Wait for a message */
156  msg_receive( task2, &msg) );
157 
158  }
159 
160  task_close();
161 
162 }
163 
164 @endcode
165 
166 <b>Periodic messages</b>@n
167 A message can also be setup to be delivered periodically to its receiver with msg_post_every(). This message will be put into
168 the message queue as a usual delayed message posted with the msg_post_in() method. When the message delay
169 expires, the message is delivered to the task and reposted to the queue automatically with the timer reloaded.
170 A posted periodic message can not be stopped, it will be delivered periodically forever.
171 Note that this type of message should be posted outside the endless task loop. Otherwise the queue will quickly fill up and the
172 system will be overloaded.
173 
174 <b>Asynchronous message posting</b>@n
175 The task can also post messages using the msg_post_async() function. The only difference from the usual msg_post() is that, the
176 task will not block waiting for the queue if it was full. The task will continue executing immediately instead. @n
177 
178 
179 <b>Asynchronous message receiving</b>@n
180 The msg_reveive_async() can be used to poll the queue for messages without blocking the task if the queue is empty. If there are no messages
181 waiting in queue, the function will return immediately and the signal member of the msg parameter will be set to the value NO_MSG_ID (0xff)
182 
183 @code
184 void ledTask( void ) {
185  static LedMsg_t msg;
186 
187  task_open();
188 
189  for (;;) {
190  msg_receive_async( ledTask, &msg );
191 
192  if ( msg.super.signal == LED_SIG ) {
193  blinkLed();
194  }
195  else if ( msg.super.signal == NO_MSG_ID ) {
196  /* Do something else */
197  }
198 
199  /* Wait 200 ms before polling message queue again */
200  task_wait(200);
201  }
202 
203  task_close();
204 }
205 @endcode
206 
207 <b>Message API</b>@n
208 The message API consists of the following macros and functions:@n
209  - msg_post()
210  - msg_post_async()
211  - msg_post_in()
212  - msg_receive()
214  - msg_post_every()
215 
216 
217 */
void os_start(void)
Definition: os_kernel.c:117
#define task_wait(x)
Definition: os_applAPI.h:112
#define msg_post_async(task, msg)
Definition: os_applAPI.h:581
#define msg_post_every(task, msg, period)
Definition: os_applAPI.h:706
#define msg_post(task, msg)
Definition: os_applAPI.h:520
uint8_t task_create(taskproctype taskproc, uint8_t prio, Msg_t *msgPool, uint8_t poolSize, uint16_t msgSize)
Definition: os_task.c:99
#define msg_receive(task, pMsg)
Definition: os_applAPI.h:767
#define event_wait(event)
Definition: os_applAPI.h:263
#define task_open()
Definition: os_applAPI.h:67
#define msg_post_in(task, msg, delay)
Definition: os_applAPI.h:644
#define msg_receive_async(task, pMsg)
Definition: os_applAPI.h:832
#define task_close()
Definition: os_applAPI.h:88