RTEMS 4.7.99.2 On-Line Library

Message Manager MESSAGE_QUEUE_CREATE - Create a queue

RTEMS Ada User's Guide

10.4.1: MESSAGE_QUEUE_CREATE - Create a queue

CALLING SEQUENCE:

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

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