RTEMS 4.8.0 On-Line Library

Message Manager MESSAGE_QUEUE_RECEIVE - Receive message from a queue

RTEMS C User's Guide

10.4.7: MESSAGE_QUEUE_RECEIVE - Receive message from a queue

CALLING SEQUENCE:

rtems_status_code rtems_message_queue_receive(
  rtems_id        id,
  void           *buffer,
  size_t         *size,
  uint32_t        option_set,
  rtems_interval  timeout
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL - message received successfully
RTEMS_INVALID_ID - invalid queue id
RTEMS_INVALID_ADDRESS - buffer is NULL
RTEMS_INVALID_ADDRESS - count 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.

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 C User's Guide