RTEMS 4.9.4 On-Line Library

Message Manager MESSAGE_QUEUE_RECEIVE - Receive message from a queue

RTEMS Ada User's Guide

10.4.7: MESSAGE_QUEUE_RECEIVE - Receive message from a queue

CALLING SEQUENCE:

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
);

DIRECTIVE STATUS CODES:

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:

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.

RTEMS Ada User's Guide