summaryrefslogtreecommitdiffstats
path: root/c-user/message/directives.rst
blob: 11ff10540b2bd7faeb7766dcf4e138bec70106b5 (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
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
.. SPDX-License-Identifier: CC-BY-SA-4.0

.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)

.. This file is part of the RTEMS quality process and was automatically
.. generated.  If you find something that needs to be fixed or
.. worded better please post a report or patch to an RTEMS mailing list
.. or raise a bug report:
..
.. https://www.rtems.org/bugs.html
..
.. For information on updating and regenerating please refer to the How-To
.. section in the Software Requirements Engineering chapter of the
.. RTEMS Software Engineering manual.  The manual is provided as a part of
.. a release.  For development sources please refer to the online
.. documentation at:
..
.. https://docs.rtems.org

.. _MessageManagerDirectives:

Directives
==========

This section details the directives of the Message Manager. A subsection is
dedicated to each of this manager's directives and lists the calling sequence,
parameters, description, return values, and notes of the directive.

.. Generated from spec:/rtems/message/if/create

.. raw:: latex

    \clearpage

.. index:: rtems_message_queue_create()
.. index:: create a message queue

.. _InterfaceRtemsMessageQueueCreate:

rtems_message_queue_create()
----------------------------

Creates a message queue.

.. rubric:: CALLING SEQUENCE:

.. code-block:: c

    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
    );

.. rubric:: PARAMETERS:

``name``
    This parameter is the object name of the message queue.

``count``
    This parameter is the maximum count of pending messages supported by the
    message queue.

``max_message_size``
    This parameter is the maximum size in bytes of a message supported by the
    message queue.

``attribute_set``
    This parameter is the attribute set of the message queue.

``id``
    This parameter is the pointer to an object identifier variable.  When the
    directive call is successful, the identifier of the created message queue
    will be stored in this variable.

.. rubric:: DESCRIPTION:

This directive creates a message queue which resides on the local node.  The
message queue has the user-defined object name specified in ``name``.  Memory
is allocated from the RTEMS Workspace for the count of messages specified in
``count``, each of ``max_message_size`` bytes in length.  The assigned object
identifier is returned in ``id``.  This identifier is used to access the
message queue with other message queue related directives.

The **attribute set** specified in ``attribute_set`` is built through a
*bitwise or* of the attribute constants described below.  Not all combinations
of attributes are allowed.  Some attributes are mutually exclusive.  If
mutually exclusive attributes are combined, the behaviour is undefined.
Attributes not mentioned below are not evaluated by this directive and have no
effect.  Default attributes can be selected by using the
:c:macro:`RTEMS_DEFAULT_ATTRIBUTES` constant.  The attribute set defines

* the scope of the message queue: :c:macro:`RTEMS_LOCAL` (default) or
  :c:macro:`RTEMS_GLOBAL` and

* the task wait queue discipline used by the message queue:
  :c:macro:`RTEMS_FIFO` (default) or :c:macro:`RTEMS_PRIORITY`.

The message queue has a local or global **scope** in a multiprocessing network
(this attribute does not refer to SMP systems).  The scope is selected by the
mutually exclusive :c:macro:`RTEMS_LOCAL` and :c:macro:`RTEMS_GLOBAL`
attributes.

* A **local scope** is the default and can be emphasized through the use of the
  :c:macro:`RTEMS_LOCAL` attribute.  A local message queue can be only used by
  the node which created it.

* A **global scope** is established if the :c:macro:`RTEMS_GLOBAL` attribute is
  set.  Setting the global attribute in a single node system has no effect.

The **task wait queue discipline** is selected by the mutually exclusive
:c:macro:`RTEMS_FIFO` and :c:macro:`RTEMS_PRIORITY` attributes. The discipline
defines the order in which tasks wait for a message to receive on a currently
empty message queue.

* The **FIFO discipline** is the default and can be emphasized through use of
  the :c:macro:`RTEMS_FIFO` attribute.

* The **priority discipline** is selected by the :c:macro:`RTEMS_PRIORITY`
  attribute.

.. rubric:: RETURN VALUES:

:c:macro:`RTEMS_SUCCESSFUL`
    The requested operation was successful.

:c:macro:`RTEMS_INVALID_NAME`
    The ``name`` parameter was invalid.

:c:macro:`RTEMS_INVALID_ADDRESS`
    The ``id`` parameter was `NULL
    <https://en.cppreference.com/w/c/types/NULL>`_.

:c:macro:`RTEMS_INVALID_NUMBER`
    The ``count`` parameter was invalid.

:c:macro:`RTEMS_INVALID_SIZE`
    The ``max_message_size`` parameter was invalid.

:c:macro:`RTEMS_TOO_MANY`
    There was no inactive object available to create a message queue.  The
    number of message queue available to the application is configured through
    the :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` application configuration
    option.

:c:macro:`RTEMS_TOO_MANY`
    In multiprocessing configurations, there was no inactive global object
    available to create a global message queue.  The number of global objects
    available to the application is configured through the
    :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application configuration
    option.

:c:macro:`RTEMS_INVALID_NUMBER`
    The product of ``count`` and ``max_message_size`` is greater than the
    maximum storage size.

:c:macro:`RTEMS_UNSATISFIED`
    There was not enough memory available in the RTEMS Workspace to allocate
    the message buffers for the message queue.

.. rubric:: NOTES:

For message queues with a global scope, the maximum message size is effectively
limited to the longest message which the :term:`MPCI` is capable of
transmitting.

For control and maintenance of the message queue, RTEMS allocates a :term:`QCB`
from the local QCB free pool and initializes it.

The QCB for a global message queue is allocated on the local node.  Message
queues should not be made global unless remote tasks must interact with the
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 identifier must be transmitted to every node in the system for
insertion in the local copy of the global object table.

.. rubric:: CONSTRAINTS:

The following constraints apply to this directive:

* The directive may be called from within device driver initialization context.

* The directive may be called from within task context.

* The directive may obtain and release the object allocator mutex.  This may
  cause the calling task to be preempted.

* When the directive operates on a global object, the directive sends a message
  to remote nodes.  This may preempt the calling task.

* The number of message queues available to the application is configured
  through the :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` application configuration
  option.

* Where the object class corresponding to the directive is configured to use
  unlimited objects, the directive may allocate memory from the RTEMS
  Workspace.

* The number of global objects available to the application is configured
  through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application
  configuration option.

.. Generated from spec:/rtems/message/if/construct

.. raw:: latex

    \clearpage

.. index:: rtems_message_queue_construct()

.. _InterfaceRtemsMessageQueueConstruct:

rtems_message_queue_construct()
-------------------------------

Constructs a message queue from the specified the message queue configuration.

.. rubric:: CALLING SEQUENCE:

.. code-block:: c

    rtems_status_code rtems_message_queue_construct(
      const rtems_message_queue_config *config,
      rtems_id                         *id
    );

.. rubric:: PARAMETERS:

``config``
    This parameter is the message queue configuration.

``id``
    This parameter is the pointer to an object identifier variable.  When the
    directive call is successful, the identifier of the constructed message
    queue will be stored in this variable.

.. rubric:: RETURN VALUES:

:c:macro:`RTEMS_SUCCESSFUL`
    The requested operation was successful.

:c:macro:`RTEMS_INVALID_ADDRESS`
    The ``config`` parameter was `NULL
    <https://en.cppreference.com/w/c/types/NULL>`_.

:c:macro:`RTEMS_INVALID_NAME`
    The message queue name in the configuration was invalid.

:c:macro:`RTEMS_INVALID_ADDRESS`
    The ``id`` parameter was `NULL
    <https://en.cppreference.com/w/c/types/NULL>`_.

:c:macro:`RTEMS_INVALID_NUMBER`
    The maximum number of pending messages in the configuration was zero.

:c:macro:`RTEMS_INVALID_SIZE`
    The maximum message size in the configuration was zero.

:c:macro:`RTEMS_TOO_MANY`
    There was no inactive message queue object available to construct a message
    queue.

:c:macro:`RTEMS_TOO_MANY`
    In multiprocessing configurations, there was no inactive global object
    available to construct a global message queue.

:c:macro:`RTEMS_INVALID_SIZE`
    The maximum message size in the configuration was too big and resulted in
    integer overflows in calculations carried out to determine the size of the
    message buffer area.

:c:macro:`RTEMS_INVALID_NUMBER`
    The maximum number of pending messages in the configuration was too big and
    resulted in integer overflows in calculations carried out to determine the
    size of the message buffer area.

:c:macro:`RTEMS_UNSATISFIED`
    The message queue storage area begin pointer in the configuration was `NULL
    <https://en.cppreference.com/w/c/types/NULL>`_.

:c:macro:`RTEMS_UNSATISFIED`
    The message queue storage area size in the configuration was not equal to
    the size calculated from the maximum number of pending messages and the
    maximum message size.

.. rubric:: NOTES:

In contrast to message queues created by
:ref:`InterfaceRtemsMessageQueueCreate`, the message queues constructed by this
directive use a user-provided message buffer storage area.

This directive is intended for applications which do not want to use the RTEMS
Workspace and instead statically allocate all operating system resources.  An
application based solely on static allocation can avoid any runtime memory
allocators.  This can simplify the application architecture as well as any
analysis that may be required.

The value for :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY` should not include memory
for message queues constructed by :ref:`InterfaceRtemsMessageQueueConstruct`.

.. rubric:: CONSTRAINTS:

The following constraints apply to this directive:

* The directive may be called from within device driver initialization context.

* The directive may be called from within task context.

* The directive may obtain and release the object allocator mutex.  This may
  cause the calling task to be preempted.

* When the directive operates on a global object, the directive sends a message
  to remote nodes.  This may preempt the calling task.

* The number of message queues available to the application is configured
  through the :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` application configuration
  option.

* Where the object class corresponding to the directive is configured to use
  unlimited objects, the directive may allocate memory from the RTEMS
  Workspace.

* The number of global objects available to the application is configured
  through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application
  configuration option.

.. Generated from spec:/rtems/message/if/ident

.. raw:: latex

    \clearpage

.. index:: rtems_message_queue_ident()

.. _InterfaceRtemsMessageQueueIdent:

rtems_message_queue_ident()
---------------------------

Identifies a message queue by the object name.

.. rubric:: CALLING SEQUENCE:

.. code-block:: c

    rtems_status_code rtems_message_queue_ident(
      rtems_name name,
      uint32_t   node,
      rtems_id  *id
    );

.. rubric:: PARAMETERS:

``name``
    This parameter is the object name to look up.

``node``
    This parameter is the node or node set to search for a matching object.

``id``
    This parameter is the pointer to an object identifier variable.  When the
    directive call is successful, the object identifier of an object with the
    specified name will be stored in this variable.

.. rubric:: DESCRIPTION:

This directive obtains a message queue identifier associated with the message
queue name specified in ``name``.

The node to search is specified in ``node``.  It shall be

* a valid node number,

* the constant :c:macro:`RTEMS_SEARCH_ALL_NODES` to search in all nodes,

* the constant :c:macro:`RTEMS_SEARCH_LOCAL_NODE` to search in the local node
  only, or

* the constant :c:macro:`RTEMS_SEARCH_OTHER_NODES` to search in all nodes
  except the local node.

.. rubric:: RETURN VALUES:

:c:macro:`RTEMS_SUCCESSFUL`
    The requested operation was successful.

:c:macro:`RTEMS_INVALID_ADDRESS`
    The ``id`` parameter was `NULL
    <https://en.cppreference.com/w/c/types/NULL>`_.

:c:macro:`RTEMS_INVALID_NAME`
    The ``name`` parameter was 0.

:c:macro:`RTEMS_INVALID_NAME`
    There was no object with the specified name on the specified nodes.

:c:macro:`RTEMS_INVALID_NODE`
    In multiprocessing configurations, the specified node was invalid.

.. rubric:: NOTES:

If the message queue name is not unique, then the message queue identifier will
match the first message queue with that name in the search order. However, this
message queue identifier is not guaranteed to correspond to the desired message
queue.

The objects are searched from lowest to the highest index.  If ``node`` is
:c:macro:`RTEMS_SEARCH_ALL_NODES`, all nodes are searched with the local node
being searched first.  All other nodes are searched from lowest to the highest
node number.

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.

The message queue identifier is used with other message related directives to
access the message queue.

.. rubric:: CONSTRAINTS:

The following constraints apply to this directive:

* The directive may be called from within any runtime context.

* The directive will not cause the calling task to be preempted.

.. Generated from spec:/rtems/message/if/delete

.. raw:: latex

    \clearpage

.. index:: rtems_message_queue_delete()
.. index:: delete a message queue

.. _InterfaceRtemsMessageQueueDelete:

rtems_message_queue_delete()
----------------------------

Deletes the message queue.

.. rubric:: CALLING SEQUENCE:

.. code-block:: c

    rtems_status_code rtems_message_queue_delete( rtems_id id );

.. rubric:: PARAMETERS:

``id``
    This parameter is the message queue identifier.

.. rubric:: 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.

.. rubric:: RETURN VALUES:

:c:macro:`RTEMS_SUCCESSFUL`
    The requested operation was successful.

:c:macro:`RTEMS_INVALID_ID`
    There was no message queue associated with the identifier specified by
    ``id``.

:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT`
    The message queue resided on a remote node.

.. rubric:: NOTES:

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

The :term:`QCB` for the deleted message queue is reclaimed by RTEMS.

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

The message queue must reside on the local node, even if the message queue was
created with the :c:macro:`RTEMS_GLOBAL` attribute.

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

.. rubric:: CONSTRAINTS:

The following constraints apply to this directive:

* The directive may be called from within device driver initialization context.

* The directive may be called from within task context.

* The directive may obtain and release the object allocator mutex.  This may
  cause the calling task to be preempted.

* When the directive operates on a global object, the directive sends a message
  to remote nodes.  This may preempt the calling task.

* The calling task does not have to be the task that created the object.  Any
  local task that knows the object identifier can delete the object.

* Where the object class corresponding to the directive is configured to use
  unlimited objects, the directive may free memory to the RTEMS Workspace.

.. Generated from spec:/rtems/message/if/send

.. raw:: latex

    \clearpage

.. index:: rtems_message_queue_send()
.. index:: send message to a queue

.. _InterfaceRtemsMessageQueueSend:

rtems_message_queue_send()
--------------------------

Puts the message at the rear of the queue.

.. rubric:: CALLING SEQUENCE:

.. code-block:: c

    rtems_status_code rtems_message_queue_send(
      rtems_id    id,
      const void *buffer,
      size_t      size
    );

.. rubric:: PARAMETERS:

``id``
    This parameter is the queue identifier.

``buffer``
    This parameter is the begin address of the message buffer to send.

``size``
    This parameter is the size in bytes of the message buffer to send.

.. rubric:: 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.

.. rubric:: RETURN VALUES:

:c:macro:`RTEMS_SUCCESSFUL`
    The requested operation was successful.

:c:macro:`RTEMS_INVALID_ID`
    There was no queue associated with the identifier specified by ``id``.

:c:macro:`RTEMS_INVALID_ADDRESS`
    The ``buffer`` parameter was `NULL
    <https://en.cppreference.com/w/c/types/NULL>`_.

:c:macro:`RTEMS_INVALID_SIZE`
    The size of the message exceeded the maximum message size of the queue as
    defined by :ref:`InterfaceRtemsMessageQueueCreate` or
    :ref:`InterfaceRtemsMessageQueueConstruct`.

:c:macro:`RTEMS_TOO_MANY`
    The maximum number of pending messages supported by the queue as defined by
    :ref:`InterfaceRtemsMessageQueueCreate` or
    :ref:`InterfaceRtemsMessageQueueConstruct` has been reached.

.. rubric:: CONSTRAINTS:

The following constraints apply to this directive:

* The directive may be called from within task context.

* The directive may be called from within interrupt context.

* The directive may unblock a task.  This may cause the calling task to be
  preempted.

* When the directive operates on a remote object, the directive sends a message
  to the remote node and waits for a reply.  This will preempt the calling
  task.

.. Generated from spec:/rtems/message/if/urgent

.. raw:: latex

    \clearpage

.. index:: rtems_message_queue_urgent()
.. index:: put message at front of queue

.. _InterfaceRtemsMessageQueueUrgent:

rtems_message_queue_urgent()
----------------------------

Puts the message at the front of the queue.

.. rubric:: CALLING SEQUENCE:

.. code-block:: c

    rtems_status_code rtems_message_queue_urgent(
      rtems_id    id,
      const void *buffer,
      size_t      size
    );

.. rubric:: PARAMETERS:

``id``
    This parameter is the queue identifier.

``buffer``
    This parameter is the begin address of the message buffer to send urgently.

``size``
    This parameter is the size in bytes of the message buffer to send urgently.

.. rubric:: 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 front of the queue.

.. rubric:: RETURN VALUES:

:c:macro:`RTEMS_SUCCESSFUL`
    The requested operation was successful.

:c:macro:`RTEMS_INVALID_ID`
    There was no queue associated with the identifier specified by ``id``.

:c:macro:`RTEMS_INVALID_ADDRESS`
    The ``buffer`` parameter was `NULL
    <https://en.cppreference.com/w/c/types/NULL>`_.

:c:macro:`RTEMS_INVALID_SIZE`
    The size of the message exceeded the maximum message size of the queue as
    defined by :ref:`InterfaceRtemsMessageQueueCreate` or
    :ref:`InterfaceRtemsMessageQueueConstruct`.

:c:macro:`RTEMS_TOO_MANY`
    The maximum number of pending messages supported by the queue as defined by
    :ref:`InterfaceRtemsMessageQueueCreate` or
    :ref:`InterfaceRtemsMessageQueueConstruct` has been reached.

.. rubric:: CONSTRAINTS:

The following constraints apply to this directive:

* The directive may be called from within task context.

* The directive may be called from within interrupt context.

* The directive may unblock a task.  This may cause the calling task to be
  preempted.

* When the directive operates on a remote object, the directive sends a message
  to the remote node and waits for a reply.  This will preempt the calling
  task.

.. Generated from spec:/rtems/message/if/broadcast

.. raw:: latex

    \clearpage

.. index:: rtems_message_queue_broadcast()
.. index:: broadcast message to a queue

.. _InterfaceRtemsMessageQueueBroadcast:

rtems_message_queue_broadcast()
-------------------------------

Broadcasts the messages to the tasks waiting at the queue.

.. rubric:: CALLING SEQUENCE:

.. code-block:: c

    rtems_status_code rtems_message_queue_broadcast(
      rtems_id    id,
      const void *buffer,
      size_t      size,
      uint32_t   *count
    );

.. rubric:: PARAMETERS:

``id``
    This parameter is the queue identifier.

``buffer``
    This parameter is the begin address of the message buffer to broadcast.

``size``
    This parameter is the size in bytes of the message buffer to broadcast.

``count``
    This parameter is the pointer to an `uint32_t
    <https://en.cppreference.com/w/c/types/integer>`_ variable.  When the
    directive call is successful, the number of unblocked tasks will be stored
    in this variable.

.. rubric:: 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``.

.. rubric:: RETURN VALUES:

:c:macro:`RTEMS_SUCCESSFUL`
    The requested operation was successful.

:c:macro:`RTEMS_INVALID_ID`
    There was no queue associated with the identifier specified by ``id``.

:c:macro:`RTEMS_INVALID_ADDRESS`
    The ``buffer`` parameter was `NULL
    <https://en.cppreference.com/w/c/types/NULL>`_.

:c:macro:`RTEMS_INVALID_ADDRESS`
    The ``count`` parameter was `NULL
    <https://en.cppreference.com/w/c/types/NULL>`_.

:c:macro:`RTEMS_INVALID_SIZE`
    The size of the message exceeded the maximum message size of the queue as
    defined by :ref:`InterfaceRtemsMessageQueueCreate` or
    :ref:`InterfaceRtemsMessageQueueConstruct`.

.. rubric:: NOTES:

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 :ref:`InterfaceRtemsMessageQueueSend`.

.. rubric:: CONSTRAINTS:

The following constraints apply to this directive:

* The directive may be called from within task context.

* The directive may be called from within interrupt context.

* The directive may unblock a task.  This may cause the calling task to be
  preempted.

* When the directive operates on a remote object, the directive sends a message
  to the remote node and waits for a reply.  This will preempt the calling
  task.

.. Generated from spec:/rtems/message/if/receive

.. raw:: latex

    \clearpage

.. index:: rtems_message_queue_receive()
.. index:: receive message from a queue

.. _InterfaceRtemsMessageQueueReceive:

rtems_message_queue_receive()
-----------------------------

Receives a message from the queue.

.. rubric:: CALLING SEQUENCE:

.. code-block:: c

    rtems_status_code rtems_message_queue_receive(
      rtems_id       id,
      void          *buffer,
      size_t        *size,
      rtems_option   option_set,
      rtems_interval timeout
    );

.. rubric:: PARAMETERS:

``id``
    This parameter is the queue identifier.

``buffer``
    This parameter is the begin address of the buffer to receive the message.
    The buffer shall be large enough to receive a message of the maximum length
    of the queue as defined by :ref:`InterfaceRtemsMessageQueueCreate` or
    :ref:`InterfaceRtemsMessageQueueConstruct`.  The ``size`` parameter cannot
    be used to specify the size of the buffer.

``size``
    This parameter is the pointer to a `size_t
    <https://en.cppreference.com/w/c/types/size_t>`_ variable.  When the
    directive call is successful, the size in bytes of the received messages
    will be stored in this variable.  This parameter cannot be used to specify
    the size of the buffer.

``option_set``
    This parameter is the option set.

``timeout``
    This parameter is the timeout in :term:`clock ticks <clock tick>` if the
    :c:macro:`RTEMS_WAIT` option is set.  Use :c:macro:`RTEMS_NO_TIMEOUT` to
    wait potentially forever.

.. rubric:: DESCRIPTION:

This directive receives a message from the queue specified by ``id``.

The **option set** specified in ``option_set`` is built through a *bitwise or*
of the option constants described below.  Not all combinations of options are
allowed.  Some options are mutually exclusive.  If mutually exclusive options
are combined, the behaviour is undefined.  Options not mentioned below are not
evaluated by this directive and have no effect. Default options can be selected
by using the :c:macro:`RTEMS_DEFAULT_OPTIONS` constant.

The calling task can **wait** or **try to receive** a message from the queue
according to the mutually exclusive :c:macro:`RTEMS_WAIT` and
:c:macro:`RTEMS_NO_WAIT` options.

* **Waiting to receive** a message from the queue is the default and can be
  emphasized through the use of the :c:macro:`RTEMS_WAIT` option. The
  ``timeout`` parameter defines how long the calling task is willing to wait.
  Use :c:macro:`RTEMS_NO_TIMEOUT` to wait potentially forever, otherwise set a
  timeout interval in clock ticks.

* **Trying to receive** a message from the queue is selected by the
  :c:macro:`RTEMS_NO_WAIT` option.  If this option is defined, then the
  ``timeout`` parameter is ignored.  When a message from the queue cannot be
  immediately received, then the :c:macro:`RTEMS_UNSATISFIED` status is
  returned.

With either :c:macro:`RTEMS_WAIT` or :c:macro:`RTEMS_NO_WAIT` if there is at
least one message in the queue, then it is copied to the buffer, the size is
set to return the length of the message in bytes, and this directive returns
immediately with the :c:macro:`RTEMS_SUCCESSFUL` status 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
the directive returns immediately with the :c:macro:`RTEMS_UNSATISFIED` status
code.  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 :c:macro:`RTEMS_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 :c:macro:`RTEMS_FIFO`
option specified, then the calling task is placed at the rear of the wait
queue.

.. rubric:: RETURN VALUES:

:c:macro:`RTEMS_SUCCESSFUL`
    The requested operation was successful.

:c:macro:`RTEMS_INVALID_ID`
    There was no queue associated with the identifier specified by ``id``.

:c:macro:`RTEMS_INVALID_ADDRESS`
    The ``buffer`` parameter was `NULL
    <https://en.cppreference.com/w/c/types/NULL>`_.

:c:macro:`RTEMS_INVALID_ADDRESS`
    The ``size`` parameter was `NULL
    <https://en.cppreference.com/w/c/types/NULL>`_.

:c:macro:`RTEMS_UNSATISFIED`
    The queue was empty.

:c:macro:`RTEMS_UNSATISFIED`
    The queue was flushed while the calling task was waiting to receive a
    message.

:c:macro:`RTEMS_TIMEOUT`
    The timeout happened while the calling task was waiting to receive a
    message

:c:macro:`RTEMS_OBJECT_WAS_DELETED`
    The queue was deleted while the calling task was waiting to receive a
    message.

.. rubric:: CONSTRAINTS:

The following constraints apply to this directive:

* When a local queue is accessed and the :c:macro:`RTEMS_NO_WAIT` option is
  set, the directive may be called from within interrupt context.

* The directive may be called from within task context.

* When the request cannot be immediately satisfied and the
  :c:macro:`RTEMS_WAIT` option is set, the calling task blocks at some point
  during the directive call.

* The timeout functionality of the directive requires a :term:`clock tick`.

* When the directive operates on a remote object, the directive sends a message
  to the remote node and waits for a reply.  This will preempt the calling
  task.

.. Generated from spec:/rtems/message/if/get-number-pending

.. raw:: latex

    \clearpage

.. index:: rtems_message_queue_get_number_pending()
.. index:: get number of pending messages

.. _InterfaceRtemsMessageQueueGetNumberPending:

rtems_message_queue_get_number_pending()
----------------------------------------

Gets the number of messages pending on the queue.

.. rubric:: CALLING SEQUENCE:

.. code-block:: c

    rtems_status_code rtems_message_queue_get_number_pending(
      rtems_id  id,
      uint32_t *count
    );

.. rubric:: PARAMETERS:

``id``
    This parameter is the queue identifier.

``count``
    This parameter is the pointer to an `uint32_t
    <https://en.cppreference.com/w/c/types/integer>`_ variable.  When the
    directive call is successful, the number of pending messages will be stored
    in this variable.

.. rubric:: DESCRIPTION:

This directive returns the number of messages pending on the queue specified by
``id`` in ``count``.  If no messages are present on the queue, count is set to
zero.

.. rubric:: RETURN VALUES:

:c:macro:`RTEMS_SUCCESSFUL`
    The requested operation was successful.

:c:macro:`RTEMS_INVALID_ID`
    There was no queue associated with the identifier specified by ``id``.

:c:macro:`RTEMS_INVALID_ADDRESS`
    The ``count`` parameter was `NULL
    <https://en.cppreference.com/w/c/types/NULL>`_.

.. rubric:: CONSTRAINTS:

The following constraints apply to this directive:

* The directive may be called from within task context.

* The directive may be called from within interrupt context.

* When the directive operates on a remote object, the directive sends a message
  to the remote node and waits for a reply.  This will preempt the calling
  task.

.. Generated from spec:/rtems/message/if/flush

.. raw:: latex

    \clearpage

.. index:: rtems_message_queue_flush()
.. index:: flush messages on a queue

.. _InterfaceRtemsMessageQueueFlush:

rtems_message_queue_flush()
---------------------------

Flushes all messages on the queue.

.. rubric:: CALLING SEQUENCE:

.. code-block:: c

    rtems_status_code rtems_message_queue_flush( rtems_id id, uint32_t *count );

.. rubric:: PARAMETERS:

``id``
    This parameter is the queue identifier.

``count``
    This parameter is the pointer to an `uint32_t
    <https://en.cppreference.com/w/c/types/integer>`_ variable.  When the
    directive call is successful, the number of unblocked tasks will be stored
    in this variable.

.. rubric:: DESCRIPTION:

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

.. rubric:: RETURN VALUES:

:c:macro:`RTEMS_SUCCESSFUL`
    The requested operation was successful.

:c:macro:`RTEMS_INVALID_ID`
    There was no queue associated with the identifier specified by ``id``.

:c:macro:`RTEMS_INVALID_ADDRESS`
    The ``count`` parameter was `NULL
    <https://en.cppreference.com/w/c/types/NULL>`_.

.. rubric:: CONSTRAINTS:

The following constraints apply to this directive:

* The directive may be called from within task context.

* The directive may be called from within interrupt context.

* When the directive operates on a remote object, the directive sends a message
  to the remote node and waits for a reply.  This will preempt the calling
  task.

.. Generated from spec:/rtems/message/if/buffer

.. raw:: latex

    \clearpage

.. index:: RTEMS_MESSAGE_QUEUE_BUFFER()

.. _InterfaceRTEMSMESSAGEQUEUEBUFFER:

RTEMS_MESSAGE_QUEUE_BUFFER()
----------------------------

Defines a structure which can be used as a message queue buffer for messages of
the specified maximum size.

.. rubric:: CALLING SEQUENCE:

.. code-block:: c

    #define RTEMS_MESSAGE_QUEUE_BUFFER( maximum_message_size )

.. rubric:: PARAMETERS:

``maximum_message_size``
    This parameter is the maximum message size in bytes.

.. rubric:: NOTES:

Use this macro to define the message buffer storage area for
:ref:`InterfaceRtemsMessageQueueConstruct`.