summaryrefslogtreecommitdiffstats
path: root/doc/user/msg.t
blob: f58d677150440a514258a5d985442ecff0d9ddbb (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
@c
@c  COPYRIGHT (c) 1988-2002.
@c  On-Line Applications Research Corporation (OAR).
@c  All rights reserved.

@chapter Message Manager

@cindex messages
@cindex message queues

@section Introduction

The message manager provides communication and
synchronization capabilities using RTEMS message queues.  The
directives provided by the message manager are:

@itemize @bullet
@item @code{@value{DIRPREFIX}message_queue_create} - Create a queue
@item @code{@value{DIRPREFIX}message_queue_ident} - Get ID of a queue
@item @code{@value{DIRPREFIX}message_queue_delete} - Delete a queue
@item @code{@value{DIRPREFIX}message_queue_send} - Put message at rear of a queue
@item @code{@value{DIRPREFIX}message_queue_urgent} - Put message at front of a queue
@item @code{@value{DIRPREFIX}message_queue_broadcast} - Broadcast N messages to a queue
@item @code{@value{DIRPREFIX}message_queue_receive} - Receive message from a queue
@item @code{@value{DIRPREFIX}message_queue_get_number_pending} - Get number of messages pending on a queue
@item @code{@value{DIRPREFIX}message_queue_flush} - Flush all messages on a queue
@end itemize

@section Background

@subsection Messages

A message is a variable length buffer where
information can be stored to support communication.  The length
of the message and the information stored in that message are
user-defined and can be actual data, pointer(s), or empty.

@subsection Message Queues

A message queue permits the passing of messages among
tasks and ISRs.  Message queues can contain a variable number of
messages.  Normally messages are sent to and received from the
queue in FIFO order using the @code{@value{DIRPREFIX}message_queue_send}
directive.  However, the @code{@value{DIRPREFIX}message_queue_urgent}
directive can be used to place
messages at the head of a queue in LIFO order.

Synchronization can be accomplished when a task can
wait for a message to arrive at a queue.  Also, a task may poll
a queue for the arrival of a message.

The maximum length message which can be sent is set
on a per message queue basis.

@subsection Building a Message Queue Attribute Set

@cindex message queue attributes

In general, an attribute set is built by a bitwise OR
of the desired attribute components.  The set of valid message
queue attributes is provided in the following table:

@itemize @bullet
@item @code{@value{RPREFIX}FIFO} - tasks wait by FIFO (default)
@item @code{@value{RPREFIX}PRIORITY} - tasks wait by priority
@item @code{@value{RPREFIX}LOCAL} - local message queue (default)
@item @code{@value{RPREFIX}GLOBAL} - global message queue
@end itemize


An attribute listed as a default is not required to
appear in the attribute list, although it is a good programming
practice to specify default attributes.  If all defaults are
desired, the attribute @code{@value{RPREFIX}DEFAULT_ATTRIBUTES}
should be specified on this call.

This example demonstrates the attribute_set parameter
needed to create a local message queue with the task priority
waiting queue discipline.  The attribute_set parameter to the
@code{@value{DIRPREFIX}message_queue_create} directive could be either 
@code{@value{RPREFIX}PRIORITY} or
@code{@value{RPREFIX}LOCAL @value{OR} @value{RPREFIX}PRIORITY}.  
The attribute_set parameter can be set to @code{@value{RPREFIX}PRIORITY}
because @code{@value{RPREFIX}LOCAL} is the default for all created
message queues.  If a similar message queue were to be known globally, then the
attribute_set parameter would be
@code{@value{RPREFIX}GLOBAL @value{OR} @value{RPREFIX}PRIORITY}.

@subsection Building a MESSAGE_QUEUE_RECEIVE Option Set

In general, an option is built by a bitwise OR of the
desired option components.  The set of valid options for the
@code{@value{DIRPREFIX}message_queue_receive} directive are
listed in the following table:

@itemize @bullet
@item @code{@value{RPREFIX}WAIT} - task will wait for a message (default)
@item @code{@value{RPREFIX}NO_WAIT} - task should not wait
@end itemize

An option listed as a default is not required to
appear in the option OR list, although it is a good programming
practice to specify default options.  If all defaults are
desired, the option @code{@value{RPREFIX}DEFAULT_OPTIONS} should
be specified on this call.

This example demonstrates the option parameter needed
to poll for a message to arrive.  The option parameter passed to
the @code{@value{DIRPREFIX}message_queue_receive} directive should
be @code{@value{RPREFIX}NO_WAIT}.

@section Operations

@subsection Creating a Message Queue

The @code{@value{DIRPREFIX}message_queue_create} directive creates a message
queue with the user-defined name.  The user specifies the
maximum message size and maximum number of messages which can be
placed in the message queue at one time.  The user may select
FIFO or task priority as the method for placing waiting tasks in
the task wait queue.  RTEMS allocates a Queue Control Block
(QCB) from the QCB free list to maintain the newly created queue
as well as memory for the message buffer pool associated with
this message queue.  RTEMS also generates a message queue ID
which is returned to the calling task.

For GLOBAL message queues, the maximum message size
is effectively limited to the longest message which the MPCI is
capable of transmitting.

@subsection Obtaining Message Queue IDs

When a message queue is created, RTEMS generates a
unique message queue ID.  The message queue ID may be obtained
by either of two methods.  First, as the result of an invocation
of the @code{@value{DIRPREFIX}message_queue_create} directive, the
queue ID is stored in a user provided location.  Second, the queue
ID may be obtained later using the @code{@value{DIRPREFIX}message_queue_ident}
directive.  The queue ID is used by other message manager
directives to access this message queue.

@subsection Receiving a Message

The @code{@value{DIRPREFIX}message_queue_receive} directive attempts to
retrieve a message from the specified message queue.  If at
least one message is in the queue, then the message is removed
from the queue, copied to the caller's message buffer, and
returned immediately along with the length of the message.  When
messages are unavailable, one of the following situations
applies:

@itemize @bullet
@item By default, the calling task will wait forever for the
message to arrive.

@item Specifying the @code{@value{RPREFIX}NO_WAIT} option forces an immediate return
with an error status code.

@item Specifying a timeout limits the period the task will
wait before returning with an error status.
@end itemize

If the task waits for a message, then it is placed in
the message queue's task wait queue in either FIFO or task
priority order.  All tasks waiting on a message queue are
returned an error code when the message queue is deleted.

@subsection Sending a Message

Messages can be sent to a queue with the
@code{@value{DIRPREFIX}message_queue_send} and
@code{@value{DIRPREFIX}message_queue_urgent} directives.  These
directives work identically when tasks are waiting to receive a
message.  A task is removed from the task waiting queue,
unblocked,  and the message is copied to a waiting task's
message buffer.

When no tasks are waiting at the queue,
@code{@value{DIRPREFIX}message_queue_send} places the
message at the rear of the message queue, while
@code{@value{DIRPREFIX}message_queue_urgent} places the message at the
front of the queue.  The message is copied to a message buffer
from this message queue's buffer pool and then placed in the
message queue.  Neither directive can successfully send a
message to a message queue which has a full queue of pending
messages.

@subsection Broadcasting a Message

The @code{@value{DIRPREFIX}message_queue_broadcast} directive sends the same
message to every task waiting on the specified message queue as
an atomic operation.  The message is copied to each waiting
task's message buffer and each task is unblocked.  The number of
tasks which were unblocked is returned to the caller.

@subsection Deleting a Message Queue

The @code{@value{DIRPREFIX}message_queue_delete} directive removes a message
queue from the system and frees its control block as well as the
memory associated with this message queue's message buffer pool.
A message queue can be deleted by any local task that knows the
message queue's ID.  As a result of this directive, all tasks
blocked waiting to receive a message from the message queue will
be readied and returned a status code which indicates that the
message queue was deleted.  Any subsequent references to the
message queue's name and ID are invalid.  Any messages waiting
at the message queue are also deleted and deallocated.

@section Directives

This section details the message manager's
directives.  A subsection is dedicated to each of this manager's
directives and describes the calling sequence, related
constants, usage, and status codes.

@c
@c
@c
@page
@subsection MESSAGE_QUEUE_CREATE - Create a queue

@cindex create a message queue

@subheading CALLING SEQUENCE:

@ifset is-C
@findex rtems_message_queue_create
@example
rtems_status_code rtems_message_queue_create(
  rtems_name        name,
  uint32_t          count,
  size_t            max_message_size,
  rtems_attribute   attribute_set,
  rtems_id         *id
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Message_Queue_Create (
   Name             : in     RTEMS.Name;
   Count            : in     RTEMS.Unsigned32;
   Max_Message_Size : in     RTEMS.Unsigned32;
   Attribute_Set    : in     RTEMS.Attribute;
   ID               :    out RTEMS.ID;
   Result           :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - queue created successfully@*
@code{@value{RPREFIX}INVALID_NAME} - invalid queue name@*
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
@code{@value{RPREFIX}INVALID_NUMBER} - invalid message count@*
@code{@value{RPREFIX}INVALID_SIZE} - invalid message size@*
@code{@value{RPREFIX}TOO_MANY} - too many queues created@*
@code{@value{RPREFIX}UNSATISFIED} - unable to allocate message buffers@*
@code{@value{RPREFIX}MP_NOT_CONFIGURED} - multiprocessing not configured@*
@code{@value{RPREFIX}TOO_MANY} - too many global objects

@subheading DESCRIPTION:

This directive creates a message queue which resides
on the local node with the user-defined name specified in name.
For control and maintenance of the queue, RTEMS allocates and
initializes a QCB.  Memory is allocated from the RTEMS Workspace
for the specified count of messages, each of max_message_size
bytes in length.  The RTEMS-assigned queue id, returned in id,
is used to access the message queue.

Specifying @code{@value{RPREFIX}PRIORITY} in attribute_set causes tasks
waiting for a message to be serviced according to task priority.
When @code{@value{RPREFIX}FIFO} is specified, waiting tasks are serviced
in First In-First Out order.

@subheading NOTES:

This directive will not cause the calling task to be
preempted.

The following message queue attribute constants are
defined by RTEMS:

@itemize @bullet
@item @code{@value{RPREFIX}FIFO} - tasks wait by FIFO (default)
@item @code{@value{RPREFIX}PRIORITY} - tasks wait by priority
@item @code{@value{RPREFIX}LOCAL} - local message queue (default)
@item @code{@value{RPREFIX}GLOBAL} - global message queue
@end itemize

Message queues should not be made global unless
remote tasks must interact with the created message queue.  This
is to avoid the system overhead incurred by the creation of a
global message queue.  When a global message queue is created,
the message queue's name and id must be transmitted to every
node in the system for insertion in the local copy of the global
object table.

For GLOBAL message queues, the maximum message size
is effectively limited to the longest message which the MPCI is
capable of transmitting.

The total number of global objects, including message
queues, is limited by the maximum_global_objects field in the
configuration table.

@c
@c
@c
@page
@subsection MESSAGE_QUEUE_IDENT - Get ID of a queue

@cindex get ID of a message queue

@subheading CALLING SEQUENCE:

@ifset is-C
@findex rtems_message_queue_ident
@example
rtems_status_code rtems_message_queue_ident(
  rtems_name  name,
  uint32_t    node,
  rtems_id   *id
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Message_Queue_Ident (
   Name   : in     RTEMS.Name;
   Node   : in     RTEMS.Unsigned32;
   ID     :    out RTEMS.ID;
   Result :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - queue identified successfully@*
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
@code{@value{RPREFIX}INVALID_NAME} - queue name not found@*
@code{@value{RPREFIX}INVALID_NODE} - invalid node id

@subheading DESCRIPTION:

This directive obtains the queue id associated with
the queue name specified in name.  If the queue name is not
unique, then the queue id will match one of the queues with that
name.  However, this queue id is not guaranteed to correspond to
the desired queue.  The queue id is used with other message
related directives to access the message queue.

@subheading NOTES:

This directive will not cause the running task to be
preempted.

If node is @code{@value{RPREFIX}SEARCH_ALL_NODES}, all nodes are searched
with the local node being searched first.  All other nodes are
searched with the lowest numbered node searched first.

If node is a valid node number which does not
represent the local node, then only the message queues exported
by the designated node are searched.

This directive does not generate activity on remote
nodes.  It accesses only the local copy of the global object
table.

@c
@c
@c
@page
@subsection MESSAGE_QUEUE_DELETE - Delete a queue

@cindex delete a message queue

@subheading CALLING SEQUENCE:

@ifset is-C
@findex rtems_message_queue_delete
@example
rtems_status_code rtems_message_queue_delete(
  rtems_id id
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Message_Queue_Delete (
   ID     : in     RTEMS.ID;
   Result :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - queue deleted successfully@*
@code{@value{RPREFIX}INVALID_ID} - invalid queue id@*
@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - cannot delete remote queue

@subheading DESCRIPTION:

This directive deletes the message queue specified by
id.  As a result of this directive, all tasks blocked waiting to
receive a message from this queue will be readied and returned a
status code which indicates that the message queue was deleted.
If no tasks are waiting, but the queue contains messages, then
RTEMS returns these message buffers back to the system message
buffer pool.  The QCB for this queue as well as the memory for
the message buffers is reclaimed by RTEMS.

@subheading NOTES:

The calling task will be preempted if its preemption
mode is enabled and one or more local tasks with a higher
priority than the calling task are waiting on the deleted queue.
The calling task will NOT be preempted if the tasks that are
waiting are remote tasks.

The calling task does not have to be the task that
created the queue, although the task and queue must reside on
the same node.

When the queue is deleted, any messages in the queue
are returned to the free message buffer pool.  Any information
stored in those messages is lost.

When a global message queue is deleted, the message
queue id must be transmitted to every node in the system for
deletion from the local copy of the global object table.

Proxies, used to represent remote tasks, are
reclaimed when the message queue is deleted.

@c
@c
@c
@page
@subsection MESSAGE_QUEUE_SEND - Put message at rear of a queue

@cindex send message to a queue

@subheading CALLING SEQUENCE:

@ifset is-C
@findex rtems_message_queue_send
@example
rtems_status_code rtems_message_queue_send(
  rtems_id   id,
  cons void *buffer,
  size_t     size
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Message_Queue_Send (
   ID     : in     RTEMS.ID;
   Buffer : in     RTEMS.Address;
   Size   : in     RTEMS.Unsigned32;
   Result :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - message sent successfully@*
@code{@value{RPREFIX}INVALID_ID} - invalid queue id@*
@code{@value{RPREFIX}INVALID_SIZE} - invalid message size@*
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{buffer} is NULL@*
@code{@value{RPREFIX}UNSATISFIED} - out of message buffers@*
@code{@value{RPREFIX}TOO_MANY} - queue's limit has been reached

@subheading DESCRIPTION:

This directive sends the message buffer of size bytes
in length to the queue specified by id.  If a task is waiting at
the queue, then the message is copied to the waiting task's
buffer and the task is unblocked. If no tasks are waiting at the
queue, then the message is copied to a message buffer which is
obtained from this message queue's message buffer pool.  The
message buffer is then placed at the rear of the queue.

@subheading NOTES:

The calling task will be preempted if it has
preemption enabled and a higher priority task is unblocked as
the result of this directive.

Sending a message to a global message queue which
does not reside on the local node will generate a request to the
remote node to post the message on the specified message queue.

If the task to be unblocked resides on a different
node from the message queue, then the message is forwarded to
the appropriate node, the waiting task is unblocked, and the
proxy used to represent the task is reclaimed.

@c
@c
@c
@page
@subsection MESSAGE_QUEUE_URGENT - Put message at front of a queue

@cindex put message at front of queue

@subheading CALLING SEQUENCE:

@ifset is-C
@findex rtems_message_queue_urgent
@example
rtems_status_code rtems_message_queue_urgent(
  rtems_id    id,
  const void *buffer,
  size_t      size
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Message_Queue_Urgent (
   ID     : in     RTEMS.ID;
   Buffer : in     RTEMS.Address;
   Size   : in     RTEMS.Unsigned32;
   Result :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - message sent successfully@*
@code{@value{RPREFIX}INVALID_ID} - invalid queue id@*
@code{@value{RPREFIX}INVALID_SIZE} - invalid message size@*
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{buffer} is NULL@*
@code{@value{RPREFIX}UNSATISFIED} - out of message buffers@*
@code{@value{RPREFIX}TOO_MANY} - queue's limit has been reached

@subheading DESCRIPTION:

This directive sends the message buffer of size bytes
in length to the queue specified by id.  If a task is waiting on
the queue, then the message is copied to the task's buffer and
the task is unblocked.  If no tasks are waiting on the queue,
then the message is copied to a message buffer which is obtained
from this message queue's message buffer pool.  The message
buffer is then placed at the front of the queue.

@subheading NOTES:

The calling task will be preempted if it has
preemption enabled and a higher priority task is unblocked as
the result of this directive.

Sending a message to a global message queue which
does not reside on the local node will generate a request
telling the remote node to post the message on the specified
message queue.

If the task to be unblocked resides on a different
node from the message queue, then the message is forwarded to
the appropriate node, the waiting task is unblocked, and the
proxy used to represent the task is reclaimed.

@c
@c
@c
@page
@subsection MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue

@cindex broadcast message to a queue

@subheading CALLING SEQUENCE:

@ifset is-C
@findex rtems_message_queue_broadcast
@example
rtems_status_code rtems_message_queue_broadcast(
  rtems_id    id,
  const void *buffer,
  size_t      size,
  uint32_t   *count
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Message_Queue_Broadcast (
   ID     : in     RTEMS.ID;
   Buffer : in     RTEMS.Address;
   Size   : in     RTEMS.Unsigned32;
   Count  :    out RTEMS.Unsigned32;
   Result :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - message broadcasted successfully@*
@code{@value{RPREFIX}INVALID_ID} - invalid queue id@*
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{buffer} is NULL@*
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{count} is NULL@*
@code{@value{RPREFIX}INVALID_SIZE} - invalid message size

@subheading DESCRIPTION:

This directive causes all tasks that are waiting at
the queue specified by id to be unblocked and sent the message
contained in buffer.  Before a task is unblocked, the message
buffer of size byes in length is copied to that task's message
buffer.  The number of tasks that were unblocked is returned in
count.

@subheading NOTES:

The calling task will be preempted if it has
preemption enabled and a higher priority task is unblocked as
the result of this directive.

The execution time of this directive is directly
related to the number of tasks waiting on the message queue,
although it is more efficient than the equivalent number of
invocations of @code{@value{DIRPREFIX}message_queue_send}.

Broadcasting a message to a global message queue
which does not reside on the local node will generate a request
telling the remote node to broadcast the message to the
specified message queue.

When a task is unblocked which resides on a different
node from the message queue, a copy of the message is forwarded
to the appropriate node,  the waiting task is unblocked, and the
proxy used to represent the task is reclaimed.

@c
@c
@c
@page
@subsection MESSAGE_QUEUE_RECEIVE - Receive message from a queue

@cindex receive message from a queue

@subheading CALLING SEQUENCE:

@ifset is-C
@findex rtems_message_queue_receive
@example
rtems_status_code rtems_message_queue_receive(
  rtems_id        id,
  void           *buffer,
  size_t         *size,
  rtems_option    option_set,
  rtems_interval  timeout
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Message_Queue_Receive (
   ID         : in     RTEMS.ID;
   Buffer     : in     RTEMS.Address;
   Option_Set : in     RTEMS.Option;
   Timeout    : in     RTEMS.Interval;
   Size       :    out RTEMS.Unsigned32;
   Result     :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - message received successfully@*
@code{@value{RPREFIX}INVALID_ID} - invalid queue id@*
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{buffer} is NULL@*
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{size} is NULL@*
@code{@value{RPREFIX}UNSATISFIED} - queue is empty@*
@code{@value{RPREFIX}TIMEOUT} - timed out waiting for message@*
@code{@value{RPREFIX}OBJECT_WAS_DELETED} - queue deleted while waiting

@subheading DESCRIPTION:

This directive receives a message from the message
queue specified in id.  The @code{@value{RPREFIX}WAIT} and @code{@value{RPREFIX}NO_WAIT} options of the
options parameter allow the calling task to specify whether to
wait for a message to become available or return immediately.
For either option, if there is at least one message in the
queue, then it is copied to buffer, size is set to return the
length of the message in bytes, and this directive returns
immediately with a successful return code.  The buffer has to be big enough to
receive a message of the maximum length with respect to this message queue.

If the calling task chooses to return immediately and
the queue is empty, then a status code indicating this condition
is returned.  If the calling task chooses to wait at the message
queue and the queue is empty, then the calling task is placed on
the message wait queue and blocked.  If the queue was created
with the @code{@value{RPREFIX}PRIORITY} option specified, then
the calling task is inserted into the wait queue according to
its priority.  But, if the queue was created with the
@code{@value{RPREFIX}FIFO} option specified, then the
calling task is placed at the rear of the wait queue.

A task choosing to wait at the queue can optionally
specify a timeout value in the timeout parameter.  The timeout
parameter specifies the maximum interval to wait before the
calling task desires to be unblocked.  If it is set to
@code{@value{RPREFIX}NO_TIMEOUT}, then the calling task will wait forever.

@subheading NOTES:

The following message receive option constants are
defined by RTEMS:

@itemize @bullet
@item @code{@value{RPREFIX}WAIT} - task will wait for a message (default)
@item @code{@value{RPREFIX}NO_WAIT} - task should not wait
@end itemize

Receiving a message from a global message queue which
does not reside on the local node will generate a request to the
remote node to obtain a message from the specified message
queue.  If no message is available and @code{@value{RPREFIX}WAIT} was specified, then
the task must be blocked until a message is posted.  A proxy is
allocated on the remote node to represent the task until the
message is posted.

A clock tick is required to support the timeout functionality of
this directive.

@c
@c
@c
@page
@subsection MESSAGE_QUEUE_GET_NUMBER_PENDING - Get number of messages pending on a queue

@cindex get number of pending messages

@subheading CALLING SEQUENCE:

@ifset is-C
@findex rtems_message_queue_get_number_pending
@example
rtems_status_code rtems_message_queue_get_number_pending(
  rtems_id  id,
  uint32_t *count
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Message_Queue_Get_Number_Pending (
   ID     : in     RTEMS.ID;
   Count  :    out RTEMS.Unsigned32;
   Result :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - number of messages pending returned successfully@*
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{count} is NULL@*
@code{@value{RPREFIX}INVALID_ID} - invalid queue id

@subheading DESCRIPTION:

This directive returns the number of messages pending on this
message queue in count.  If no messages are present
on the queue, count is set to zero.

@subheading NOTES:

Getting the number of pending messages on a global message queue which
does not reside on the local node will generate a request to the
remote node to actually obtain the pending message count for
the specified message queue.


@c
@c
@c
@page
@subsection MESSAGE_QUEUE_FLUSH - Flush all messages on a queue

@cindex flush messages on a queue

@subheading CALLING SEQUENCE:

@ifset is-C
@findex rtems_message_queue_flush
@example
rtems_status_code rtems_message_queue_flush(
  rtems_id  id,
  uint32_t *count
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Message_Queue_Flush (
   ID     : in     RTEMS.ID;
   Count  :    out RTEMS.Unsigned32;
   Result :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - message queue flushed successfully@*
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{count} is NULL@*
@code{@value{RPREFIX}INVALID_ID} - invalid queue id

@subheading DESCRIPTION:

This directive removes all pending messages from the
specified queue id.  The number of messages removed is returned
in count.  If no messages are present on the queue, count is set
to zero.

@subheading NOTES:

Flushing all messages on a global message queue which
does not reside on the local node will generate a request to the
remote node to actually flush the specified message queue.