source: rtems/doc/user/msg.t @ a3a7527

4.104.114.84.95
Last change on this file since a3a7527 was a3a7527, checked in by Joel Sherrill <joel.sherrill@…>, on Mar 27, 1998 at 1:04:02 PM

Attempting to add variable so that in C all constants start with RTEMS_
and all directives start with rtems_.

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