6 A :dfn:`mailbox` is a kernel object that provides enhanced message queue
7 capabilities that go beyond the capabilities of a message queue object.
25 * A **receive queue** of threads that are waiting to receive a message.
31 A thread that sends a message is known as the **sending thread**,
32 while a thread that receives the message is known as the **receiving thread**.
33 Each message may be received by only one thread (i.e. point-to-multipoint and
40 Message Format
43 A **message descriptor** is a data structure that specifies where a message's
44 data is located, and how the message is to be handled by the mailbox.
45 Both the sending thread and the receiving thread supply a message descriptor
46 when accessing a mailbox. The mailbox uses the message descriptors to perform
47 a message exchange between compatible sending and receiving threads.
48 The mailbox also updates certain message descriptor fields during the exchange,
51 A mailbox message contains zero or more bytes of **message data**.
52 The size and format of the message data is application-defined, and can vary
53 from one message to the next.
55 A **message buffer** is an area of memory provided by the thread that sends or
56 receives the message data. An array or structure variable can often be used for
59 A message that has neither form of message data is called an **empty message**.
62     A message whose message buffer exists, but contains zero bytes of actual
63     data, is *not* an empty message.
65 Message Lifecycle
68 The life cycle of a message is straightforward. A message is created when
69 it is given to a mailbox by the sending thread. The message is then owned
71 may retrieve the message data when it receives the message from the mailbox,
73 Only when data retrieval has occurred is the message deleted by the mailbox.
78 A sending thread can specify the address of the thread to which the message
81 it wishes to receive a message, or it can receive a message from any thread
83 A message is exchanged only when the requirements of both the sending thread
86 For example, if thread A sends a message to thread B (and only thread B)
87 it will be received by thread B if thread B tries to receive a message
89 The exchange will not occur if thread B tries to receive a message
90 from thread C. The message can never be received by thread C,
91 even if it tries to receive a message from thread A (or from any thread).
93 Message Flow Control
97 In a synchronous exchange, the sending thread blocks until the message
99 the sending thread does not wait until the message has been received
101 other work (such as gather data that will be used in the next message)
102 *before* the message is given to a receiving thread and fully processed.
103 The technique used for a given message exchange is determined
110 if a previously sent message still exists before sending a subsequent message.
138 Message Descriptors
141 A message descriptor is a structure of type :c:struct:`k_mbox_msg`.
146     A 32-bit value that is exchanged by the message sender and receiver,
149     during any message exchange, and allowing the receiver to pass a value
150     to the sender during a synchronous message exchange.
153     The message data size, in bytes. Set it to zero when sending an empty
154     message, or when sending a message buffer with no actual data. When
155     receiving a message, set it to the maximum amount of data desired, or to
156     zero if the message data is not wanted. The mailbox updates this field with
157     the actual number of data bytes exchanged once the message is received.
160     A pointer to the sending thread's message buffer. Set it to ``NULL``
161     when sending an empty message. Leave this field uninitialized when
162     receiving a message.
166     to allow any thread to receive the message. Leave this field uninitialized
167     when receiving a message. The mailbox updates this field with
168     the actual receiver's address once the message is received.
172     to receive a message sent by any thread. Leave this field uninitialized
173     when sending a message. The mailbox updates this field
174     with the actual sender's address when the message is put into
177 Sending a Message
180 A thread sends a message by first creating its message data, if any.
182 Next, the sending thread creates a message descriptor that characterizes
183 the message to be sent, as described in the previous section.
186 message exchange. The message is immediately given to a compatible receiving
187 thread, if one is currently waiting. Otherwise, the message is added
193 the oldest message can be received first.
196 receiving thread has both received the message and retrieved the message data.
197 If the message is not received before the waiting period specified by the
198 sending thread is reached, the message is removed from the mailbox's send queue
200 the sending thread can examine the message descriptor to determine
201 which thread received the message, how much data was exchanged,
208    before the message is received by another thread. Once a message is received
210    the message data and unblock the sending thread.
214 message is given to a receiving thread immediately or added to the send queue.
216 when the message is deleted by the mailbox, for example, when the message
224    A thread that sends a message asynchronously has no way to determine
225    which thread received the message, how much data was exchanged, or the
228 Sending an Empty Message  argument
232 to any consuming thread that wants one. The message "info" field is
234 portion of the message isn't used.
247             /* prepare to send empty message */
253             /* send message and wait until a consumer receives it */
258 Sending Data Using a Message Buffer  argument
263 The message "info" field is used to exchange information about
264 the maximum size message buffer that each thread can handle.
282             /* prepare to send message */
288             /* send message and wait until a consumer receives it */
293             /* verify that message data was fully received */
295                 printf("some message data dropped during transfer!");
301 Receiving a Message
304 A thread receives a message by first creating a message descriptor that
305 characterizes the message it wants to receive. It then calls one of the
306 mailbox receive APIs. The mailbox searches its send queue and takes the message
312 can examine the message descriptor to determine which thread sent the message,
319 first can receive a message first.
324     message descriptors. For example, if thread A waits to receive a message
325     only from thread X and then thread B waits to receive a message from
326     thread Y, an incoming message from thread Y to any thread will be given
330 incoming message and where the data ends up. The thread may choose to take
331 all of the data in the message, to take only the initial part of the data,
333 copied into a message buffer of its choice.
336 when retrieving message data.
341 The most straightforward way for a thread to retrieve message data is to
342 specify a message buffer when the message is received. The thread indicates
343 both the location of the message buffer (which must not be ``NULL``)
346 The mailbox copies the message's data to the message buffer as part of the
347 receive operation. If the message buffer is not big enough to contain all of the
348 message's data, any uncopied data is lost. If the message is not big enough
349 to fill all of the buffer with data, the unused portion of the message buffer is
351 message descriptor to indicate how many data bytes were copied (if any).
354 where the maximum size of a message is known in advance.
357 producing thread, using the immediate data retrieval technique. The message
359 message buffer that each thread can handle.
372             /* prepare to receive message */
382             /* verify that message data was fully received */
384                 printf("some message data dropped during transfer!");
388             /* compute sum of all message bytes (from 0 to 100 of them) */
396 Retrieving Data Later Using a Message Buffer  argument
399 A receiving thread may choose to defer message data retrieval at the time
400 the message is received, so that it can retrieve the data into a message buffer
402 The thread does this by specifying a message buffer location of ``NULL``
406 The mailbox does not copy any message data as part of the receive operation.
407 However, the mailbox still updates the receiving thread's message descriptor
412 * If the message descriptor size is zero, then either the sender's message
415   the mailbox has already completed data retrieval and deleted the message.
417 * If the message descriptor size is non-zero and the receiving thread still
419   and supply a message buffer large enough to hold the data. The mailbox copies
420   the data into the message buffer and deletes the message.
422 * If the message descriptor size is non-zero and the receiving thread does *not*
424   and specify a message buffer of ``NULL``. The mailbox deletes
425   the message without copying the data.
428 immediate retrieval of message data is undesirable. For example, it can be
430 always supply a message buffer capable of holding the largest possible
431 incoming message.
434 to get message data from a producing thread only if the message meets
435 certain criteria, thereby eliminating unneeded data copying. The message
436 "info" field supplied by the sender is used to classify the message.
446             /* prepare to receive message */
450             /* get message, but not its data */
453             /* get message data for only certain types of messages */
455                 /* retrieve message data and delete the message */
461                 /* ignore message data and delete the message */
471 of a message queue are insufficient.