diff options
Diffstat (limited to 'c-user/message_manager.rst')
| -rw-r--r-- | c-user/message_manager.rst | 879 |
1 files changed, 438 insertions, 441 deletions
diff --git a/c-user/message_manager.rst b/c-user/message_manager.rst index d622cef..5613da9 100644 --- a/c-user/message_manager.rst +++ b/c-user/message_manager.rst @@ -215,543 +215,540 @@ This section details the message manager's directives. A subsection is dedicated to each of this manager's directives and describes the calling sequence, related constants, usage, and status codes. +.. raw:: latex + + \clearpage + .. _rtems_message_queue_create: MESSAGE_QUEUE_CREATE - Create a queue ------------------------------------- .. index:: create a message queue - -**CALLING SEQUENCE:** - .. index:: rtems_message_queue_create -.. code-block:: c - - rtems_status_code rtems_message_queue_create( - rtems_name name, - uint32_t count, - size_t max_message_size, - rtems_attribute attribute_set, - rtems_id *id - ); - -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - queue created successfully - * - ``RTEMS_INVALID_NAME`` - - invalid queue name - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NUMBER`` - - invalid message count - * - ``RTEMS_INVALID_SIZE`` - - invalid message size - * - ``RTEMS_TOO_MANY`` - - too many queues created - * - ``RTEMS_UNSATISFIED`` - - unable to allocate message buffers - * - ``RTEMS_MP_NOT_CONFIGURED`` - - multiprocessing not configured - * - ``RTEMS_TOO_MANY`` - - too many global objects - -**DESCRIPTION:** - -This directive creates a message queue which resides on the local node with the -user-defined name specified in name. For control and maintenance of the queue, -RTEMS allocates and initializes a QCB. Memory is allocated from the RTEMS -Workspace for the specified count of messages, each of max_message_size bytes -in length. The RTEMS-assigned queue id, returned in id, is used to access the -message queue. - -Specifying ``RTEMS_PRIORITY`` in attribute_set causes tasks waiting for a -message to be serviced according to task priority. When ``RTEMS_FIFO`` is -specified, waiting tasks are serviced in First In-First Out order. - -**NOTES:** - -This directive will not cause the calling task to be preempted. - -The following message queue attribute constants are defined by RTEMS: - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_FIFO`` - - tasks wait by FIFO (default) - * - ``RTEMS_PRIORITY`` - - tasks wait by priority - * - ``RTEMS_LOCAL`` - - local message queue (default) - * - ``RTEMS_GLOBAL`` - - global message queue - -Message queues should not be made global unless remote tasks must interact with -the created message queue. This is to avoid the system overhead incurred by -the creation of a global message queue. When a global message queue is -created, the message queue's name and id must be transmitted to every node in -the system for insertion in the local copy of the global object table. - -For GLOBAL message queues, the maximum message size is effectively limited to -the longest message which the MPCI is capable of transmitting. - -The total number of global objects, including message queues, is limited by the -``maximum_global_objects`` field in the configuration table. +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_message_queue_create( + rtems_name name, + uint32_t count, + size_t max_message_size, + rtems_attribute attribute_set, + rtems_id *id + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - queue created successfully + * - ``RTEMS_INVALID_NAME`` + - invalid queue name + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_INVALID_NUMBER`` + - invalid message count + * - ``RTEMS_INVALID_SIZE`` + - invalid message size + * - ``RTEMS_TOO_MANY`` + - too many queues created + * - ``RTEMS_UNSATISFIED`` + - unable to allocate message buffers + * - ``RTEMS_MP_NOT_CONFIGURED`` + - multiprocessing not configured + * - ``RTEMS_TOO_MANY`` + - too many global objects + +DESCRIPTION: + This directive creates a message queue which resides on the local node with + the user-defined name specified in name. For control and maintenance of + the queue, RTEMS allocates and initializes a QCB. Memory is allocated from + the RTEMS Workspace for the specified count of messages, each of + max_message_size bytes in length. The RTEMS-assigned queue id, returned in + id, is used to access the message queue. + + Specifying ``RTEMS_PRIORITY`` in attribute_set causes tasks waiting for a + message to be serviced according to task priority. When ``RTEMS_FIFO`` is + specified, waiting tasks are serviced in First In-First Out order. + +NOTES: + This directive will not cause the calling task to be preempted. + + The following message queue attribute constants are defined by RTEMS: + + .. list-table:: + :class: rtems-table + + * - ``RTEMS_FIFO`` + - tasks wait by FIFO (default) + * - ``RTEMS_PRIORITY`` + - tasks wait by priority + * - ``RTEMS_LOCAL`` + - local message queue (default) + * - ``RTEMS_GLOBAL`` + - global message queue + + Message queues should not be made global unless remote tasks must interact + with the created message queue. This is to avoid the system overhead + incurred by the creation of a global message queue. When a global message + queue is created, the message queue's name and id must be transmitted to + every node in the system for insertion in the local copy of the global + object table. + + For GLOBAL message queues, the maximum message size is effectively limited + to the longest message which the MPCI is capable of transmitting. + + The total number of global objects, including message queues, is limited by + the ``maximum_global_objects`` field in the configuration table. + +.. raw:: latex + + \clearpage .. _rtems_message_queue_ident: MESSAGE_QUEUE_IDENT - Get ID of a queue --------------------------------------- .. index:: get ID of a message queue - -**CALLING SEQUENCE:** - .. index:: rtems_message_queue_ident -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_message_queue_ident( - rtems_name name, - uint32_t node, - rtems_id *id - ); + rtems_status_code rtems_message_queue_ident( + rtems_name name, + uint32_t node, + rtems_id *id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_SUCCESSFUL`` + - queue identified successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_INVALID_NAME`` + - queue name not found + * - ``RTEMS_INVALID_NODE`` + - invalid node id - * - ``RTEMS_SUCCESSFUL`` - - queue identified successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - queue name not found - * - ``RTEMS_INVALID_NODE`` - - invalid node id +DESCRIPTION: + This directive obtains the queue id associated with the queue name + specified in name. If the queue name is not unique, then the queue id will + match one of the queues with that name. However, this queue id is not + guaranteed to correspond to the desired queue. The queue id is used with + other message related directives to access the message queue. -**DESCRIPTION:** +NOTES: + This directive will not cause the running task to be preempted. -This directive obtains the queue id associated with the queue name specified in -name. If the queue name is not unique, then the queue id will match one of the -queues with that name. However, this queue id is not guaranteed to correspond -to the desired queue. The queue id is used with other message related -directives to access the message queue. + If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the + local node being searched first. All other nodes are searched with the + lowest numbered node searched first. -**NOTES:** + If node is a valid node number which does not represent the local node, + then only the message queues exported by the designated node are searched. -This directive will not cause the running task to be preempted. + This directive does not generate activity on remote nodes. It accesses + only the local copy of the global object table. -If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the local -node being searched first. All other nodes are searched with the lowest -numbered node searched first. +.. raw:: latex -If node is a valid node number which does not represent the local node, then -only the message queues exported by the designated node are searched. - -This directive does not generate activity on remote nodes. It accesses only -the local copy of the global object table. + \clearpage .. _rtems_message_queue_delete: MESSAGE_QUEUE_DELETE - Delete a queue ------------------------------------- .. index:: delete a message queue - -**CALLING SEQUENCE:** - .. index:: rtems_message_queue_delete -.. code-block:: c - - rtems_status_code rtems_message_queue_delete( - rtems_id id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_message_queue_delete( + rtems_id id + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - queue deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid queue id - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - cannot delete remote queue + * - ``RTEMS_SUCCESSFUL`` + - queue deleted successfully + * - ``RTEMS_INVALID_ID`` + - invalid queue id + * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + - cannot delete remote queue -**DESCRIPTION:** +DESCRIPTION: + This directive deletes the message queue specified by ``id``. As a result + of this directive, all tasks blocked waiting to receive a message from this + queue will be readied and returned a status code which indicates that the + message queue was deleted. If no tasks are waiting, but the queue contains + messages, then RTEMS returns these message buffers back to the system + message buffer pool. The QCB for this queue as well as the memory for the + message buffers is reclaimed by RTEMS. -This directive deletes the message queue specified by ``id``. As a result of -this directive, all tasks blocked waiting to receive a message from this queue -will be readied and returned a status code which indicates that the message -queue was deleted. If no tasks are waiting, but the queue contains messages, -then RTEMS returns these message buffers back to the system message buffer -pool. The QCB for this queue as well as the memory for the message buffers is -reclaimed by RTEMS. +NOTES: + The calling task will be preempted if its preemption mode is enabled and + one or more local tasks with a higher priority than the calling task are + waiting on the deleted queue. The calling task will NOT be preempted if + the tasks that are waiting are remote tasks. -**NOTES:** + The calling task does not have to be the task that created the queue, + although the task and queue must reside on the same node. -The calling task will be preempted if its preemption mode is enabled and one or -more local tasks with a higher priority than the calling task are waiting on -the deleted queue. The calling task will NOT be preempted if the tasks that -are waiting are remote tasks. + When the queue is deleted, any messages in the queue are returned to the + free message buffer pool. Any information stored in those messages is + lost. -The calling task does not have to be the task that created the queue, although -the task and queue must reside on the same node. + When a global message queue is deleted, the message queue id must be + transmitted to every node in the system for deletion from the local copy of + the global object table. -When the queue is deleted, any messages in the queue are returned to the free -message buffer pool. Any information stored in those messages is lost. + Proxies, used to represent remote tasks, are reclaimed when the message + queue is deleted. -When a global message queue is deleted, the message queue id must be -transmitted to every node in the system for deletion from the local copy of the -global object table. +.. raw:: latex -Proxies, used to represent remote tasks, are reclaimed when the message queue -is deleted. + \clearpage .. _rtems_message_queue_send: MESSAGE_QUEUE_SEND - Put message at rear of a queue --------------------------------------------------- .. index:: send message to a queue - -**CALLING SEQUENCE:** - .. index:: rtems_message_queue_send -.. code-block:: c - - rtems_status_code rtems_message_queue_send( - rtems_id id, - cons void *buffer, - size_t size - ); - -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - message sent successfully - * - ``RTEMS_INVALID_ID`` - - invalid queue id - * - ``RTEMS_INVALID_SIZE`` - - invalid message size - * - ``RTEMS_INVALID_ADDRESS`` - - ``buffer`` is NULL - * - ``RTEMS_UNSATISFIED`` - - out of message buffers - * - ``RTEMS_TOO_MANY`` - - queue's limit has been reached - -**DESCRIPTION:** - -This directive sends the message buffer of size bytes in length to the queue -specified by id. If a task is waiting at the queue, then the message is copied -to the waiting task's buffer and the task is unblocked. If no tasks are waiting -at the queue, then the message is copied to a message buffer which is obtained -from this message queue's message buffer pool. The message buffer is then -placed at the rear of the queue. - -**NOTES:** - -The calling task will be preempted if it has preemption enabled and a higher -priority task is unblocked as the result of this directive. - -Sending a message to a global message queue which does not reside on the local -node will generate a request to the remote node to post the message on the -specified message queue. - -If the task to be unblocked resides on a different node from the message queue, -then the message is forwarded to the appropriate node, the waiting task is -unblocked, and the proxy used to represent the task is reclaimed. +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_message_queue_send( + rtems_id id, + cons void *buffer, + size_t size + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - message sent successfully + * - ``RTEMS_INVALID_ID`` + - invalid queue id + * - ``RTEMS_INVALID_SIZE`` + - invalid message size + * - ``RTEMS_INVALID_ADDRESS`` + - ``buffer`` is NULL + * - ``RTEMS_UNSATISFIED`` + - out of message buffers + * - ``RTEMS_TOO_MANY`` + - queue's limit has been reached + +DESCRIPTION: + This directive sends the message buffer of size bytes in length to the + queue specified by id. If a task is waiting at the queue, then the message + is copied to the waiting task's buffer and the task is unblocked. If no + tasks are waiting at the queue, then the message is copied to a message + buffer which is obtained from this message queue's message buffer pool. + The message buffer is then placed at the rear of the queue. + +NOTES: + The calling task will be preempted if it has preemption enabled and a + higher priority task is unblocked as the result of this directive. + + Sending a message to a global message queue which does not reside on the + local node will generate a request to the remote node to post the message + on the specified message queue. + + If the task to be unblocked resides on a different node from the message + queue, then the message is forwarded to the appropriate node, the waiting + task is unblocked, and the proxy used to represent the task is reclaimed. + +.. raw:: latex + + \clearpage .. _rtems_message_queue_urgent: MESSAGE_QUEUE_URGENT - Put message at front of a queue ------------------------------------------------------ .. index:: put message at front of queue - -**CALLING SEQUENCE:** - .. index:: rtems_message_queue_urgent -.. code-block:: c - - rtems_status_code rtems_message_queue_urgent( - rtems_id id, - const void *buffer, - size_t size - ); - -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - message sent successfully - * - ``RTEMS_INVALID_ID`` - - invalid queue id - * - ``RTEMS_INVALID_SIZE`` - - invalid message size - * - ``RTEMS_INVALID_ADDRESS`` - - ``buffer`` is NULL - * - ``RTEMS_UNSATISFIED`` - - out of message buffers - * - ``RTEMS_TOO_MANY`` - - queue's limit has been reached - -**DESCRIPTION:** - -This directive sends the message buffer of size bytes in length to the queue -specified by id. If a task is waiting on the queue, then the message is copied -to the task's buffer and the task is unblocked. If no tasks are waiting on the -queue, then the message is copied to a message buffer which is obtained from -this message queue's message buffer pool. The message buffer is then placed at -the front of the queue. - -**NOTES:** - -The calling task will be preempted if it has preemption enabled and a higher -priority task is unblocked as the result of this directive. - -Sending a message to a global message queue which does not reside on the local -node will generate a request telling the remote node to post the message on the -specified message queue. - -If the task to be unblocked resides on a different node from the message queue, -then the message is forwarded to the appropriate node, the waiting task is -unblocked, and the proxy used to represent the task is reclaimed. +**CALLING SEQUENCE:** + .. code-block:: c + + rtems_status_code rtems_message_queue_urgent( + rtems_id id, + const void *buffer, + size_t size + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - message sent successfully + * - ``RTEMS_INVALID_ID`` + - invalid queue id + * - ``RTEMS_INVALID_SIZE`` + - invalid message size + * - ``RTEMS_INVALID_ADDRESS`` + - ``buffer`` is NULL + * - ``RTEMS_UNSATISFIED`` + - out of message buffers + * - ``RTEMS_TOO_MANY`` + - queue's limit has been reached + +DESCRIPTION: + This directive sends the message buffer of size bytes in length to the + queue specified by id. If a task is waiting on the queue, then the message + is copied to the task's buffer and the task is unblocked. If no tasks are + waiting on the queue, then the message is copied to a message buffer which + is obtained from this message queue's message buffer pool. The message + buffer is then placed at the front of the queue. + +NOTES: + The calling task will be preempted if it has preemption enabled and a + higher priority task is unblocked as the result of this directive. + + Sending a message to a global message queue which does not reside on the + local node will generate a request telling the remote node to post the + message on the specified message queue. + + If the task to be unblocked resides on a different node from the message + queue, then the message is forwarded to the appropriate node, the waiting + task is unblocked, and the proxy used to represent the task is reclaimed. + +.. raw:: latex + + \clearpage .. _rtems_message_queue_broadcast: MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue --------------------------------------------------------- .. index:: broadcast message to a queue - -**CALLING SEQUENCE:** - .. index:: rtems_message_queue_broadcast -.. code-block:: c - - rtems_status_code rtems_message_queue_broadcast( - rtems_id id, - const void *buffer, - size_t size, - uint32_t *count - ); - -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - message broadcasted successfully - * - ``RTEMS_INVALID_ID`` - - invalid queue id - * - ``RTEMS_INVALID_ADDRESS`` - - ``buffer`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``count`` is NULL - * - ``RTEMS_INVALID_SIZE`` - - invalid message size - -**DESCRIPTION:** - -This directive causes all tasks that are waiting at the queue specified by id -to be unblocked and sent the message contained in buffer. Before a task is -unblocked, the message buffer of size byes in length is copied to that task's -message buffer. The number of tasks that were unblocked is returned in count. - -**NOTES:** - -The calling task will be preempted if it has preemption enabled and a higher -priority task is unblocked as the result of this directive. - -The execution time of this directive is directly related to the number of tasks -waiting on the message queue, although it is more efficient than the equivalent -number of invocations of ``rtems_message_queue_send``. - -Broadcasting a message to a global message queue which does not reside on the -local node will generate a request telling the remote node to broadcast the -message to the specified message queue. - -When a task is unblocked which resides on a different node from the message -queue, a copy of the message is forwarded to the appropriate node, the waiting -task is unblocked, and the proxy used to represent the task is reclaimed. +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_message_queue_broadcast( + rtems_id id, + const void *buffer, + size_t size, + uint32_t *count + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - message broadcasted successfully + * - ``RTEMS_INVALID_ID`` + - invalid queue id + * - ``RTEMS_INVALID_ADDRESS`` + - ``buffer`` is NULL + * - ``RTEMS_INVALID_ADDRESS`` + - ``count`` is NULL + * - ``RTEMS_INVALID_SIZE`` + - invalid message size + +DESCRIPTION: + This directive causes all tasks that are waiting at the queue specified by + id to be unblocked and sent the message contained in buffer. Before a task + is unblocked, the message buffer of size byes in length is copied to that + task's message buffer. The number of tasks that were unblocked is returned + in count. + +NOTES: + The calling task will be preempted if it has preemption enabled and a + higher priority task is unblocked as the result of this directive. + + The execution time of this directive is directly related to the number of + tasks waiting on the message queue, although it is more efficient than the + equivalent number of invocations of ``rtems_message_queue_send``. + + Broadcasting a message to a global message queue which does not reside on + the local node will generate a request telling the remote node to broadcast + the message to the specified message queue. + + When a task is unblocked which resides on a different node from the message + queue, a copy of the message is forwarded to the appropriate node, the + waiting task is unblocked, and the proxy used to represent the task is + reclaimed. + +.. raw:: latex + + \clearpage .. _rtems_message_queue_receive: MESSAGE_QUEUE_RECEIVE - Receive message from a queue ---------------------------------------------------- .. index:: receive message from a queue - -**CALLING SEQUENCE:** - .. index:: rtems_message_queue_receive -.. code-block:: c - - rtems_status_code rtems_message_queue_receive( - rtems_id id, - void *buffer, - size_t *size, - rtems_option option_set, - rtems_interval timeout - ); - -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - message received successfully - * - ``RTEMS_INVALID_ID`` - - invalid queue id - * - ``RTEMS_INVALID_ADDRESS`` - - ``buffer`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``size`` is NULL - * - ``RTEMS_UNSATISFIED`` - - queue is empty - * - ``RTEMS_TIMEOUT`` - - timed out waiting for message - * - ``RTEMS_OBJECT_WAS_DELETED`` - - queue deleted while waiting - -**DESCRIPTION:** - -This directive receives a message from the message queue specified in id. The -``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` options of the options parameter allow the -calling task to specify whether to wait for a message to become available or -return immediately. For either option, if there is at least one message in the -queue, then it is copied to buffer, size is set to return the length of the -message in bytes, and this directive returns immediately with a successful -return code. The buffer has to be big enough to receive a message of the -maximum length with respect to this message queue. - -If the calling task chooses to return immediately and the queue is empty, then -a status code indicating this condition is returned. If the calling task -chooses to wait at the message queue and the queue is empty, then the calling -task is placed on the message wait queue and blocked. If the queue was created -with the ``RTEMS_PRIORITY`` option specified, then the calling task is inserted -into the wait queue according to its priority. But, if the queue was created -with the ``RTEMS_FIFO`` option specified, then the calling task is placed at -the rear of the wait queue. - -A task choosing to wait at the queue can optionally specify a timeout value in -the timeout parameter. The timeout parameter specifies the maximum interval to -wait before the calling task desires to be unblocked. If it is set to -``RTEMS_NO_TIMEOUT``, then the calling task will wait forever. - -**NOTES:** - -The following message receive option constants are defined by RTEMS: - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_WAIT`` - - task will wait for a message (default) - * - ``RTEMS_NO_WAIT`` - - task should not wait - -Receiving a message from a global message queue which does not reside on the -local node will generate a request to the remote node to obtain a message from -the specified message queue. If no message is available and ``RTEMS_WAIT`` was -specified, then the task must be blocked until a message is posted. A proxy is -allocated on the remote node to represent the task until the message is posted. - -A clock tick is required to support the timeout functionality of this -directive. +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_message_queue_receive( + rtems_id id, + void *buffer, + size_t *size, + rtems_option option_set, + rtems_interval timeout + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - message received successfully + * - ``RTEMS_INVALID_ID`` + - invalid queue id + * - ``RTEMS_INVALID_ADDRESS`` + - ``buffer`` is NULL + * - ``RTEMS_INVALID_ADDRESS`` + - ``size`` is NULL + * - ``RTEMS_UNSATISFIED`` + - queue is empty + * - ``RTEMS_TIMEOUT`` + - timed out waiting for message + * - ``RTEMS_OBJECT_WAS_DELETED`` + - queue deleted while waiting + +DESCRIPTION: + This directive receives a message from the message queue specified in id. + The ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` options of the options parameter + allow the calling task to specify whether to wait for a message to become + available or return immediately. For either option, if there is at least + one message in the queue, then it is copied to buffer, size is set to + return the length of the message in bytes, and this directive returns + immediately with a successful return code. The buffer has to be big enough + to receive a message of the maximum length with respect to this message + queue. + + If the calling task chooses to return immediately and the queue is empty, + then a status code indicating this condition is returned. If the calling + task chooses to wait at the message queue and the queue is empty, then the + calling task is placed on the message wait queue and blocked. If the queue + was created with the ``RTEMS_PRIORITY`` option specified, then the calling + task is inserted into the wait queue according to its priority. But, if + the queue was created with the ``RTEMS_FIFO`` option specified, then the + calling task is placed at the rear of the wait queue. + + A task choosing to wait at the queue can optionally specify a timeout value + in the timeout parameter. The timeout parameter specifies the maximum + interval to wait before the calling task desires to be unblocked. If it is + set to ``RTEMS_NO_TIMEOUT``, then the calling task will wait forever. + +NOTES: + The following message receive option constants are defined by RTEMS: + + .. list-table:: + :class: rtems-table + + * - ``RTEMS_WAIT`` + - task will wait for a message (default) + * - ``RTEMS_NO_WAIT`` + - task should not wait + + Receiving a message from a global message queue which does not reside on + the local node will generate a request to the remote node to obtain a + message from the specified message queue. If no message is available and + ``RTEMS_WAIT`` was specified, then the task must be blocked until a message + is posted. A proxy is allocated on the remote node to represent the task + until the message is posted. + + A clock tick is required to support the timeout functionality of this + directive. + +.. raw:: latex + + \clearpage .. _rtems_message_queue_get_number_pending: MESSAGE_QUEUE_GET_NUMBER_PENDING - Get number of messages pending on a queue ---------------------------------------------------------------------------- .. index:: get number of pending messages - -**CALLING SEQUENCE:** - .. index:: rtems_message_queue_get_number_pending -.. code-block:: c - - rtems_status_code rtems_message_queue_get_number_pending( - rtems_id id, - uint32_t *count - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_message_queue_get_number_pending( + rtems_id id, + uint32_t *count + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - number of messages pending returned successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``count`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid queue id + * - ``RTEMS_SUCCESSFUL`` + - number of messages pending returned successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``count`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid queue id -**DESCRIPTION:** +DESCRIPTION: + This directive returns the number of messages pending on this message queue + in count. If no messages are present on the queue, count is set to zero. -This directive returns the number of messages pending on this message queue in -count. If no messages are present on the queue, count is set to zero. +NOTES: + Getting the number of pending messages on a global message queue which does + not reside on the local node will generate a request to the remote node to + actually obtain the pending message count for the specified message queue. -**NOTES:** +.. raw:: latex -Getting the number of pending messages on a global message queue which does not -reside on the local node will generate a request to the remote node to actually -obtain the pending message count for the specified message queue. + \clearpage .. _rtems_message_queue_flush: MESSAGE_QUEUE_FLUSH - Flush all messages on a queue --------------------------------------------------- .. index:: flush messages on a queue - -**CALLING SEQUENCE:** - .. index:: rtems_message_queue_flush -.. code-block:: c - - rtems_status_code rtems_message_queue_flush( - rtems_id id, - uint32_t *count - ); - -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - message queue flushed successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``count`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid queue id - -**DESCRIPTION:** - -This directive removes all pending messages from the specified queue id. The -number of messages removed is returned in count. If no messages are present on -the queue, count is set to zero. - -**NOTES:** - -Flushing all messages on a global message queue which does not reside on the -local node will generate a request to the remote node to actually flush the -specified message queue. +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_message_queue_flush( + rtems_id id, + uint32_t *count + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - message queue flushed successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``count`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid queue id + +DESCRIPTION: + This directive removes all pending messages from the specified queue id. + The number of messages removed is returned in count. If no messages are + present on the queue, count is set to zero. + +NOTES: + Flushing all messages on a global message queue which does not reside on + the local node will generate a request to the remote node to actually flush + the specified message queue. |