Lines Matching full:a
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.
8 A mailbox allows threads to send and receive messages of any size
21 A mailbox has the following key properties:
23 * A **send queue** of messages that have been sent but not yet received.
25 * A **receive queue** of threads that are waiting to receive a message.
27 A mailbox must be initialized before it can be used. This sets both of its
30 A mailbox allows threads, but not ISRs, to exchange messages.
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**.
36 Messages exchanged using a mailbox are handled non-anonymously,
43 A **message descriptor** is a data structure that specifies where a message's
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.
51 A mailbox message contains zero or more bytes of **message data**.
55 A **message buffer** is an area of memory provided by the thread that sends or
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
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
70 by the mailbox until it is given to a receiving thread. The receiving thread
72 or it may perform data retrieval during a second, subsequent mailbox operation.
78 A sending thread can specify the address of the thread to which the message
80 Likewise, a receiving thread can specify the address of the thread from which
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
88 from thread A or if thread B tries to receive from any thread.
89 The exchange will not occur if thread B tries to receive a message
91 even if it tries to receive a message from thread A (or from any thread).
97 In a synchronous exchange, the sending thread blocks until the 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
107 preventing a sending thread from generating messages faster than they can be
109 explicit form of flow control, which allows a sending thread to determine
110 if a previously sent message still exists before sending a subsequent message.
115 Defining a Mailbox
118 A mailbox is defined using a variable of type :c:struct:`k_mbox`.
129 Alternatively, a mailbox can be defined and initialized at compile time
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,
148 bi-directional, allowing the sender to pass a value to the receiver
149 during any message exchange, and allowing the receiver to pass a value
150 to the sender during a synchronous message exchange.
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
160 A pointer to the sending thread's message buffer. Set it to ``NULL``
162 receiving a message.
167 when receiving a message. The mailbox updates this field with
172 to receive a message sent by any thread. Leave this field uninitialized
173 when sending a message. The mailbox updates this field
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
185 Finally, the sending thread calls a mailbox send API to initiate the
186 message exchange. The message is immediately given to a compatible receiving
190 Any number of messages may exist simultaneously on a send queue.
195 For a synchronous send operation, the operation normally completes when a
199 and the send operation fails. When a send operation completes successfully
205 A synchronous send operation may block the sending thread indefinitely,
206 even when the thread specifies a maximum waiting period.
208 before the message is received by another thread. Once a message is received
214 message is given to a receiving thread immediately or added to the send queue.
215 The sending thread may optionally specify a semaphore that the mailbox gives
217 has been received and its data retrieved by a receiving thread.
218 The use of a semaphore allows the sending thread to easily implement
219 a flow control mechanism that ensures that the mailbox holds no more than
220 an application-specified number of messages from a sending thread
224 A thread that sends a message asynchronously has no way to determine
231 This code uses a mailbox to synchronously pass 4 byte random values
253 /* send message and wait until a consumer receives it */
258 Sending Data Using a Message Buffer
261 This code uses a mailbox to synchronously pass variable-sized requests
262 from a producing thread to any consuming thread that wants it.
288 /* send message and wait until a consumer receives it */
301 Receiving a Message
304 A thread receives a message by first creating a message descriptor that
311 Once a receive operation completes successfully the receiving thread
316 Any number of receiving threads may wait simultaneously on a mailboxes'
319 first can receive a message first.
322 Receiving threads do not always receive messages in a first in, first out
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
327 to thread B and thread A will continue to wait.
333 copied into a message buffer of its choice.
335 The following sections outline various approaches a receiving thread may use
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
354 where the maximum size of a message is known in advance.
356 The following code uses a mailbox to process variable-sized requests from any
377 /* get a data item, waiting as long as needed */
396 Retrieving Data Later Using a Message Buffer
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
401 at a later time.
402 The thread does this by specifying a message buffer location of ``NULL``
403 and a size indicating the maximum amount of data it is willing to retrieve
419 and supply a message buffer large enough to hold the data. The mailbox copies
424 and specify a message buffer of ``NULL``. The mailbox deletes
430 always supply a message buffer capable of holding the largest possible
433 The following code uses a mailbox's deferred data retrieval mechanism
434 to get message data from a producing thread only if the message meets
470 Use a mailbox to transfer data items between threads whenever the capabilities
471 of a message queue are insufficient.