diff options
Diffstat (limited to 'doc/user/msg.t')
-rw-r--r-- | doc/user/msg.t | 834 |
1 files changed, 834 insertions, 0 deletions
diff --git a/doc/user/msg.t b/doc/user/msg.t new file mode 100644 index 0000000000..03d2150e3c --- /dev/null +++ b/doc/user/msg.t @@ -0,0 +1,834 @@ +@c +@c COPYRIGHT (c) 1988-2002. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + +@chapter Message Manager + +@cindex messages +@cindex message queues + +@section Introduction + +The message manager provides communication and +synchronization capabilities using RTEMS message queues. The +directives provided by the message manager are: + +@itemize @bullet +@item @code{@value{DIRPREFIX}message_queue_create} - Create a queue +@item @code{@value{DIRPREFIX}message_queue_ident} - Get ID of a queue +@item @code{@value{DIRPREFIX}message_queue_delete} - Delete a queue +@item @code{@value{DIRPREFIX}message_queue_send} - Put message at rear of a queue +@item @code{@value{DIRPREFIX}message_queue_urgent} - Put message at front of a queue +@item @code{@value{DIRPREFIX}message_queue_broadcast} - Broadcast N messages to a queue +@item @code{@value{DIRPREFIX}message_queue_receive} - Receive message from a queue +@item @code{@value{DIRPREFIX}message_queue_get_number_pending} - Get number of messages pending on a queue +@item @code{@value{DIRPREFIX}message_queue_flush} - Flush all messages on a queue +@end itemize + +@section Background + +@subsection Messages + +A message is a variable length buffer where +information can be stored to support communication. The length +of the message and the information stored in that message are +user-defined and can be actual data, pointer(s), or empty. + +@subsection Message Queues + +A message queue permits the passing of messages among +tasks and ISRs. Message queues can contain a variable number of +messages. Normally messages are sent to and received from the +queue in FIFO order using the @code{@value{DIRPREFIX}message_queue_send} +directive. However, the @code{@value{DIRPREFIX}message_queue_urgent} +directive can be used to place +messages at the head of a queue in LIFO order. + +Synchronization can be accomplished when a task can +wait for a message to arrive at a queue. Also, a task may poll +a queue for the arrival of a message. + +The maximum length message which can be sent is set +on a per message queue basis. + +@subsection Building a Message Queue Attribute Set + +@cindex message queue attributes + +In general, an attribute set is built by a bitwise OR +of the desired attribute components. The set of valid message +queue attributes is provided in the following table: + +@itemize @bullet +@item @code{@value{RPREFIX}FIFO} - tasks wait by FIFO (default) +@item @code{@value{RPREFIX}PRIORITY} - tasks wait by priority +@item @code{@value{RPREFIX}LOCAL} - local message queue (default) +@item @code{@value{RPREFIX}GLOBAL} - global message queue +@end itemize + + +An attribute listed as a default is not required to +appear in the attribute list, although it is a good programming +practice to specify default attributes. If all defaults are +desired, the attribute @code{@value{RPREFIX}DEFAULT_ATTRIBUTES} +should be specified on this call. + +This example demonstrates the attribute_set parameter +needed to create a local message queue with the task priority +waiting queue discipline. The attribute_set parameter to the +@code{@value{DIRPREFIX}message_queue_create} directive could be either +@code{@value{RPREFIX}PRIORITY} or +@code{@value{RPREFIX}LOCAL @value{OR} @value{RPREFIX}PRIORITY}. +The attribute_set parameter can be set to @code{@value{RPREFIX}PRIORITY} +because @code{@value{RPREFIX}LOCAL} is the default for all created +message queues. If a similar message queue were to be known globally, then the +attribute_set parameter would be +@code{@value{RPREFIX}GLOBAL @value{OR} @value{RPREFIX}PRIORITY}. + +@subsection Building a MESSAGE_QUEUE_RECEIVE Option Set + +In general, an option is built by a bitwise OR of the +desired option components. The set of valid options for the +@code{@value{DIRPREFIX}message_queue_receive} directive are +listed in the following table: + +@itemize @bullet +@item @code{@value{RPREFIX}WAIT} - task will wait for a message (default) +@item @code{@value{RPREFIX}NO_WAIT} - task should not wait +@end itemize + +An option listed as a default is not required to +appear in the option OR list, although it is a good programming +practice to specify default options. If all defaults are +desired, the option @code{@value{RPREFIX}DEFAULT_OPTIONS} should +be specified on this call. + +This example demonstrates the option parameter needed +to poll for a message to arrive. The option parameter passed to +the @code{@value{DIRPREFIX}message_queue_receive} directive should +be @code{@value{RPREFIX}NO_WAIT}. + +@section Operations + +@subsection Creating a Message Queue + +The @code{@value{DIRPREFIX}message_queue_create} directive creates a message +queue with the user-defined name. The user specifies the +maximum message size and maximum number of messages which can be +placed in the message queue at one time. The user may select +FIFO or task priority as the method for placing waiting tasks in +the task wait queue. RTEMS allocates a Queue Control Block +(QCB) from the QCB free list to maintain the newly created queue +as well as memory for the message buffer pool associated with +this message queue. RTEMS also generates a message queue ID +which is returned to the calling task. + +For GLOBAL message queues, the maximum message size +is effectively limited to the longest message which the MPCI is +capable of transmitting. + +@subsection Obtaining Message Queue IDs + +When a message queue is created, RTEMS generates a +unique message queue ID. The message queue ID may be obtained +by either of two methods. First, as the result of an invocation +of the @code{@value{DIRPREFIX}message_queue_create} directive, the +queue ID is stored in a user provided location. Second, the queue +ID may be obtained later using the @code{@value{DIRPREFIX}message_queue_ident} +directive. The queue ID is used by other message manager +directives to access this message queue. + +@subsection Receiving a Message + +The @code{@value{DIRPREFIX}message_queue_receive} directive attempts to +retrieve a message from the specified message queue. If at +least one message is in the queue, then the message is removed +from the queue, copied to the caller's message buffer, and +returned immediately along with the length of the message. When +messages are unavailable, one of the following situations +applies: + +@itemize @bullet +@item By default, the calling task will wait forever for the +message to arrive. + +@item Specifying the @code{@value{RPREFIX}NO_WAIT} option forces an immediate return +with an error status code. + +@item Specifying a timeout limits the period the task will +wait before returning with an error status. +@end itemize + +If the task waits for a message, then it is placed in +the message queue's task wait queue in either FIFO or task +priority order. All tasks waiting on a message queue are +returned an error code when the message queue is deleted. + +@subsection Sending a Message + +Messages can be sent to a queue with the +@code{@value{DIRPREFIX}message_queue_send} and +@code{@value{DIRPREFIX}message_queue_urgent} directives. These +directives work identically when tasks are waiting to receive a +message. A task is removed from the task waiting queue, +unblocked, and the message is copied to a waiting task's +message buffer. + +When no tasks are waiting at the queue, +@code{@value{DIRPREFIX}message_queue_send} places the +message at the rear of the message queue, while +@code{@value{DIRPREFIX}message_queue_urgent} places the message at the +front of the queue. The message is copied to a message buffer +from this message queue's buffer pool and then placed in the +message queue. Neither directive can successfully send a +message to a message queue which has a full queue of pending +messages. + +@subsection Broadcasting a Message + +The @code{@value{DIRPREFIX}message_queue_broadcast} directive sends the same +message to every task waiting on the specified message queue as +an atomic operation. The message is copied to each waiting +task's message buffer and each task is unblocked. The number of +tasks which were unblocked is returned to the caller. + +@subsection Deleting a Message Queue + +The @code{@value{DIRPREFIX}message_queue_delete} directive removes a message +queue from the system and frees its control block as well as the +memory associated with this message queue's message buffer pool. +A message queue can be deleted by any local task that knows the +message queue's ID. As a result of this directive, all tasks +blocked waiting to receive a message from the message queue will +be readied and returned a status code which indicates that the +message queue was deleted. Any subsequent references to the +message queue's name and ID are invalid. Any messages waiting +at the message queue are also deleted and deallocated. + +@section Directives + +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. + +@c +@c +@c +@page +@subsection MESSAGE_QUEUE_CREATE - Create a queue + +@cindex create a message queue + +@subheading CALLING SEQUENCE: + +@ifset is-C +@findex rtems_message_queue_create +@example +rtems_status_code rtems_message_queue_create( + rtems_name name, + rtems_unsigned32 count, + rtems_unsigned32 max_message_size, + rtems_attribute attribute_set, + rtems_id *id +); +@end example +@end ifset + +@ifset is-Ada +@example +procedure Message_Queue_Create ( + Name : in RTEMS.Name; + Count : in RTEMS.Unsigned32; + Max_Message_Size : in RTEMS.Unsigned32; + Attribute_Set : in RTEMS.Attribute; + ID : out RTEMS.ID; + Result : out RTEMS.Status_Codes +); +@end example +@end ifset + +@subheading DIRECTIVE STATUS CODES: +@code{@value{RPREFIX}SUCCESSFUL} - queue created successfully@* +@code{@value{RPREFIX}INVALID_NAME} - invalid task name@* +@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@* +@code{@value{RPREFIX}INVALID_NUMBER} - invalid message count@* +@code{@value{RPREFIX}INVALID_SIZE} - invalid message size@* +@code{@value{RPREFIX}TOO_MANY} - too many queues created@* +@code{@value{RPREFIX}MP_NOT_CONFIGURED} - multiprocessing not configured@* +@code{@value{RPREFIX}TOO_MANY} - too many global objects + +@subheading 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 @code{@value{RPREFIX}PRIORITY} in attribute_set causes tasks +waiting for a message to be serviced according to task priority. +When @code{@value{RPREFIX}FIFO} is specified, waiting tasks are serviced in First +In-First Out order. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +The following message queue attribute constants are +defined by RTEMS: + +@itemize @bullet +@item @code{@value{RPREFIX}FIFO} - tasks wait by FIFO (default) +@item @code{@value{RPREFIX}PRIORITY} - tasks wait by priority +@item @code{@value{RPREFIX}LOCAL} - local message queue (default) +@item @code{@value{RPREFIX}GLOBAL} - global message queue +@end itemize + +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. + +@c +@c +@c +@page +@subsection MESSAGE_QUEUE_IDENT - Get ID of a queue + +@cindex get ID of a message queue + +@subheading CALLING SEQUENCE: + +@ifset is-C +@findex rtems_message_queue_ident +@example +rtems_status_code rtems_message_queue_ident( + rtems_name name, + rtems_unsigned32 node, + rtems_id *id +); +@end example +@end ifset + +@ifset is-Ada +@example +procedure Message_Queue_Ident ( + Name : in RTEMS.Name; + Node : in RTEMS.Unsigned32; + ID : out RTEMS.ID; + Result : out RTEMS.Status_Codes +); +@end example +@end ifset + +@subheading DIRECTIVE STATUS CODES: +@code{@value{RPREFIX}SUCCESSFUL} - queue identified successfully@* +@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@* +@code{@value{RPREFIX}INVALID_NAME} - queue name not found@* +@code{@value{RPREFIX}INVALID_NODE} - invalid node id + +@subheading 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. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +If node is @code{@value{RPREFIX}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. + +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. + +@c +@c +@c +@page +@subsection MESSAGE_QUEUE_DELETE - Delete a queue + +@cindex delete a message queue + +@subheading CALLING SEQUENCE: + +@ifset is-C +@findex rtems_message_queue_delete +@example +rtems_status_code rtems_message_queue_delete( + rtems_id id +); +@end example +@end ifset + +@ifset is-Ada +@example +procedure Message_Queue_Delete ( + ID : in RTEMS.ID; + Result : out RTEMS.Status_Codes +); +@end example +@end ifset + +@subheading DIRECTIVE STATUS CODES: +@code{@value{RPREFIX}SUCCESSFUL} - queue deleted successfully@* +@code{@value{RPREFIX}INVALID_ID} - invalid queue id@* +@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - cannot delete remote queue + +@subheading 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. + +@subheading 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. + +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 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. + +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. + +Proxies, used to represent remote tasks, are +reclaimed when the message queue is deleted. + +@c +@c +@c +@page +@subsection MESSAGE_QUEUE_SEND - Put message at rear of a queue + +@cindex send message to a queue + +@subheading CALLING SEQUENCE: + +@ifset is-C +@findex rtems_message_queue_send +@example +rtems_status_code rtems_message_queue_send( + rtems_id id, + void *buffer, + rtems_unsigned32 size +); +@end example +@end ifset + +@ifset is-Ada +@example +procedure Message_Queue_Send ( + ID : in RTEMS.ID; + Buffer : in RTEMS.Address; + Size : in RTEMS.Unsigned32; + Result : out RTEMS.Status_Codes +); +@end example +@end ifset + +@subheading DIRECTIVE STATUS CODES: +@code{@value{RPREFIX}SUCCESSFUL} - message sent successfully@* +@code{@value{RPREFIX}INVALID_ID} - invalid queue id@* +@code{@value{RPREFIX}INVALID_SIZE} - invalid message size@* +@code{@value{RPREFIX}INVALID_ADDRESS} - @code{buffer} is NULL@* +@code{@value{RPREFIX}UNSATISFIED} - out of message buffers@* +@code{@value{RPREFIX}TOO_MANY} - queue's limit has been reached + +@subheading 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. + +@subheading 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. + +@c +@c +@c +@page +@subsection MESSAGE_QUEUE_URGENT - Put message at front of a queue + +@cindex put message at front of queue + +@subheading CALLING SEQUENCE: + +@ifset is-C +@findex rtems_message_queue_urgent +@example +rtems_status_code rtems_message_queue_urgent( + rtems_id id, + void *buffer, + rtems_unsigned32 size +); +@end example +@end ifset + +@ifset is-Ada +@example +procedure Message_Queue_Urgent ( + ID : in RTEMS.ID; + Buffer : in RTEMS.Address; + Size : in RTEMS.Unsigned32; + Result : out RTEMS.Status_Codes +); +@end example +@end ifset + +@subheading DIRECTIVE STATUS CODES: +@code{@value{RPREFIX}SUCCESSFUL} - message sent successfully@* +@code{@value{RPREFIX}INVALID_ID} - invalid queue id@* +@code{@value{RPREFIX}INVALID_SIZE} - invalid message size@* +@code{@value{RPREFIX}INVALID_ADDRESS} - @code{buffer} is NULL@* +@code{@value{RPREFIX}UNSATISFIED} - out of message buffers@* +@code{@value{RPREFIX}TOO_MANY} - queue's limit has been reached + +@subheading 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. + +@subheading 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. + +@c +@c +@c +@page +@subsection MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue + +@cindex broadcast message to a queue + +@subheading CALLING SEQUENCE: + +@ifset is-C +@findex rtems_message_queue_broadcast +@example +rtems_status_code rtems_message_queue_broadcast( + rtems_id id, + void *buffer, + rtems_unsigned32 size, + rtems_unsigned32 *count +); +@end example +@end ifset + +@ifset is-Ada +@example +procedure Message_Queue_Broadcast ( + ID : in RTEMS.ID; + Buffer : in RTEMS.Address; + Size : in RTEMS.Unsigned32; + Count : out RTEMS.Unsigned32; + Result : out RTEMS.Status_Codes +); +@end example +@end ifset + +@subheading DIRECTIVE STATUS CODES: +@code{@value{RPREFIX}SUCCESSFUL} - message broadcasted successfully@* +@code{@value{RPREFIX}INVALID_ID} - invalid queue id@* +@code{@value{RPREFIX}INVALID_ADDRESS} - @code{buffer} is NULL@* +@code{@value{RPREFIX}INVALID_ADDRESS} - @code{count} is NULL@* +@code{@value{RPREFIX}INVALID_SIZE} - invalid message size + +@subheading 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. + +@subheading 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 @code{@value{DIRPREFIX}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. + +@c +@c +@c +@page +@subsection MESSAGE_QUEUE_RECEIVE - Receive message from a queue + +@cindex receive message from a queue + +@subheading CALLING SEQUENCE: + +@ifset is-C +@findex rtems_message_queue_receive +@example +rtems_status_code rtems_message_queue_receive( + rtems_id id, + void *buffer, + rtems_unsigned32 *size, + rtems_unsigned32 option_set, + rtems_interval timeout +); +@end example +@end ifset + +@ifset is-Ada +@example +procedure Message_Queue_Receive ( + ID : in RTEMS.ID; + Buffer : in RTEMS.Address; + Option_Set : in RTEMS.Option; + Timeout : in RTEMS.Interval; + Size : out RTEMS.Unsigned32; + Result : out RTEMS.Status_Codes +); +@end example +@end ifset + +@subheading DIRECTIVE STATUS CODES: +@code{@value{RPREFIX}SUCCESSFUL} - message received successfully@* +@code{@value{RPREFIX}INVALID_ID} - invalid queue id@* +@code{@value{RPREFIX}INVALID_ADDRESS} - @code{buffer} is NULL@* +@code{@value{RPREFIX}INVALID_ADDRESS} - @code{count} is NULL@* +@code{@value{RPREFIX}UNSATISFIED} - queue is empty@* +@code{@value{RPREFIX}TIMEOUT} - timed out waiting for message@* +@code{@value{RPREFIX}OBJECT_WAS_DELETED} - queue deleted while waiting + +@subheading DESCRIPTION: + +This directive receives a message from the message +queue specified in id. The @code{@value{RPREFIX}WAIT} and @code{@value{RPREFIX}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. + +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 @code{@value{RPREFIX}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 +@code{@value{RPREFIX}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 +@code{@value{RPREFIX}NO_TIMEOUT}, then the calling task will wait forever. + +@subheading NOTES: + +The following message receive option constants are +defined by RTEMS: + +@itemize @bullet +@item @code{@value{RPREFIX}WAIT} - task will wait for a message (default) +@item @code{@value{RPREFIX}NO_WAIT} - task should not wait +@end itemize + +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 @code{@value{RPREFIX}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. + +@c +@c +@c +@page +@subsection MESSAGE_QUEUE_GET_NUMBER_PENDING - Get number of messages pending on a queue + +@cindex get number of pending messages + +@subheading CALLING SEQUENCE: + +@ifset is-C +@findex rtems_message_queue_get_number_pending +@example +rtems_status_code rtems_message_queue_get_number_pending( + rtems_id id, + rtems_unsigned32 *count +); +@end example +@end ifset + +@ifset is-Ada +@example +procedure Message_Queue_Get_Number_Pending ( + ID : in RTEMS.ID; + Count : out RTEMS.Unsigned32; + Result : out RTEMS.Status_Codes +); +@end example +@end ifset + +@subheading DIRECTIVE STATUS CODES: +@code{@value{RPREFIX}SUCCESSFUL} - number of messages pending returned successfully@* +@code{@value{RPREFIX}INVALID_ADDRESS} - @code{count} is NULL@* +@code{@value{RPREFIX}INVALID_ID} - invalid queue id + +@subheading 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. + +@subheading 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. + + +@c +@c +@c +@page +@subsection MESSAGE_QUEUE_FLUSH - Flush all messages on a queue + +@cindex flush messages on a queue + +@subheading CALLING SEQUENCE: + +@ifset is-C +@findex rtems_message_queue_flush +@example +rtems_status_code rtems_message_queue_flush( + rtems_id id, + rtems_unsigned32 *count +); +@end example +@end ifset + +@ifset is-Ada +@example +procedure Message_Queue_Flush ( + ID : in RTEMS.ID; + Count : out RTEMS.Unsigned32; + Result : out RTEMS.Status_Codes +); +@end example +@end ifset + +@subheading DIRECTIVE STATUS CODES: +@code{@value{RPREFIX}SUCCESSFUL} - message queue flushed successfully@* +@code{@value{RPREFIX}INVALID_ADDRESS} - @code{count} is NULL@* +@code{@value{RPREFIX}INVALID_ID} - invalid queue id + +@subheading 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. + +@subheading 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. + |