source: rtems-docs/c-user/message/directives.rst @ c4df72c

Last change on this file since c4df72c was c4df72c, checked in by Martin Erik Werner <martinerikwerner.aac@…>, on 01/22/23 at 00:04:55

c-user/message/directives.rst: byes->bytes typo

  • Property mode set to 100644
File size: 33.5 KB
Line 
1.. SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
4.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
5
6.. This file is part of the RTEMS quality process and was automatically
7.. generated.  If you find something that needs to be fixed or
8.. worded better please post a report or patch to an RTEMS mailing list
9.. or raise a bug report:
10..
11.. https://www.rtems.org/bugs.html
12..
13.. For information on updating and regenerating please refer to the How-To
14.. section in the Software Requirements Engineering chapter of the
15.. RTEMS Software Engineering manual.  The manual is provided as a part of
16.. a release.  For development sources please refer to the online
17.. documentation at:
18..
19.. https://docs.rtems.org
20
21.. _MessageManagerDirectives:
22
23Directives
24==========
25
26This section details the directives of the Message Manager. A subsection is
27dedicated to each of this manager's directives and lists the calling sequence,
28parameters, description, return values, and notes of the directive.
29
30.. Generated from spec:/rtems/message/if/create
31
32.. raw:: latex
33
34    \clearpage
35
36.. index:: rtems_message_queue_create()
37.. index:: create a message queue
38
39.. _InterfaceRtemsMessageQueueCreate:
40
41rtems_message_queue_create()
42----------------------------
43
44Creates a message queue.
45
46.. rubric:: CALLING SEQUENCE:
47
48.. code-block:: c
49
50    rtems_status_code rtems_message_queue_create(
51      rtems_name      name,
52      uint32_t        count,
53      size_t          max_message_size,
54      rtems_attribute attribute_set,
55      rtems_id       *id
56    );
57
58.. rubric:: PARAMETERS:
59
60``name``
61    This parameter is the object name of the message queue.
62
63``count``
64    This parameter is the maximum count of pending messages supported by the
65    message queue.
66
67``max_message_size``
68    This parameter is the maximum size in bytes of a message supported by the
69    message queue.
70
71``attribute_set``
72    This parameter is the attribute set of the message queue.
73
74``id``
75    This parameter is the pointer to an :c:type:`rtems_id` object.  When the
76    directive call is successful, the identifier of the created message queue
77    will be stored in this object.
78
79.. rubric:: DESCRIPTION:
80
81This directive creates a message queue which resides on the local node.  The
82message queue has the user-defined object name specified in ``name``.  Memory
83is allocated from the RTEMS Workspace for the count of messages specified in
84``count``, each of ``max_message_size`` bytes in length.  The assigned object
85identifier is returned in ``id``.  This identifier is used to access the
86message queue with other message queue related directives.
87
88The **attribute set** specified in ``attribute_set`` is built through a
89*bitwise or* of the attribute constants described below.  Not all combinations
90of attributes are allowed.  Some attributes are mutually exclusive.  If
91mutually exclusive attributes are combined, the behaviour is undefined.
92Attributes not mentioned below are not evaluated by this directive and have no
93effect.  Default attributes can be selected by using the
94:c:macro:`RTEMS_DEFAULT_ATTRIBUTES` constant.  The attribute set defines
95
96* the scope of the message queue: :c:macro:`RTEMS_LOCAL` (default) or
97  :c:macro:`RTEMS_GLOBAL` and
98
99* the task wait queue discipline used by the message queue:
100  :c:macro:`RTEMS_FIFO` (default) or :c:macro:`RTEMS_PRIORITY`.
101
102The message queue has a local or global **scope** in a multiprocessing network
103(this attribute does not refer to SMP systems).  The scope is selected by the
104mutually exclusive :c:macro:`RTEMS_LOCAL` and :c:macro:`RTEMS_GLOBAL`
105attributes.
106
107* A **local scope** is the default and can be emphasized through the use of the
108  :c:macro:`RTEMS_LOCAL` attribute.  A local message queue can be only used by
109  the node which created it.
110
111* A **global scope** is established if the :c:macro:`RTEMS_GLOBAL` attribute is
112  set.  Setting the global attribute in a single node system has no effect.
113
114The **task wait queue discipline** is selected by the mutually exclusive
115:c:macro:`RTEMS_FIFO` and :c:macro:`RTEMS_PRIORITY` attributes. The discipline
116defines the order in which tasks wait for a message to receive on a currently
117empty message queue.
118
119* The **FIFO discipline** is the default and can be emphasized through use of
120  the :c:macro:`RTEMS_FIFO` attribute.
121
122* The **priority discipline** is selected by the :c:macro:`RTEMS_PRIORITY`
123  attribute.
124
125.. rubric:: RETURN VALUES:
126
127:c:macro:`RTEMS_SUCCESSFUL`
128    The requested operation was successful.
129
130:c:macro:`RTEMS_INVALID_NAME`
131    The ``name`` parameter was invalid.
132
133:c:macro:`RTEMS_INVALID_ADDRESS`
134    The ``id`` parameter was `NULL
135    <https://en.cppreference.com/w/c/types/NULL>`_.
136
137:c:macro:`RTEMS_INVALID_NUMBER`
138    The ``count`` parameter was invalid.
139
140:c:macro:`RTEMS_INVALID_SIZE`
141    The ``max_message_size`` parameter was invalid.
142
143:c:macro:`RTEMS_TOO_MANY`
144    There was no inactive object available to create a message queue.  The
145    number of message queue available to the application is configured through
146    the :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` application configuration
147    option.
148
149:c:macro:`RTEMS_TOO_MANY`
150    In multiprocessing configurations, there was no inactive global object
151    available to create a global message queue.  The number of global objects
152    available to the application is configured through the
153    :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application configuration
154    option.
155
156:c:macro:`RTEMS_INVALID_NUMBER`
157    The product of ``count`` and ``max_message_size`` is greater than the
158    maximum storage size.
159
160:c:macro:`RTEMS_UNSATISFIED`
161    There was not enough memory available in the RTEMS Workspace to allocate
162    the message buffers for the message queue.
163
164.. rubric:: NOTES:
165
166For message queues with a global scope, the maximum message size is effectively
167limited to the longest message which the :term:`MPCI` is capable of
168transmitting.
169
170For control and maintenance of the message queue, RTEMS allocates a :term:`QCB`
171from the local QCB free pool and initializes it.
172
173The QCB for a global message queue is allocated on the local node.  Message
174queues should not be made global unless remote tasks must interact with the
175message queue.  This is to avoid the system overhead incurred by the creation
176of a global message queue.  When a global message queue is created, the message
177queue's name and identifier must be transmitted to every node in the system for
178insertion in the local copy of the global object table.
179
180.. rubric:: CONSTRAINTS:
181
182The following constraints apply to this directive:
183
184* The directive may be called from within device driver initialization context.
185
186* The directive may be called from within task context.
187
188* The directive may obtain and release the object allocator mutex.  This may
189  cause the calling task to be preempted.
190
191* When the directive operates on a global object, the directive sends a message
192  to remote nodes.  This may preempt the calling task.
193
194* The number of message queues available to the application is configured
195  through the :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` application configuration
196  option.
197
198* Where the object class corresponding to the directive is configured to use
199  unlimited objects, the directive may allocate memory from the RTEMS
200  Workspace.
201
202* The number of global objects available to the application is configured
203  through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application
204  configuration option.
205
206.. Generated from spec:/rtems/message/if/construct
207
208.. raw:: latex
209
210    \clearpage
211
212.. index:: rtems_message_queue_construct()
213
214.. _InterfaceRtemsMessageQueueConstruct:
215
216rtems_message_queue_construct()
217-------------------------------
218
219Constructs a message queue from the specified the message queue configuration.
220
221.. rubric:: CALLING SEQUENCE:
222
223.. code-block:: c
224
225    rtems_status_code rtems_message_queue_construct(
226      const rtems_message_queue_config *config,
227      rtems_id                         *id
228    );
229
230.. rubric:: PARAMETERS:
231
232``config``
233    This parameter is the message queue configuration.
234
235``id``
236    This parameter is the pointer to an :c:type:`rtems_id` object.  When the
237    directive call is successful, the identifier of the constructed message
238    queue will be stored in this object.
239
240.. rubric:: RETURN VALUES:
241
242:c:macro:`RTEMS_SUCCESSFUL`
243    The requested operation was successful.
244
245:c:macro:`RTEMS_INVALID_ADDRESS`
246    The ``config`` parameter was `NULL
247    <https://en.cppreference.com/w/c/types/NULL>`_.
248
249:c:macro:`RTEMS_INVALID_NAME`
250    The message queue name in the configuration was invalid.
251
252:c:macro:`RTEMS_INVALID_ADDRESS`
253    The ``id`` parameter was `NULL
254    <https://en.cppreference.com/w/c/types/NULL>`_.
255
256:c:macro:`RTEMS_INVALID_NUMBER`
257    The maximum number of pending messages in the configuration was zero.
258
259:c:macro:`RTEMS_INVALID_SIZE`
260    The maximum message size in the configuration was zero.
261
262:c:macro:`RTEMS_TOO_MANY`
263    There was no inactive message queue object available to construct a message
264    queue.
265
266:c:macro:`RTEMS_TOO_MANY`
267    In multiprocessing configurations, there was no inactive global object
268    available to construct a global message queue.
269
270:c:macro:`RTEMS_INVALID_SIZE`
271    The maximum message size in the configuration was too big and resulted in
272    integer overflows in calculations carried out to determine the size of the
273    message buffer area.
274
275:c:macro:`RTEMS_INVALID_NUMBER`
276    The maximum number of pending messages in the configuration was too big and
277    resulted in integer overflows in calculations carried out to determine the
278    size of the message buffer area.
279
280:c:macro:`RTEMS_UNSATISFIED`
281    The message queue storage area begin pointer in the configuration was `NULL
282    <https://en.cppreference.com/w/c/types/NULL>`_.
283
284:c:macro:`RTEMS_UNSATISFIED`
285    The message queue storage area size in the configuration was not equal to
286    the size calculated from the maximum number of pending messages and the
287    maximum message size.
288
289.. rubric:: NOTES:
290
291In contrast to message queues created by
292:ref:`InterfaceRtemsMessageQueueCreate`, the message queues constructed by this
293directive use a user-provided message buffer storage area.
294
295This directive is intended for applications which do not want to use the RTEMS
296Workspace and instead statically allocate all operating system resources.  An
297application based solely on static allocation can avoid any runtime memory
298allocators.  This can simplify the application architecture as well as any
299analysis that may be required.
300
301The value for :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY` should not include memory
302for message queues constructed by :ref:`InterfaceRtemsMessageQueueConstruct`.
303
304.. rubric:: CONSTRAINTS:
305
306The following constraints apply to this directive:
307
308* The directive may be called from within device driver initialization context.
309
310* The directive may be called from within task context.
311
312* The directive may obtain and release the object allocator mutex.  This may
313  cause the calling task to be preempted.
314
315* When the directive operates on a global object, the directive sends a message
316  to remote nodes.  This may preempt the calling task.
317
318* The number of message queues available to the application is configured
319  through the :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` application configuration
320  option.
321
322* Where the object class corresponding to the directive is configured to use
323  unlimited objects, the directive may allocate memory from the RTEMS
324  Workspace.
325
326* The number of global objects available to the application is configured
327  through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application
328  configuration option.
329
330.. Generated from spec:/rtems/message/if/ident
331
332.. raw:: latex
333
334    \clearpage
335
336.. index:: rtems_message_queue_ident()
337
338.. _InterfaceRtemsMessageQueueIdent:
339
340rtems_message_queue_ident()
341---------------------------
342
343Identifies a message queue by the object name.
344
345.. rubric:: CALLING SEQUENCE:
346
347.. code-block:: c
348
349    rtems_status_code rtems_message_queue_ident(
350      rtems_name name,
351      uint32_t   node,
352      rtems_id  *id
353    );
354
355.. rubric:: PARAMETERS:
356
357``name``
358    This parameter is the object name to look up.
359
360``node``
361    This parameter is the node or node set to search for a matching object.
362
363``id``
364    This parameter is the pointer to an :c:type:`rtems_id` object.  When the
365    directive call is successful, the object identifier of an object with the
366    specified name will be stored in this object.
367
368.. rubric:: DESCRIPTION:
369
370This directive obtains a message queue identifier associated with the message
371queue name specified in ``name``.
372
373The node to search is specified in ``node``.  It shall be
374
375* a valid node number,
376
377* the constant :c:macro:`RTEMS_SEARCH_ALL_NODES` to search in all nodes,
378
379* the constant :c:macro:`RTEMS_SEARCH_LOCAL_NODE` to search in the local node
380  only, or
381
382* the constant :c:macro:`RTEMS_SEARCH_OTHER_NODES` to search in all nodes
383  except the local node.
384
385.. rubric:: RETURN VALUES:
386
387:c:macro:`RTEMS_SUCCESSFUL`
388    The requested operation was successful.
389
390:c:macro:`RTEMS_INVALID_ADDRESS`
391    The ``id`` parameter was `NULL
392    <https://en.cppreference.com/w/c/types/NULL>`_.
393
394:c:macro:`RTEMS_INVALID_NAME`
395    The ``name`` parameter was 0.
396
397:c:macro:`RTEMS_INVALID_NAME`
398    There was no object with the specified name on the specified nodes.
399
400:c:macro:`RTEMS_INVALID_NODE`
401    In multiprocessing configurations, the specified node was invalid.
402
403.. rubric:: NOTES:
404
405If the message queue name is not unique, then the message queue identifier will
406match the first message queue with that name in the search order. However, this
407message queue identifier is not guaranteed to correspond to the desired message
408queue.
409
410The objects are searched from lowest to the highest index.  If ``node`` is
411:c:macro:`RTEMS_SEARCH_ALL_NODES`, all nodes are searched with the local node
412being searched first.  All other nodes are searched from lowest to the highest
413node number.
414
415If node is a valid node number which does not represent the local node, then
416only the message queues exported by the designated node are searched.
417
418This directive does not generate activity on remote nodes.  It accesses only
419the local copy of the global object table.
420
421The message queue identifier is used with other message related directives to
422access the message queue.
423
424.. rubric:: CONSTRAINTS:
425
426The following constraints apply to this directive:
427
428* The directive may be called from within any runtime context.
429
430* The directive will not cause the calling task to be preempted.
431
432.. Generated from spec:/rtems/message/if/delete
433
434.. raw:: latex
435
436    \clearpage
437
438.. index:: rtems_message_queue_delete()
439.. index:: delete a message queue
440
441.. _InterfaceRtemsMessageQueueDelete:
442
443rtems_message_queue_delete()
444----------------------------
445
446Deletes the message queue.
447
448.. rubric:: CALLING SEQUENCE:
449
450.. code-block:: c
451
452    rtems_status_code rtems_message_queue_delete( rtems_id id );
453
454.. rubric:: PARAMETERS:
455
456``id``
457    This parameter is the message queue identifier.
458
459.. rubric:: DESCRIPTION:
460
461This directive deletes the message queue specified by ``id``. As a result of
462this directive, all tasks blocked waiting to receive a message from this queue
463will be readied and returned a status code which indicates that the message
464queue was deleted.
465
466.. rubric:: RETURN VALUES:
467
468:c:macro:`RTEMS_SUCCESSFUL`
469    The requested operation was successful.
470
471:c:macro:`RTEMS_INVALID_ID`
472    There was no message queue associated with the identifier specified by
473    ``id``.
474
475:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT`
476    The message queue resided on a remote node.
477
478.. rubric:: NOTES:
479
480When the message queue is deleted, any messages in the queue are returned to
481the free message buffer pool.  Any information stored in those messages is
482lost.  The message buffers allocated for the message queue are reclaimed.
483
484The :term:`QCB` for the deleted message queue is reclaimed by RTEMS.
485
486When a global message queue is deleted, the message queue identifier must be
487transmitted to every node in the system for deletion from the local copy of the
488global object table.
489
490The message queue must reside on the local node, even if the message queue was
491created with the :c:macro:`RTEMS_GLOBAL` attribute.
492
493Proxies, used to represent remote tasks, are reclaimed when the message queue
494is deleted.
495
496.. rubric:: CONSTRAINTS:
497
498The following constraints apply to this directive:
499
500* The directive may be called from within device driver initialization context.
501
502* The directive may be called from within task context.
503
504* The directive may obtain and release the object allocator mutex.  This may
505  cause the calling task to be preempted.
506
507* When the directive operates on a global object, the directive sends a message
508  to remote nodes.  This may preempt the calling task.
509
510* The calling task does not have to be the task that created the object.  Any
511  local task that knows the object identifier can delete the object.
512
513* Where the object class corresponding to the directive is configured to use
514  unlimited objects, the directive may free memory to the RTEMS Workspace.
515
516.. Generated from spec:/rtems/message/if/send
517
518.. raw:: latex
519
520    \clearpage
521
522.. index:: rtems_message_queue_send()
523.. index:: send message to a queue
524
525.. _InterfaceRtemsMessageQueueSend:
526
527rtems_message_queue_send()
528--------------------------
529
530Puts the message at the rear of the queue.
531
532.. rubric:: CALLING SEQUENCE:
533
534.. code-block:: c
535
536    rtems_status_code rtems_message_queue_send(
537      rtems_id    id,
538      const void *buffer,
539      size_t      size
540    );
541
542.. rubric:: PARAMETERS:
543
544``id``
545    This parameter is the queue identifier.
546
547``buffer``
548    This parameter is the begin address of the message buffer to send.
549
550``size``
551    This parameter is the size in bytes of the message buffer to send.
552
553.. rubric:: DESCRIPTION:
554
555This directive sends the message ``buffer`` of ``size`` bytes in length to the
556queue specified by ``id``.  If a task is waiting at the queue, then the message
557is copied to the waiting task's buffer and the task is unblocked. If no tasks
558are waiting at the queue, then the message is copied to a message buffer which
559is obtained from this message queue's message buffer pool.  The message buffer
560is then placed at the rear of the queue.
561
562.. rubric:: RETURN VALUES:
563
564:c:macro:`RTEMS_SUCCESSFUL`
565    The requested operation was successful.
566
567:c:macro:`RTEMS_INVALID_ID`
568    There was no queue associated with the identifier specified by ``id``.
569
570:c:macro:`RTEMS_INVALID_ADDRESS`
571    The ``buffer`` parameter was `NULL
572    <https://en.cppreference.com/w/c/types/NULL>`_.
573
574:c:macro:`RTEMS_INVALID_SIZE`
575    The size of the message exceeded the maximum message size of the queue as
576    defined by :ref:`InterfaceRtemsMessageQueueCreate` or
577    :ref:`InterfaceRtemsMessageQueueConstruct`.
578
579:c:macro:`RTEMS_TOO_MANY`
580    The maximum number of pending messages supported by the queue as defined by
581    :ref:`InterfaceRtemsMessageQueueCreate` or
582    :ref:`InterfaceRtemsMessageQueueConstruct` has been reached.
583
584.. rubric:: CONSTRAINTS:
585
586The following constraints apply to this directive:
587
588* The directive may be called from within task context.
589
590* The directive may be called from within interrupt context.
591
592* The directive may unblock a task.  This may cause the calling task to be
593  preempted.
594
595* When the directive operates on a remote object, the directive sends a message
596  to the remote node and waits for a reply.  This will preempt the calling
597  task.
598
599.. Generated from spec:/rtems/message/if/urgent
600
601.. raw:: latex
602
603    \clearpage
604
605.. index:: rtems_message_queue_urgent()
606.. index:: put message at front of queue
607
608.. _InterfaceRtemsMessageQueueUrgent:
609
610rtems_message_queue_urgent()
611----------------------------
612
613Puts the message at the front of the queue.
614
615.. rubric:: CALLING SEQUENCE:
616
617.. code-block:: c
618
619    rtems_status_code rtems_message_queue_urgent(
620      rtems_id    id,
621      const void *buffer,
622      size_t      size
623    );
624
625.. rubric:: PARAMETERS:
626
627``id``
628    This parameter is the queue identifier.
629
630``buffer``
631    This parameter is the begin address of the message buffer to send urgently.
632
633``size``
634    This parameter is the size in bytes of the message buffer to send urgently.
635
636.. rubric:: DESCRIPTION:
637
638This directive sends the message ``buffer`` of ``size`` bytes in length to the
639queue specified by ``id``.  If a task is waiting at the queue, then the message
640is copied to the waiting task's buffer and the task is unblocked. If no tasks
641are waiting at the queue, then the message is copied to a message buffer which
642is obtained from this message queue's message buffer pool.  The message buffer
643is then placed at the front of the queue.
644
645.. rubric:: RETURN VALUES:
646
647:c:macro:`RTEMS_SUCCESSFUL`
648    The requested operation was successful.
649
650:c:macro:`RTEMS_INVALID_ID`
651    There was no queue associated with the identifier specified by ``id``.
652
653:c:macro:`RTEMS_INVALID_ADDRESS`
654    The ``buffer`` parameter was `NULL
655    <https://en.cppreference.com/w/c/types/NULL>`_.
656
657:c:macro:`RTEMS_INVALID_SIZE`
658    The size of the message exceeded the maximum message size of the queue as
659    defined by :ref:`InterfaceRtemsMessageQueueCreate` or
660    :ref:`InterfaceRtemsMessageQueueConstruct`.
661
662:c:macro:`RTEMS_TOO_MANY`
663    The maximum number of pending messages supported by the queue as defined by
664    :ref:`InterfaceRtemsMessageQueueCreate` or
665    :ref:`InterfaceRtemsMessageQueueConstruct` has been reached.
666
667.. rubric:: CONSTRAINTS:
668
669The following constraints apply to this directive:
670
671* The directive may be called from within task context.
672
673* The directive may be called from within interrupt context.
674
675* The directive may unblock a task.  This may cause the calling task to be
676  preempted.
677
678* When the directive operates on a remote object, the directive sends a message
679  to the remote node and waits for a reply.  This will preempt the calling
680  task.
681
682.. Generated from spec:/rtems/message/if/broadcast
683
684.. raw:: latex
685
686    \clearpage
687
688.. index:: rtems_message_queue_broadcast()
689.. index:: broadcast message to a queue
690
691.. _InterfaceRtemsMessageQueueBroadcast:
692
693rtems_message_queue_broadcast()
694-------------------------------
695
696Broadcasts the messages to the tasks waiting at the queue.
697
698.. rubric:: CALLING SEQUENCE:
699
700.. code-block:: c
701
702    rtems_status_code rtems_message_queue_broadcast(
703      rtems_id    id,
704      const void *buffer,
705      size_t      size,
706      uint32_t   *count
707    );
708
709.. rubric:: PARAMETERS:
710
711``id``
712    This parameter is the queue identifier.
713
714``buffer``
715    This parameter is the begin address of the message buffer to broadcast.
716
717``size``
718    This parameter is the size in bytes of the message buffer to broadcast.
719
720``count``
721    This parameter is the pointer to an `uint32_t
722    <https://en.cppreference.com/w/c/types/integer>`_ object.  When the
723    directive call is successful, the number of unblocked tasks will be stored
724    in this object.
725
726.. rubric:: DESCRIPTION:
727
728This directive causes all tasks that are waiting at the queue specified by
729``id`` to be unblocked and sent the message contained in ``buffer``.  Before a
730task is unblocked, the message ``buffer`` of ``size`` bytes in length is copied
731to that task's message buffer.  The number of tasks that were unblocked is
732returned in ``count``.
733
734.. rubric:: RETURN VALUES:
735
736:c:macro:`RTEMS_SUCCESSFUL`
737    The requested operation was successful.
738
739:c:macro:`RTEMS_INVALID_ID`
740    There was no queue associated with the identifier specified by ``id``.
741
742:c:macro:`RTEMS_INVALID_ADDRESS`
743    The ``buffer`` parameter was `NULL
744    <https://en.cppreference.com/w/c/types/NULL>`_.
745
746:c:macro:`RTEMS_INVALID_ADDRESS`
747    The ``count`` parameter was `NULL
748    <https://en.cppreference.com/w/c/types/NULL>`_.
749
750:c:macro:`RTEMS_INVALID_SIZE`
751    The size of the message exceeded the maximum message size of the queue as
752    defined by :ref:`InterfaceRtemsMessageQueueCreate` or
753    :ref:`InterfaceRtemsMessageQueueConstruct`.
754
755.. rubric:: NOTES:
756
757The execution time of this directive is directly related to the number of tasks
758waiting on the message queue, although it is more efficient than the equivalent
759number of invocations of :ref:`InterfaceRtemsMessageQueueSend`.
760
761.. rubric:: CONSTRAINTS:
762
763The following constraints apply to this directive:
764
765* The directive may be called from within task context.
766
767* The directive may be called from within interrupt context.
768
769* The directive may unblock a task.  This may cause the calling task to be
770  preempted.
771
772* When the directive operates on a remote object, the directive sends a message
773  to the remote node and waits for a reply.  This will preempt the calling
774  task.
775
776.. Generated from spec:/rtems/message/if/receive
777
778.. raw:: latex
779
780    \clearpage
781
782.. index:: rtems_message_queue_receive()
783.. index:: receive message from a queue
784
785.. _InterfaceRtemsMessageQueueReceive:
786
787rtems_message_queue_receive()
788-----------------------------
789
790Receives a message from the queue.
791
792.. rubric:: CALLING SEQUENCE:
793
794.. code-block:: c
795
796    rtems_status_code rtems_message_queue_receive(
797      rtems_id       id,
798      void          *buffer,
799      size_t        *size,
800      rtems_option   option_set,
801      rtems_interval timeout
802    );
803
804.. rubric:: PARAMETERS:
805
806``id``
807    This parameter is the queue identifier.
808
809``buffer``
810    This parameter is the begin address of the buffer to receive the message.
811    The buffer shall be large enough to receive a message of the maximum length
812    of the queue as defined by :ref:`InterfaceRtemsMessageQueueCreate` or
813    :ref:`InterfaceRtemsMessageQueueConstruct`.  The ``size`` parameter cannot
814    be used to specify the size of the buffer.
815
816``size``
817    This parameter is the pointer to a `size_t
818    <https://en.cppreference.com/w/c/types/size_t>`_ object.  When the
819    directive call is successful, the size in bytes of the received messages
820    will be stored in this object.  This parameter cannot be used to specify
821    the size of the buffer.
822
823``option_set``
824    This parameter is the option set.
825
826``timeout``
827    This parameter is the timeout in :term:`clock ticks <clock tick>` if the
828    :c:macro:`RTEMS_WAIT` option is set.  Use :c:macro:`RTEMS_NO_TIMEOUT` to
829    wait potentially forever.
830
831.. rubric:: DESCRIPTION:
832
833This directive receives a message from the queue specified by ``id``.
834
835The **option set** specified in ``option_set`` is built through a *bitwise or*
836of the option constants described below.  Not all combinations of options are
837allowed.  Some options are mutually exclusive.  If mutually exclusive options
838are combined, the behaviour is undefined.  Options not mentioned below are not
839evaluated by this directive and have no effect. Default options can be selected
840by using the :c:macro:`RTEMS_DEFAULT_OPTIONS` constant.
841
842The calling task can **wait** or **try to receive** a message from the queue
843according to the mutually exclusive :c:macro:`RTEMS_WAIT` and
844:c:macro:`RTEMS_NO_WAIT` options.
845
846* **Waiting to receive** a message from the queue is the default and can be
847  emphasized through the use of the :c:macro:`RTEMS_WAIT` option. The
848  ``timeout`` parameter defines how long the calling task is willing to wait.
849  Use :c:macro:`RTEMS_NO_TIMEOUT` to wait potentially forever, otherwise set a
850  timeout interval in clock ticks.
851
852* **Trying to receive** a message from the queue is selected by the
853  :c:macro:`RTEMS_NO_WAIT` option.  If this option is defined, then the
854  ``timeout`` parameter is ignored.  When a message from the queue cannot be
855  immediately received, then the :c:macro:`RTEMS_UNSATISFIED` status is
856  returned.
857
858With either :c:macro:`RTEMS_WAIT` or :c:macro:`RTEMS_NO_WAIT` if there is at
859least one message in the queue, then it is copied to the buffer, the size is
860set to return the length of the message in bytes, and this directive returns
861immediately with the :c:macro:`RTEMS_SUCCESSFUL` status code.  The buffer has
862to be big enough to receive a message of the maximum length with respect to
863this message queue.
864
865If the calling task chooses to return immediately and the queue is empty, then
866the directive returns immediately with the :c:macro:`RTEMS_UNSATISFIED` status
867code.  If the calling task chooses to wait at the message queue and the queue
868is empty, then the calling task is placed on the message wait queue and
869blocked.  If the queue was created with the :c:macro:`RTEMS_PRIORITY` option
870specified, then the calling task is inserted into the wait queue according to
871its priority.  But, if the queue was created with the :c:macro:`RTEMS_FIFO`
872option specified, then the calling task is placed at the rear of the wait
873queue.
874
875.. rubric:: RETURN VALUES:
876
877:c:macro:`RTEMS_SUCCESSFUL`
878    The requested operation was successful.
879
880:c:macro:`RTEMS_INVALID_ID`
881    There was no queue associated with the identifier specified by ``id``.
882
883:c:macro:`RTEMS_INVALID_ADDRESS`
884    The ``buffer`` parameter was `NULL
885    <https://en.cppreference.com/w/c/types/NULL>`_.
886
887:c:macro:`RTEMS_INVALID_ADDRESS`
888    The ``size`` parameter was `NULL
889    <https://en.cppreference.com/w/c/types/NULL>`_.
890
891:c:macro:`RTEMS_UNSATISFIED`
892    The queue was empty.
893
894:c:macro:`RTEMS_TIMEOUT`
895    The timeout happened while the calling task was waiting to receive a
896    message
897
898:c:macro:`RTEMS_OBJECT_WAS_DELETED`
899    The queue was deleted while the calling task was waiting to receive a
900    message.
901
902.. rubric:: CONSTRAINTS:
903
904The following constraints apply to this directive:
905
906* When a local queue is accessed and the :c:macro:`RTEMS_NO_WAIT` option is
907  set, the directive may be called from within interrupt context.
908
909* The directive may be called from within task context.
910
911* When the request cannot be immediately satisfied and the
912  :c:macro:`RTEMS_WAIT` option is set, the calling task blocks at some point
913  during the directive call.
914
915* The timeout functionality of the directive requires a :term:`clock tick`.
916
917* When the directive operates on a remote object, the directive sends a message
918  to the remote node and waits for a reply.  This will preempt the calling
919  task.
920
921.. Generated from spec:/rtems/message/if/get-number-pending
922
923.. raw:: latex
924
925    \clearpage
926
927.. index:: rtems_message_queue_get_number_pending()
928.. index:: get number of pending messages
929
930.. _InterfaceRtemsMessageQueueGetNumberPending:
931
932rtems_message_queue_get_number_pending()
933----------------------------------------
934
935Gets the number of messages pending on the queue.
936
937.. rubric:: CALLING SEQUENCE:
938
939.. code-block:: c
940
941    rtems_status_code rtems_message_queue_get_number_pending(
942      rtems_id  id,
943      uint32_t *count
944    );
945
946.. rubric:: PARAMETERS:
947
948``id``
949    This parameter is the queue identifier.
950
951``count``
952    This parameter is the pointer to an `uint32_t
953    <https://en.cppreference.com/w/c/types/integer>`_ object.  When the
954    directive call is successful, the number of pending messages will be stored
955    in this object.
956
957.. rubric:: DESCRIPTION:
958
959This directive returns the number of messages pending on the queue specified by
960``id`` in ``count``.  If no messages are present on the queue, count is set to
961zero.
962
963.. rubric:: RETURN VALUES:
964
965:c:macro:`RTEMS_SUCCESSFUL`
966    The requested operation was successful.
967
968:c:macro:`RTEMS_INVALID_ID`
969    There was no queue associated with the identifier specified by ``id``.
970
971:c:macro:`RTEMS_INVALID_ADDRESS`
972    The ``count`` parameter was `NULL
973    <https://en.cppreference.com/w/c/types/NULL>`_.
974
975.. rubric:: CONSTRAINTS:
976
977The following constraints apply to this directive:
978
979* The directive may be called from within task context.
980
981* The directive may be called from within interrupt context.
982
983* When the directive operates on a remote object, the directive sends a message
984  to the remote node and waits for a reply.  This will preempt the calling
985  task.
986
987.. Generated from spec:/rtems/message/if/flush
988
989.. raw:: latex
990
991    \clearpage
992
993.. index:: rtems_message_queue_flush()
994.. index:: flush messages on a queue
995
996.. _InterfaceRtemsMessageQueueFlush:
997
998rtems_message_queue_flush()
999---------------------------
1000
1001Flushes all messages on the queue.
1002
1003.. rubric:: CALLING SEQUENCE:
1004
1005.. code-block:: c
1006
1007    rtems_status_code rtems_message_queue_flush( rtems_id id, uint32_t *count );
1008
1009.. rubric:: PARAMETERS:
1010
1011``id``
1012    This parameter is the queue identifier.
1013
1014``count``
1015    This parameter is the pointer to an `uint32_t
1016    <https://en.cppreference.com/w/c/types/integer>`_ object.  When the
1017    directive call is successful, the number of pending messages removed from
1018    the queue will be stored in this object.
1019
1020.. rubric:: DESCRIPTION:
1021
1022This directive removes all pending messages from the queue specified by ``id``.
1023The number of messages removed is returned in ``count``.  If no messages are
1024present on the queue, count is set to zero.
1025
1026.. rubric:: RETURN VALUES:
1027
1028:c:macro:`RTEMS_SUCCESSFUL`
1029    The requested operation was successful.
1030
1031:c:macro:`RTEMS_INVALID_ID`
1032    There was no queue associated with the identifier specified by ``id``.
1033
1034:c:macro:`RTEMS_INVALID_ADDRESS`
1035    The ``count`` parameter was `NULL
1036    <https://en.cppreference.com/w/c/types/NULL>`_.
1037
1038.. rubric:: NOTES:
1039
1040The directive does not flush tasks waiting to receive a message from the
1041:term:`wait queue` of the message queue.
1042
1043.. rubric:: CONSTRAINTS:
1044
1045The following constraints apply to this directive:
1046
1047* The directive may be called from within interrupt context.
1048
1049* The directive may be called from within device driver initialization context.
1050
1051* The directive may be called from within task context.
1052
1053* The directive will not cause the calling task to be preempted.
1054
1055.. Generated from spec:/rtems/message/if/buffer
1056
1057.. raw:: latex
1058
1059    \clearpage
1060
1061.. index:: RTEMS_MESSAGE_QUEUE_BUFFER()
1062
1063.. _InterfaceRTEMSMESSAGEQUEUEBUFFER:
1064
1065RTEMS_MESSAGE_QUEUE_BUFFER()
1066----------------------------
1067
1068Defines a structure which can be used as a message queue buffer for messages of
1069the specified maximum size.
1070
1071.. rubric:: CALLING SEQUENCE:
1072
1073.. code-block:: c
1074
1075    RTEMS_MESSAGE_QUEUE_BUFFER( size_t maximum_message_size );
1076
1077.. rubric:: PARAMETERS:
1078
1079``maximum_message_size``
1080    This parameter is the maximum message size in bytes.
1081
1082.. rubric:: NOTES:
1083
1084Use this macro to define the message buffer storage area for
1085:ref:`InterfaceRtemsMessageQueueConstruct`.
Note: See TracBrowser for help on using the repository browser.