RTEMS 4.8.0 On-Line Library

Message Manager MESSAGE_QUEUE_CREATE - Create a queue

RTEMS C User's Guide

10.4.1: MESSAGE_QUEUE_CREATE - Create a queue

CALLING SEQUENCE:

rtems_status_code rtems_message_queue_create(
  rtems_name        name,
  uint32_t          count,
  uint32_t          max_message_size,
  rtems_attribute   attribute_set,
  rtems_id         *id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL - queue created successfully
RTEMS_INVALID_NAME - invalid task 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:

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.

RTEMS C User's Guide