1 <!-- Copyright (C) 2003 Red Hat, Inc. -->
2 <!-- This material may be distributed only subject to the terms -->
3 <!-- and conditions set forth in the Open Publication License, v1.0 -->
4 <!-- or later (the latest version is presently available at -->
5 <!-- http://www.opencontent.org/openpub/). -->
6 <!-- Distribution of the work or derivative of the work in any -->
7 <!-- standard (paper) book form is prohibited unless prior -->
8 <!-- permission is obtained from the copyright holder. -->
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="The eCos Kernel"
23 HREF="kernel.html"><LINK
26 HREF="kernel-semaphores.html"><LINK
29 HREF="kernel-flags.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="kernel-semaphores.html"
71 HREF="kernel-flags.html"
82 NAME="KERNEL-MAIL-BOXES">Mail boxes</H1
90 >cyg_mbox_create, cyg_mbox_delete, cyg_mbox_get, cyg_mbox_timed_get, cyg_mbox_tryget, cyg_mbox_peek_item, cyg_mbox_put, cyg_mbox_timed_put, cyg_mbox_tryput, cyg_mbox_peek, cyg_mbox_waiting_to_get, cyg_mbox_waiting_to_put -- Synchronization primitive</DIV
92 CLASS="REFSYNOPSISDIV"
108 CLASS="FUNCSYNOPSISINFO"
109 >#include <cyg/kernel/kapi.h>
118 >void cyg_mbox_create</CODE
119 >(cyg_handle_t* handle, cyg_mbox* mbox);</CODE
125 >void cyg_mbox_delete</CODE
126 >(cyg_handle_t mbox);</CODE
132 >void* cyg_mbox_get</CODE
133 >(cyg_handle_t mbox);</CODE
139 >void* cyg_mbox_timed_get</CODE
140 >(cyg_handle_t mbox, cyg_tick_count_t abstime);</CODE
146 >void* cyg_mbox_tryget</CODE
147 >(cyg_handle_t mbox);</CODE
153 >cyg_count32 cyg_mbox_peek</CODE
154 >(cyg_handle_t mbox);</CODE
160 >void* cyg_mbox_peek_item</CODE
161 >(cyg_handle_t mbox);</CODE
167 >cyg_bool_t cyg_mbox_put</CODE
168 >(cyg_handle_t mbox, void* item);</CODE
174 >cyg_bool_t cyg_mbox_timed_put</CODE
175 >(cyg_handle_t mbox, void* item, cyg_tick_count_t abstime);</CODE
181 >cyg_bool_t cyg_mbox_tryput</CODE
182 >(cyg_handle_t mbox, void* item);</CODE
188 >cyg_bool_t cyg_mbox_waiting_to_get</CODE
189 >(cyg_handle_t mbox);</CODE
195 >cyg_bool_t cyg_mbox_waiting_to_put</CODE
196 >(cyg_handle_t mbox);</CODE
205 NAME="KERNEL-MAIL-BOXES-DESCRIPTION"
210 >Mail boxes are a synchronization primitive. Like semaphores they
211 can be used by a consumer thread to wait until a certain event has
212 occurred, but the producer also has the ability to transmit some data
213 along with each event. This data, the message, is normally a pointer
214 to some data structure. It is stored in the mail box itself, so the
215 producer thread that generates the event and provides the data usually
216 does not have to block until some consumer thread is ready to receive
217 the event. However a mail box will only have a finite capacity,
218 typically ten slots. Even if the system is balanced and events are
219 typically consumed at least as fast as they are generated, a burst of
220 events can cause the mail box to fill up and the generating thread
221 will block until space is available again. This behaviour is very
222 different from semaphores, where it is only necessary to maintain a
223 counter and hence an overflow is unlikely.
226 >Before a mail box can be used it must be created with a call to
230 >. Each mail box has a unique
231 handle which will be returned via the first argument and which should
232 be used for subsequent operations.
236 > also requires an area of memory
237 for the kernel structure, which is provided by the
241 > second argument. If a mail box is
242 no longer required then <TT
246 used. This will simply discard any messages that remain posted.
249 >The main function for waiting on a mail box is
253 >. If there is a pending message
254 because of a call to <TT
261 > will return immediately with the
262 message that was put into the mail box. Otherwise this function
263 will block until there is a put operation. Exceptionally the thread
264 can instead be unblocked by a call to
267 >cyg_thread_release</TT
272 > will return a null pointer. It is
273 assumed that there will never be a call to
277 > with a null pointer, because it
278 would not be possible to distinguish between that and a release
279 operation. Messages are always retrieved in the order in which they
280 were put into the mail box, and there is no support for messages
281 with different priorities.
284 >There are two variants of <TT
290 >cyg_mbox_timed_get</TT
291 > will wait until either
292 a message is available or until a number of clock ticks have occurred.
293 If no message is posted within the timeout then a null pointer will be
298 operation which will either return a message if one is available or a
302 >New messages are placed in the mail box by calling
306 > or one of its variants. The main put
307 function takes two arguments, a handle to the mail box and a
308 pointer for the message itself. If there is a spare slot in the
309 mail box then the new message can be placed there immediately, and
310 if there is a waiting thread it will be woken up so that it can
311 receive the message. If the mail box is currently full then
315 > will block until there has been a
316 get operation and a slot is available. The
319 >cyg_mbox_timed_put</TT
320 > variant imposes a time limit
321 on the put operation, returning false if the operation cannot be
322 completed within the specified number of clock ticks. The
326 > variant is non-blocking,
327 returning false if there are no free slots available and the message
328 cannot be posted without blocking.
331 >There are a further four functions available for examining the current
332 state of a mailbox. The results of these functions must be used with
333 care because usually the state can change at any time as a result of
334 activity within other threads, but they may prove occasionally useful
335 during debugging or in special situations.
339 > returns a count of the number of
340 messages currently stored in the mail box.
343 >cyg_mbox_peek_item</TT
344 > retrieves the first message,
345 but it remains in the mail box until a get operation is performed.
348 >cyg_mbox_waiting_to_get</TT
352 >cyg_mbox_waiting_to_put</TT
353 > indicate whether or not
354 there are currently threads blocked in a get or a put operation on a
358 >The number of slots in each mail box is controlled by a
362 >CYGNUM_KERNEL_SYNCH_MBOX_QUEUE_SIZE</TT
364 value of 10. All mail boxes are the same size.
370 NAME="KERNEL-MAIL-BOXES-CONTEXT"
378 > is typically called during
379 system initialization but may also be called in thread context.
380 The remaining functions are normally called only during thread
381 context. Of special note is <TT
385 can be a blocking operation when the mail box is full, and which
386 therefore must never be called from DSR context. It is permitted to
394 >, and the information functions
395 from DSR context but this is rarely useful.
403 SUMMARY="Footer navigation table"
414 HREF="kernel-semaphores.html"
432 HREF="kernel-flags.html"
projects / karo-tx-redboot.git / blob