diff options
Diffstat (limited to 'c-user/message/directives.rst')
-rw-r--r-- | c-user/message/directives.rst | 64 |
1 files changed, 33 insertions, 31 deletions
diff --git a/c-user/message/directives.rst b/c-user/message/directives.rst index 11ff105..7039b2e 100644 --- a/c-user/message/directives.rst +++ b/c-user/message/directives.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -72,9 +72,9 @@ Creates a message queue. This parameter is the attribute set of the message queue. ``id`` - This parameter is the pointer to an object identifier variable. When the - directive call is successful, the identifier of the created message queue - will be stored in this variable. + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created message + queue will be stored in this object. .. rubric:: DESCRIPTION: @@ -230,12 +230,13 @@ Constructs a message queue from the specified the message queue configuration. .. rubric:: PARAMETERS: ``config`` - This parameter is the message queue configuration. + This parameter is the pointer to an :ref:`InterfaceRtemsMessageQueueConfig` + object. It configures the message queue. ``id`` - This parameter is the pointer to an object identifier variable. When the - directive call is successful, the identifier of the constructed message - queue will be stored in this variable. + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the constructed message + queue will be stored in this object. .. rubric:: RETURN VALUES: @@ -361,9 +362,9 @@ Identifies a message queue by the object name. This parameter is the node or node set to search for a matching object. ``id`` - This parameter is the pointer to an object identifier variable. When the - directive call is successful, the object identifier of an object with the - specified name will be stored in this variable. + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. .. rubric:: DESCRIPTION: @@ -719,15 +720,15 @@ Broadcasts the messages to the tasks waiting at the queue. ``count`` This parameter is the pointer to an `uint32_t - <https://en.cppreference.com/w/c/types/integer>`_ variable. When the + <https://en.cppreference.com/w/c/types/integer>`_ object. When the directive call is successful, the number of unblocked tasks will be stored - in this variable. + in this object. .. rubric:: DESCRIPTION: This directive causes all tasks that are waiting at the queue specified by ``id`` to be unblocked and sent the message contained in ``buffer``. Before a -task is unblocked, the message ``buffer`` of ``size`` byes in length is copied +task is unblocked, the message ``buffer`` of ``size`` bytes in length is copied to that task's message buffer. The number of tasks that were unblocked is returned in ``count``. @@ -815,9 +816,9 @@ Receives a message from the queue. ``size`` This parameter is the pointer to a `size_t - <https://en.cppreference.com/w/c/types/size_t>`_ variable. When the + <https://en.cppreference.com/w/c/types/size_t>`_ object. When the directive call is successful, the size in bytes of the received messages - will be stored in this variable. This parameter cannot be used to specify + will be stored in this object. This parameter cannot be used to specify the size of the buffer. ``option_set`` @@ -891,10 +892,6 @@ queue. :c:macro:`RTEMS_UNSATISFIED` The queue was empty. -:c:macro:`RTEMS_UNSATISFIED` - The queue was flushed while the calling task was waiting to receive a - message. - :c:macro:`RTEMS_TIMEOUT` The timeout happened while the calling task was waiting to receive a message @@ -954,9 +951,9 @@ Gets the number of messages pending on the queue. ``count`` This parameter is the pointer to an `uint32_t - <https://en.cppreference.com/w/c/types/integer>`_ variable. When the + <https://en.cppreference.com/w/c/types/integer>`_ object. When the directive call is successful, the number of pending messages will be stored - in this variable. + in this object. .. rubric:: DESCRIPTION: @@ -1017,9 +1014,9 @@ Flushes all messages on the queue. ``count`` This parameter is the pointer to an `uint32_t - <https://en.cppreference.com/w/c/types/integer>`_ variable. When the - directive call is successful, the number of unblocked tasks will be stored - in this variable. + <https://en.cppreference.com/w/c/types/integer>`_ object. When the + directive call is successful, the number of pending messages removed from + the queue will be stored in this object. .. rubric:: DESCRIPTION: @@ -1039,17 +1036,22 @@ present on the queue, count is set to zero. The ``count`` parameter was `NULL <https://en.cppreference.com/w/c/types/NULL>`_. +.. rubric:: NOTES: + +The directive does not flush tasks waiting to receive a message from the +:term:`wait queue` of the message queue. + .. rubric:: CONSTRAINTS: The following constraints apply to this directive: -* The directive may be called from within task context. - * The directive may be called from within interrupt context. -* When the directive operates on a remote object, the directive sends a message - to the remote node and waits for a reply. This will preempt the calling - task. +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. .. Generated from spec:/rtems/message/if/buffer @@ -1071,7 +1073,7 @@ the specified maximum size. .. code-block:: c - #define RTEMS_MESSAGE_QUEUE_BUFFER( maximum_message_size ) + RTEMS_MESSAGE_QUEUE_BUFFER( size_t maximum_message_size ); .. rubric:: PARAMETERS: |