Add demo application.
[bertos.git] / kern / msg.h
1 /*!
2  * \file
3  * <!--
4  * Copyright 2004 Develer S.r.l. (http://www.develer.com/)
5  * Copyright 1999,2001 Bernardo Innocenti <bernie@develer.com>
6  * This file is part of DevLib - See README.devlib for information.
7  * -->
8  *
9  * \brief Simple inter-process messaging system
10  *
11  * This module implements a common system for executing
12  * a user defined action calling a hook function.
13  *
14  * \version $Id$
15  *
16  * \author Bernardo Innocenti <bernie@develer.com>
17  */
18
19 /*#*
20  *#* $Log$
21  *#* Revision 1.8  2005/11/04 16:20:02  bernie
22  *#* Fix reference to README.devlib in header.
23  *#*
24  *#* Revision 1.7  2005/02/09 21:48:30  bernie
25  *#* Doxygen fixes.
26  *#*
27  *#* Revision 1.6  2005/01/22 04:20:26  bernie
28  *#* Write extensive documentation; Add simple locking.
29  *#*
30  *#* Revision 1.5  2004/11/28 23:20:25  bernie
31  *#* Remove obsolete INITLIST macro.
32  *#*
33  *#* Revision 1.4  2004/10/19 08:22:09  bernie
34  *#* msg_peek(): New function.
35  *#*
36  *#* Revision 1.3  2004/08/25 14:12:09  rasky
37  *#* Aggiornato il comment block dei log RCS
38  *#*
39  *#* Revision 1.2  2004/08/14 19:37:57  rasky
40  *#* Merge da SC: macros.h, pool.h, BIT_CHANGE, nome dei processi, etc.
41  *#*
42  *#* Revision 1.1  2004/06/06 15:11:08  bernie
43  *#* Import into DevLib.
44  *#*
45  *#*/
46 #ifndef KERN_MSG_H
47 #define KERN_MSG_H
48
49 #include "event.h"
50 #include <mware/list.h>
51
52
53 /*!
54  * Handle queues of messages associated an action.
55  *
56  * A message port is an abstraction used to exchange information
57  * asynchronously between processes or other entities such as
58  * interrupts and call-back functions.
59  *
60  * This form of IPC is higher-level than bare signals and
61  * semaphores, because it sets a policy for exchanging
62  * structured data with well-defined synchronization and
63  * ownership semantics.
64  *
65  * Before using it, a message port must be initialized by
66  * calling msg_initPort(), which associates the port with
67  * an Event object, which can be setup to signal a process
68  * or invoke a call-back hook.
69  *
70  * A process or interrupt routine can deliver messages to any
71  * message port by calling msg_put().  By sending a message,
72  * the sender temporarly or permanently transfers ownership
73  * of its associated data to the receiver.
74  *
75  * Queuing a message to a port automatically triggers the
76  * associated Event to notify the receiver.  When the
77  * receiver wakes up, it usually invokes msg_get() to pick
78  * the next message from the port.
79  *
80  * Message ports can hold any number of pending messages,
81  * and receivers usually process them in FIFO order.
82  * Other scheduling policies are possible, but not implemented
83  * in this API.
84  *
85  * After the receiver has done processing a message, it replies
86  * it back to the sender with msg_reply(), which transfer
87  * ownership back to the original sender.  Replies are delivered
88  * to a reply port, which is nothing more than another MsgPort
89  * structure designated by the sender.
90  *
91  * Returning messages to senders is not mandatory, but it provides
92  * a convenient way to provide some kind of result and simplify
93  * the resource allocation scheme at the same time.
94  *
95  * When using signals to receive messages in a process, you
96  * call sig_wait() in an event-loop to wake up when messages
97  * are delivered to any of your ports.  When your process
98  * wakes up with the port signal active, multiple messages
99  * may already have queued up at the message port, and the
100  * process must process them all before returning to sleep.
101  * Signals don't keep a nesting count.
102  *
103  * A simple message loop works like this:
104  *
105  * \code
106  *      // Our message port.
107  *      static MsgPort test_port;
108  *
109  *      // A test message with two parameters and a result.
110  *      typedef struct
111  *      {
112  *              Msg msg;
113  *
114  *              int x, y;
115  *              int result;
116  *      } TestMsg;
117  *
118  *
119  *      // A process that sends two messages and waits for replies.
120  *      static void sender_proc(void)
121  *      {
122  *              MsgPort test_reply_port;
123  *              TestMsg msg1;
124  *              TestMsg msg2;
125  *              Msg *reply;
126  *
127  *              msg_initPort(&reply_port,
128  *                      event_createSignal(proc_current(), SIGF_SINGLE);
129  *
130  *              // Fill-in first message and send it out.
131  *              msg1.x = 3;
132  *              msg1.y = 2;
133  *              msg1.msg.replyPort = &test_reply_port;
134  *              msg_put(&test_port, &msg1);
135  *
136  *              // Fill-in second message and send it out too.
137  *              msg2.x = 5;
138  *              msg2.y = 4;
139  *              msg2.msg.replyPort = &test_reply_port;
140  *              msg_put(&test_port, &msg1);
141  *
142  *              // Wait for a reply...
143  *              sig_wait(SIG_SINGLE);
144  *
145  *              reply = (TestMsg *)msg_get(&test_reply_port);
146  *              ASSERT(reply != NULL);
147  *              ASSERT(reply->result == 5);
148  *
149  *              // Get reply to second message.
150  *              while (!(reply = (TestMsg *)msg_get(&test_reply_port))
151  *              {
152  *                      // Not yet, be patient and wait some more.
153  *                      sig_wait(SIG_SINGLE);
154  *              }
155  *
156  *              ASSERT(reply->result == 9);
157  *      }
158  *
159  *
160  *      // Receive messages and do something boring with them.
161  *      static void receiver_proc(void)
162  *      {
163  *              msg_initPort(&test_port,
164  *                      event_createSignal(proc_current(), SIGF_EXAMPLE);
165  *
166  *              proc_new(sender_proc, (iptr_t)&test_port,
167  *                      sender_stack, sizeof(sender_stack);
168  *
169  *              for (;;)
170  *              {
171  *                      sigmask_t sigs = sig_wait(SIGF_EXAMPLE | more_signals);
172  *
173  *                      if (sigs & SIGF_EXAMPLE)
174  *                      {
175  *                              TestMsg *emsg;
176  *                              while (emsg = (TestMsg *)msg_get(&test_port)
177  *                              {
178  *                                      // Do something with the message
179  *                                      emsg->result = emsg->x + emsg->y;
180  *                                      msg_reply((Msg *)msg);
181  *                              }
182  *                      }
183  *              }
184  *      }
185  * \endcode
186  */
187 typedef struct MsgPort
188 {
189         List  queue;   /*!< Messages queued at this port. */
190         Event event;   /*!< Event to trigger when a message arrives. */
191 } MsgPort;
192
193
194 typedef struct Msg
195 {
196         Node     link;      /*!< Link into message port queue. */
197         MsgPort *replyPort; /*!< Port to which the msg is to be replied. */
198         /* User data may follow */
199 } Msg;
200
201
202 /*!
203  * Lock a message port.
204  *
205  * This is required before reading or manipulating
206  * any field of the MsgPort structure.
207  *
208  * \note Ports may be locked multiple times and each
209  *       call to msg_lockPort() must be paired with
210  *       a corresponding call to msg_unlockPort().
211  *
212  * \todo Add a configurable policy for locking against
213  *       interrupts and locking with semaphorse.
214  *
215  * \see msg_unlockPort()
216  */
217 INLINE void msg_lockPort(MsgPort *port)
218 {
219         proc_forbid();
220 }
221
222 /*!
223  * Unlock a message port.
224  *
225  * \see msg_lockPort()
226  */
227 INLINE void msg_unlockPort(MsgPort *port)
228 {
229         proc_permit();
230 }
231
232
233 /*! Initialize a message port */
234 INLINE void msg_initPort(MsgPort *port, Event event)
235 {
236         LIST_INIT(&port->queue);
237         port->event = event;
238 }
239
240 /*! Queue \a msg into \a port, triggering the associated event */
241 INLINE void msg_put(MsgPort *port, Msg *msg)
242 {
243         msg_portLock(port);
244         ADDTAIL(&port->queue, &msg->link);
245         msg_portUnlock(port);
246
247         event_do(&port->event);
248 }
249
250 /*!
251  * Get the first message from the queue of \a port.
252  *
253  * \return Pointer to the message or NULL if the port was empty.
254  */
255 INLINE Msg *msg_get(MsgPort *port)
256 {
257         Msg *msg;
258
259         msg_portLock(port);
260         msg = (Msg *)REMHEAD(&port->queue);
261         msg_portUnlock(port);
262
263         return msg;
264 }
265
266 /*! Peek the first message in the queue of \a port, or NULL if the port is empty. */
267 INLINE Msg *msg_peek(MsgPort *port)
268 {
269         Msg *msg;
270
271         msg_portLock(port);
272         msg = (Msg *)port->queue.head;
273         if (ISLISTEMPTY(&port->queue))
274                 msg = NULL;
275         msg_portUnlock(port);
276
277         return msg;
278 }
279
280 /*! Send back (reply) \a msg to its sender. */
281 INLINE void msg_reply(Msg *msg)
282 {
283         msg_put(msg->replyPort, msg);
284 }
285
286 #endif /* KERN_MSG_H */