source: rtems-docs/c-user/message_manager.rst @ 4da4a15

4.115
Last change on this file since 4da4a15 was 4da4a15, checked in by Chris Johns <chrisj@…>, on 11/09/16 at 00:42:10

c-user: Fix header levels. Minor fixes.

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