source: rtems-docs/c-user/message_manager.rst @ 464d541

5
Last change on this file since 464d541 was 3384994, checked in by Chris Johns <chrisj@…>, on 11/13/17 at 02:25:18

Clean up sphinx warnings.

  • Fix minor formatting issues.
  • Fix reference the gloassary TLS using ':term:'.
  • Make sure nothing is between an anchor and the heading where ':ref:' references the anchor. This meant moving all the recently added '.. index::' entries.

Update #3232.
Update #3229.

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