source: rtems/doc/user/msg.t @ 7f46d43d

4.8
Last change on this file since 7f46d43d was 7f46d43d, checked in by Joel Sherrill <joel.sherrill@…>, on Aug 1, 2008 at 3:29:45 PM

2008-08-01 Joel Sherrill <joel.sherrill@…>

  • user/msg.t: Parameter is size not count. Spotted by Sebastian Huber.
  • Property mode set to 100644
File size: 26.9 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2002.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Message Manager
10
11@cindex messages
12@cindex message queues
13
14@section Introduction
15
16The message manager provides communication and
17synchronization capabilities using RTEMS message queues.  The
18directives provided by the message manager are:
19
20@itemize @bullet
21@item @code{@value{DIRPREFIX}message_queue_create} - Create a queue
22@item @code{@value{DIRPREFIX}message_queue_ident} - Get ID of a queue
23@item @code{@value{DIRPREFIX}message_queue_delete} - Delete a queue
24@item @code{@value{DIRPREFIX}message_queue_send} - Put message at rear of a queue
25@item @code{@value{DIRPREFIX}message_queue_urgent} - Put message at front of a queue
26@item @code{@value{DIRPREFIX}message_queue_broadcast} - Broadcast N messages to a queue
27@item @code{@value{DIRPREFIX}message_queue_receive} - Receive message from a queue
28@item @code{@value{DIRPREFIX}message_queue_get_number_pending} - Get number of messages pending on a queue
29@item @code{@value{DIRPREFIX}message_queue_flush} - Flush all messages on a queue
30@end itemize
31
32@section Background
33
34@subsection Messages
35
36A message is a variable length buffer where
37information can be stored to support communication.  The length
38of the message and the information stored in that message are
39user-defined and can be actual data, pointer(s), or empty.
40
41@subsection Message Queues
42
43A message queue permits the passing of messages among
44tasks and ISRs.  Message queues can contain a variable number of
45messages.  Normally messages are sent to and received from the
46queue in FIFO order using the @code{@value{DIRPREFIX}message_queue_send}
47directive.  However, the @code{@value{DIRPREFIX}message_queue_urgent}
48directive can be used to place
49messages at the head of a queue in LIFO order.
50
51Synchronization can be accomplished when a task can
52wait for a message to arrive at a queue.  Also, a task may poll
53a queue for the arrival of a message.
54
55The maximum length message which can be sent is set
56on a per message queue basis.
57
58@subsection Building a Message Queue Attribute Set
59
60@cindex message queue attributes
61
62In general, an attribute set is built by a bitwise OR
63of the desired attribute components.  The set of valid message
64queue attributes is provided in the following table:
65
66@itemize @bullet
67@item @code{@value{RPREFIX}FIFO} - tasks wait by FIFO (default)
68@item @code{@value{RPREFIX}PRIORITY} - tasks wait by priority
69@item @code{@value{RPREFIX}LOCAL} - local message queue (default)
70@item @code{@value{RPREFIX}GLOBAL} - global message queue
71@end itemize
72
73
74An attribute listed as a default is not required to
75appear in the attribute list, although it is a good programming
76practice to specify default attributes.  If all defaults are
77desired, the attribute @code{@value{RPREFIX}DEFAULT_ATTRIBUTES}
78should be specified on this call.
79
80This example demonstrates the attribute_set parameter
81needed to create a local message queue with the task priority
82waiting queue discipline.  The attribute_set parameter to the
83@code{@value{DIRPREFIX}message_queue_create} directive could be either
84@code{@value{RPREFIX}PRIORITY} or
85@code{@value{RPREFIX}LOCAL @value{OR} @value{RPREFIX}PRIORITY}. 
86The attribute_set parameter can be set to @code{@value{RPREFIX}PRIORITY}
87because @code{@value{RPREFIX}LOCAL} is the default for all created
88message queues.  If a similar message queue were to be known globally, then the
89attribute_set parameter would be
90@code{@value{RPREFIX}GLOBAL @value{OR} @value{RPREFIX}PRIORITY}.
91
92@subsection Building a MESSAGE_QUEUE_RECEIVE Option Set
93
94In general, an option is built by a bitwise OR of the
95desired option components.  The set of valid options for the
96@code{@value{DIRPREFIX}message_queue_receive} directive are
97listed in the following table:
98
99@itemize @bullet
100@item @code{@value{RPREFIX}WAIT} - task will wait for a message (default)
101@item @code{@value{RPREFIX}NO_WAIT} - task should not wait
102@end itemize
103
104An option listed as a default is not required to
105appear in the option OR list, although it is a good programming
106practice to specify default options.  If all defaults are
107desired, the option @code{@value{RPREFIX}DEFAULT_OPTIONS} should
108be specified on this call.
109
110This example demonstrates the option parameter needed
111to poll for a message to arrive.  The option parameter passed to
112the @code{@value{DIRPREFIX}message_queue_receive} directive should
113be @code{@value{RPREFIX}NO_WAIT}.
114
115@section Operations
116
117@subsection Creating a Message Queue
118
119The @code{@value{DIRPREFIX}message_queue_create} directive creates a message
120queue with the user-defined name.  The user specifies the
121maximum message size and maximum number of messages which can be
122placed in the message queue at one time.  The user may select
123FIFO or task priority as the method for placing waiting tasks in
124the task wait queue.  RTEMS allocates a Queue Control Block
125(QCB) from the QCB free list to maintain the newly created queue
126as well as memory for the message buffer pool associated with
127this message queue.  RTEMS also generates a message queue ID
128which is returned to the calling task.
129
130For GLOBAL message queues, the maximum message size
131is effectively limited to the longest message which the MPCI is
132capable of transmitting.
133
134@subsection Obtaining Message Queue IDs
135
136When a message queue is created, RTEMS generates a
137unique message queue ID.  The message queue ID may be obtained
138by either of two methods.  First, as the result of an invocation
139of the @code{@value{DIRPREFIX}message_queue_create} directive, the
140queue ID is stored in a user provided location.  Second, the queue
141ID may be obtained later using the @code{@value{DIRPREFIX}message_queue_ident}
142directive.  The queue ID is used by other message manager
143directives to access this message queue.
144
145@subsection Receiving a Message
146
147The @code{@value{DIRPREFIX}message_queue_receive} directive attempts to
148retrieve a message from the specified message queue.  If at
149least one message is in the queue, then the message is removed
150from the queue, copied to the caller's message buffer, and
151returned immediately along with the length of the message.  When
152messages are unavailable, one of the following situations
153applies:
154
155@itemize @bullet
156@item By default, the calling task will wait forever for the
157message to arrive.
158
159@item Specifying the @code{@value{RPREFIX}NO_WAIT} option forces an immediate return
160with an error status code.
161
162@item Specifying a timeout limits the period the task will
163wait before returning with an error status.
164@end itemize
165
166If the task waits for a message, then it is placed in
167the message queue's task wait queue in either FIFO or task
168priority order.  All tasks waiting on a message queue are
169returned an error code when the message queue is deleted.
170
171@subsection Sending a Message
172
173Messages can be sent to a queue with the
174@code{@value{DIRPREFIX}message_queue_send} and
175@code{@value{DIRPREFIX}message_queue_urgent} directives.  These
176directives work identically when tasks are waiting to receive a
177message.  A task is removed from the task waiting queue,
178unblocked,  and the message is copied to a waiting task's
179message buffer.
180
181When no tasks are waiting at the queue,
182@code{@value{DIRPREFIX}message_queue_send} places the
183message at the rear of the message queue, while
184@code{@value{DIRPREFIX}message_queue_urgent} places the message at the
185front of the queue.  The message is copied to a message buffer
186from this message queue's buffer pool and then placed in the
187message queue.  Neither directive can successfully send a
188message to a message queue which has a full queue of pending
189messages.
190
191@subsection Broadcasting a Message
192
193The @code{@value{DIRPREFIX}message_queue_broadcast} directive sends the same
194message to every task waiting on the specified message queue as
195an atomic operation.  The message is copied to each waiting
196task's message buffer and each task is unblocked.  The number of
197tasks which were unblocked is returned to the caller.
198
199@subsection Deleting a Message Queue
200
201The @code{@value{DIRPREFIX}message_queue_delete} directive removes a message
202queue from the system and frees its control block as well as the
203memory associated with this message queue's message buffer pool.
204A message queue can be deleted by any local task that knows the
205message queue's ID.  As a result of this directive, all tasks
206blocked waiting to receive a message from the message queue will
207be readied and returned a status code which indicates that the
208message queue was deleted.  Any subsequent references to the
209message queue's name and ID are invalid.  Any messages waiting
210at the message queue are also deleted and deallocated.
211
212@section Directives
213
214This section details the message manager's
215directives.  A subsection is dedicated to each of this manager's
216directives and describes the calling sequence, related
217constants, usage, and status codes.
218
219@c
220@c
221@c
222@page
223@subsection MESSAGE_QUEUE_CREATE - Create a queue
224
225@cindex create a message queue
226
227@subheading CALLING SEQUENCE:
228
229@ifset is-C
230@findex rtems_message_queue_create
231@example
232rtems_status_code rtems_message_queue_create(
233  rtems_name        name,
234  uint32_t          count,
235  uint32_t          max_message_size,
236  rtems_attribute   attribute_set,
237  rtems_id         *id
238);
239@end example
240@end ifset
241
242@ifset is-Ada
243@example
244procedure Message_Queue_Create (
245   Name             : in     RTEMS.Name;
246   Count            : in     RTEMS.Unsigned32;
247   Max_Message_Size : in     RTEMS.Unsigned32;
248   Attribute_Set    : in     RTEMS.Attribute;
249   ID               :    out RTEMS.ID;
250   Result           :    out RTEMS.Status_Codes
251);
252@end example
253@end ifset
254
255@subheading DIRECTIVE STATUS CODES:
256@code{@value{RPREFIX}SUCCESSFUL} - queue created successfully@*
257@code{@value{RPREFIX}INVALID_NAME} - invalid queue name@*
258@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
259@code{@value{RPREFIX}INVALID_NUMBER} - invalid message count@*
260@code{@value{RPREFIX}INVALID_SIZE} - invalid message size@*
261@code{@value{RPREFIX}TOO_MANY} - too many queues created@*
262@code{@value{RPREFIX}UNSATISFIED} - unable to allocate message buffers@*
263@code{@value{RPREFIX}MP_NOT_CONFIGURED} - multiprocessing not configured@*
264@code{@value{RPREFIX}TOO_MANY} - too many global objects
265
266@subheading DESCRIPTION:
267
268This directive creates a message queue which resides
269on the local node with the user-defined name specified in name.
270For control and maintenance of the queue, RTEMS allocates and
271initializes a QCB.  Memory is allocated from the RTEMS Workspace
272for the specified count of messages, each of max_message_size
273bytes in length.  The RTEMS-assigned queue id, returned in id,
274is used to access the message queue.
275
276Specifying @code{@value{RPREFIX}PRIORITY} in attribute_set causes tasks
277waiting for a message to be serviced according to task priority.
278When @code{@value{RPREFIX}FIFO} is specified, waiting tasks are serviced
279in First In-First Out order.
280
281@subheading NOTES:
282
283This directive will not cause the calling task to be
284preempted.
285
286The following message queue attribute constants are
287defined by RTEMS:
288
289@itemize @bullet
290@item @code{@value{RPREFIX}FIFO} - tasks wait by FIFO (default)
291@item @code{@value{RPREFIX}PRIORITY} - tasks wait by priority
292@item @code{@value{RPREFIX}LOCAL} - local message queue (default)
293@item @code{@value{RPREFIX}GLOBAL} - global message queue
294@end itemize
295
296Message queues should not be made global unless
297remote tasks must interact with the created message queue.  This
298is to avoid the system overhead incurred by the creation of a
299global message queue.  When a global message queue is created,
300the message queue's name and id must be transmitted to every
301node in the system for insertion in the local copy of the global
302object table.
303
304For GLOBAL message queues, the maximum message size
305is effectively limited to the longest message which the MPCI is
306capable of transmitting.
307
308The total number of global objects, including message
309queues, is limited by the maximum_global_objects field in the
310configuration table.
311
312@c
313@c
314@c
315@page
316@subsection MESSAGE_QUEUE_IDENT - Get ID of a queue
317
318@cindex get ID of a message queue
319
320@subheading CALLING SEQUENCE:
321
322@ifset is-C
323@findex rtems_message_queue_ident
324@example
325rtems_status_code rtems_message_queue_ident(
326  rtems_name  name,
327  uint32_t    node,
328  rtems_id   *id
329);
330@end example
331@end ifset
332
333@ifset is-Ada
334@example
335procedure Message_Queue_Ident (
336   Name   : in     RTEMS.Name;
337   Node   : in     RTEMS.Unsigned32;
338   ID     :    out RTEMS.ID;
339   Result :    out RTEMS.Status_Codes
340);
341@end example
342@end ifset
343
344@subheading DIRECTIVE STATUS CODES:
345@code{@value{RPREFIX}SUCCESSFUL} - queue identified successfully@*
346@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
347@code{@value{RPREFIX}INVALID_NAME} - queue name not found@*
348@code{@value{RPREFIX}INVALID_NODE} - invalid node id
349
350@subheading DESCRIPTION:
351
352This directive obtains the queue id associated with
353the queue name specified in name.  If the queue name is not
354unique, then the queue id will match one of the queues with that
355name.  However, this queue id is not guaranteed to correspond to
356the desired queue.  The queue id is used with other message
357related directives to access the message queue.
358
359@subheading NOTES:
360
361This directive will not cause the running task to be
362preempted.
363
364If node is @code{@value{RPREFIX}SEARCH_ALL_NODES}, all nodes are searched
365with the local node being searched first.  All other nodes are
366searched with the lowest numbered node searched first.
367
368If node is a valid node number which does not
369represent the local node, then only the message queues exported
370by the designated node are searched.
371
372This directive does not generate activity on remote
373nodes.  It accesses only the local copy of the global object
374table.
375
376@c
377@c
378@c
379@page
380@subsection MESSAGE_QUEUE_DELETE - Delete a queue
381
382@cindex delete a message queue
383
384@subheading CALLING SEQUENCE:
385
386@ifset is-C
387@findex rtems_message_queue_delete
388@example
389rtems_status_code rtems_message_queue_delete(
390  rtems_id id
391);
392@end example
393@end ifset
394
395@ifset is-Ada
396@example
397procedure Message_Queue_Delete (
398   ID     : in     RTEMS.ID;
399   Result :    out RTEMS.Status_Codes
400);
401@end example
402@end ifset
403
404@subheading DIRECTIVE STATUS CODES:
405@code{@value{RPREFIX}SUCCESSFUL} - queue deleted successfully@*
406@code{@value{RPREFIX}INVALID_ID} - invalid queue id@*
407@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - cannot delete remote queue
408
409@subheading DESCRIPTION:
410
411This directive deletes the message queue specified by
412id.  As a result of this directive, all tasks blocked waiting to
413receive a message from this queue will be readied and returned a
414status code which indicates that the message queue was deleted.
415If no tasks are waiting, but the queue contains messages, then
416RTEMS returns these message buffers back to the system message
417buffer pool.  The QCB for this queue as well as the memory for
418the message buffers is reclaimed by RTEMS.
419
420@subheading NOTES:
421
422The calling task will be preempted if its preemption
423mode is enabled and one or more local tasks with a higher
424priority than the calling task are waiting on the deleted queue.
425The calling task will NOT be preempted if the tasks that are
426waiting are remote tasks.
427
428The calling task does not have to be the task that
429created the queue, although the task and queue must reside on
430the same node.
431
432When the queue is deleted, any messages in the queue
433are returned to the free message buffer pool.  Any information
434stored in those messages is lost.
435
436When a global message queue is deleted, the message
437queue id must be transmitted to every node in the system for
438deletion from the local copy of the global object table.
439
440Proxies, used to represent remote tasks, are
441reclaimed when the message queue is deleted.
442
443@c
444@c
445@c
446@page
447@subsection MESSAGE_QUEUE_SEND - Put message at rear of a queue
448
449@cindex send message to a queue
450
451@subheading CALLING SEQUENCE:
452
453@ifset is-C
454@findex rtems_message_queue_send
455@example
456rtems_status_code rtems_message_queue_send(
457  rtems_id  id,
458  void     *buffer,
459  size_t    size
460);
461@end example
462@end ifset
463
464@ifset is-Ada
465@example
466procedure Message_Queue_Send (
467   ID     : in     RTEMS.ID;
468   Buffer : in     RTEMS.Address;
469   Size   : in     RTEMS.Unsigned32;
470   Result :    out RTEMS.Status_Codes
471);
472@end example
473@end ifset
474
475@subheading DIRECTIVE STATUS CODES:
476@code{@value{RPREFIX}SUCCESSFUL} - message sent successfully@*
477@code{@value{RPREFIX}INVALID_ID} - invalid queue id@*
478@code{@value{RPREFIX}INVALID_SIZE} - invalid message size@*
479@code{@value{RPREFIX}INVALID_ADDRESS} - @code{buffer} is NULL@*
480@code{@value{RPREFIX}UNSATISFIED} - out of message buffers@*
481@code{@value{RPREFIX}TOO_MANY} - queue's limit has been reached
482
483@subheading DESCRIPTION:
484
485This directive sends the message buffer of size bytes
486in length to the queue specified by id.  If a task is waiting at
487the queue, then the message is copied to the waiting task's
488buffer and the task is unblocked. If no tasks are waiting at the
489queue, then the message is copied to a message buffer which is
490obtained from this message queue's message buffer pool.  The
491message buffer is then placed at the rear of the queue.
492
493@subheading NOTES:
494
495The calling task will be preempted if it has
496preemption enabled and a higher priority task is unblocked as
497the result of this directive.
498
499Sending a message to a global message queue which
500does not reside on the local node will generate a request to the
501remote node to post the message on the specified message queue.
502
503If the task to be unblocked resides on a different
504node from the message queue, then the message is forwarded to
505the appropriate node, the waiting task is unblocked, and the
506proxy used to represent the task is reclaimed.
507
508@c
509@c
510@c
511@page
512@subsection MESSAGE_QUEUE_URGENT - Put message at front of a queue
513
514@cindex put message at front of queue
515
516@subheading CALLING SEQUENCE:
517
518@ifset is-C
519@findex rtems_message_queue_urgent
520@example
521rtems_status_code rtems_message_queue_urgent(
522  rtems_id  id,
523  void     *buffer,
524  size_t    size
525);
526@end example
527@end ifset
528
529@ifset is-Ada
530@example
531procedure Message_Queue_Urgent (
532   ID     : in     RTEMS.ID;
533   Buffer : in     RTEMS.Address;
534   Size   : in     RTEMS.Unsigned32;
535   Result :    out RTEMS.Status_Codes
536);
537@end example
538@end ifset
539
540@subheading DIRECTIVE STATUS CODES:
541@code{@value{RPREFIX}SUCCESSFUL} - message sent successfully@*
542@code{@value{RPREFIX}INVALID_ID} - invalid queue id@*
543@code{@value{RPREFIX}INVALID_SIZE} - invalid message size@*
544@code{@value{RPREFIX}INVALID_ADDRESS} - @code{buffer} is NULL@*
545@code{@value{RPREFIX}UNSATISFIED} - out of message buffers@*
546@code{@value{RPREFIX}TOO_MANY} - queue's limit has been reached
547
548@subheading DESCRIPTION:
549
550This directive sends the message buffer of size bytes
551in length to the queue specified by id.  If a task is waiting on
552the queue, then the message is copied to the task's buffer and
553the task is unblocked.  If no tasks are waiting on the queue,
554then the message is copied to a message buffer which is obtained
555from this message queue's message buffer pool.  The message
556buffer is then placed at the front of the queue.
557
558@subheading NOTES:
559
560The calling task will be preempted if it has
561preemption enabled and a higher priority task is unblocked as
562the result of this directive.
563
564Sending a message to a global message queue which
565does not reside on the local node will generate a request
566telling the remote node to post the message on the specified
567message queue.
568
569If the task to be unblocked resides on a different
570node from the message queue, then the message is forwarded to
571the appropriate node, the waiting task is unblocked, and the
572proxy used to represent the task is reclaimed.
573
574@c
575@c
576@c
577@page
578@subsection MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue
579
580@cindex broadcast message to a queue
581
582@subheading CALLING SEQUENCE:
583
584@ifset is-C
585@findex rtems_message_queue_broadcast
586@example
587rtems_status_code rtems_message_queue_broadcast(
588  rtems_id  id,
589  void     *buffer,
590  size_t    size,
591  uint32_t *count
592);
593@end example
594@end ifset
595
596@ifset is-Ada
597@example
598procedure Message_Queue_Broadcast (
599   ID     : in     RTEMS.ID;
600   Buffer : in     RTEMS.Address;
601   Size   : in     RTEMS.Unsigned32;
602   Count  :    out RTEMS.Unsigned32;
603   Result :    out RTEMS.Status_Codes
604);
605@end example
606@end ifset
607
608@subheading DIRECTIVE STATUS CODES:
609@code{@value{RPREFIX}SUCCESSFUL} - message broadcasted successfully@*
610@code{@value{RPREFIX}INVALID_ID} - invalid queue id@*
611@code{@value{RPREFIX}INVALID_ADDRESS} - @code{buffer} is NULL@*
612@code{@value{RPREFIX}INVALID_ADDRESS} - @code{count} is NULL@*
613@code{@value{RPREFIX}INVALID_SIZE} - invalid message size
614
615@subheading DESCRIPTION:
616
617This directive causes all tasks that are waiting at
618the queue specified by id to be unblocked and sent the message
619contained in buffer.  Before a task is unblocked, the message
620buffer of size byes in length is copied to that task's message
621buffer.  The number of tasks that were unblocked is returned in
622count.
623
624@subheading NOTES:
625
626The calling task will be preempted if it has
627preemption enabled and a higher priority task is unblocked as
628the result of this directive.
629
630The execution time of this directive is directly
631related to the number of tasks waiting on the message queue,
632although it is more efficient than the equivalent number of
633invocations of @code{@value{DIRPREFIX}message_queue_send}.
634
635Broadcasting a message to a global message queue
636which does not reside on the local node will generate a request
637telling the remote node to broadcast the message to the
638specified message queue.
639
640When a task is unblocked which resides on a different
641node from the message queue, a copy of the message is forwarded
642to the appropriate node,  the waiting task is unblocked, and the
643proxy used to represent the task is reclaimed.
644
645@c
646@c
647@c
648@page
649@subsection MESSAGE_QUEUE_RECEIVE - Receive message from a queue
650
651@cindex receive message from a queue
652
653@subheading CALLING SEQUENCE:
654
655@ifset is-C
656@findex rtems_message_queue_receive
657@example
658rtems_status_code rtems_message_queue_receive(
659  rtems_id        id,
660  void           *buffer,
661  size_t         *size,
662  uint32_t        option_set,
663  rtems_interval  timeout
664);
665@end example
666@end ifset
667
668@ifset is-Ada
669@example
670procedure Message_Queue_Receive (
671   ID         : in     RTEMS.ID;
672   Buffer     : in     RTEMS.Address;
673   Option_Set : in     RTEMS.Option;
674   Timeout    : in     RTEMS.Interval;
675   Size       :    out RTEMS.Unsigned32;
676   Result     :    out RTEMS.Status_Codes
677);
678@end example
679@end ifset
680
681@subheading DIRECTIVE STATUS CODES:
682@code{@value{RPREFIX}SUCCESSFUL} - message received successfully@*
683@code{@value{RPREFIX}INVALID_ID} - invalid queue id@*
684@code{@value{RPREFIX}INVALID_ADDRESS} - @code{buffer} is NULL@*
685@code{@value{RPREFIX}INVALID_ADDRESS} - @code{size} is NULL@*
686@code{@value{RPREFIX}UNSATISFIED} - queue is empty@*
687@code{@value{RPREFIX}TIMEOUT} - timed out waiting for message@*
688@code{@value{RPREFIX}OBJECT_WAS_DELETED} - queue deleted while waiting
689
690@subheading DESCRIPTION:
691
692This directive receives a message from the message
693queue specified in id.  The @code{@value{RPREFIX}WAIT} and @code{@value{RPREFIX}NO_WAIT} options of the
694options parameter allow the calling task to specify whether to
695wait for a message to become available or return immediately.
696For either option, if there is at least one message in the
697queue, then it is copied to buffer, size is set to return the
698length of the message in bytes, and this directive returns
699immediately with a successful return code.
700
701If the calling task chooses to return immediately and
702the queue is empty, then a status code indicating this condition
703is returned.  If the calling task chooses to wait at the message
704queue and the queue is empty, then the calling task is placed on
705the message wait queue and blocked.  If the queue was created
706with the @code{@value{RPREFIX}PRIORITY} option specified, then
707the calling task is inserted into the wait queue according to
708its priority.  But, if the queue was created with the
709@code{@value{RPREFIX}FIFO} option specified, then the
710calling task is placed at the rear of the wait queue.
711
712A task choosing to wait at the queue can optionally
713specify a timeout value in the timeout parameter.  The timeout
714parameter specifies the maximum interval to wait before the
715calling task desires to be unblocked.  If it is set to
716@code{@value{RPREFIX}NO_TIMEOUT}, then the calling task will wait forever.
717
718@subheading NOTES:
719
720The following message receive option constants are
721defined by RTEMS:
722
723@itemize @bullet
724@item @code{@value{RPREFIX}WAIT} - task will wait for a message (default)
725@item @code{@value{RPREFIX}NO_WAIT} - task should not wait
726@end itemize
727
728Receiving a message from a global message queue which
729does not reside on the local node will generate a request to the
730remote node to obtain a message from the specified message
731queue.  If no message is available and @code{@value{RPREFIX}WAIT} was specified, then
732the task must be blocked until a message is posted.  A proxy is
733allocated on the remote node to represent the task until the
734message is posted.
735
736A clock tick is required to support the timeout functionality of
737this directive.
738
739@c
740@c
741@c
742@page
743@subsection MESSAGE_QUEUE_GET_NUMBER_PENDING - Get number of messages pending on a queue
744
745@cindex get number of pending messages
746
747@subheading CALLING SEQUENCE:
748
749@ifset is-C
750@findex rtems_message_queue_get_number_pending
751@example
752rtems_status_code rtems_message_queue_get_number_pending(
753  rtems_id  id,
754  uint32_t *count
755);
756@end example
757@end ifset
758
759@ifset is-Ada
760@example
761procedure Message_Queue_Get_Number_Pending (
762   ID     : in     RTEMS.ID;
763   Count  :    out RTEMS.Unsigned32;
764   Result :    out RTEMS.Status_Codes
765);
766@end example
767@end ifset
768
769@subheading DIRECTIVE STATUS CODES:
770@code{@value{RPREFIX}SUCCESSFUL} - number of messages pending returned successfully@*
771@code{@value{RPREFIX}INVALID_ADDRESS} - @code{count} is NULL@*
772@code{@value{RPREFIX}INVALID_ID} - invalid queue id
773
774@subheading DESCRIPTION:
775
776This directive returns the number of messages pending on this
777message queue in count.  If no messages are present
778on the queue, count is set to zero.
779
780@subheading NOTES:
781
782Getting the number of pending messages on a global message queue which
783does not reside on the local node will generate a request to the
784remote node to actually obtain the pending message count for
785the specified message queue.
786
787
788@c
789@c
790@c
791@page
792@subsection MESSAGE_QUEUE_FLUSH - Flush all messages on a queue
793
794@cindex flush messages on a queue
795
796@subheading CALLING SEQUENCE:
797
798@ifset is-C
799@findex rtems_message_queue_flush
800@example
801rtems_status_code rtems_message_queue_flush(
802  rtems_id  id,
803  uint32_t *count
804);
805@end example
806@end ifset
807
808@ifset is-Ada
809@example
810procedure Message_Queue_Flush (
811   ID     : in     RTEMS.ID;
812   Count  :    out RTEMS.Unsigned32;
813   Result :    out RTEMS.Status_Codes
814);
815@end example
816@end ifset
817
818@subheading DIRECTIVE STATUS CODES:
819@code{@value{RPREFIX}SUCCESSFUL} - message queue flushed successfully@*
820@code{@value{RPREFIX}INVALID_ADDRESS} - @code{count} is NULL@*
821@code{@value{RPREFIX}INVALID_ID} - invalid queue id
822
823@subheading DESCRIPTION:
824
825This directive removes all pending messages from the
826specified queue id.  The number of messages removed is returned
827in count.  If no messages are present on the queue, count is set
828to zero.
829
830@subheading NOTES:
831
832Flushing all messages on a global message queue which
833does not reside on the local node will generate a request to the
834remote node to actually flush the specified message queue.
835
Note: See TracBrowser for help on using the repository browser.