SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
  Creates a message queue.
copyrights:
- Copyright (C) 2021 embedded brains GmbH & Co. KG
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
  default:
    attributes: null
    body: null
    params:
    - ${../../type/if/name:/name} ${.:/params[0]/name}
    - ${/c/if/uint32_t:/name} ${.:/params[1]/name}
    - ${/c/if/size_t:/name} ${.:/params[2]/name}
    - ${../../attr/if/attribute:/name} ${.:/params[3]/name}
    - ${../../type/if/id:/name} *${.:/params[4]/name}
    return: ${../../status/if/code:/name}
  variants: []
description: |
  This directive creates a message queue which resides on the local node.  The
  message queue has the user-defined object name specified in
  ${.:/params[0]/name}.  Memory is allocated from the RTEMS Workspace for the
  count of messages specified in ${.:/params[1]/name}, each of
  ${.:/params[2]/name} bytes in length.  The assigned object identifier is
  returned in ${.:/params[4]/name}.  This identifier is used to access the
  message queue with other message queue related directives.

  The **attribute set** specified in ${.:/params[3]/name} is built through a
  *bitwise or* of the attribute constants described below.  Not all
  combinations of attributes are allowed.  Some attributes are mutually
  exclusive.  If mutually exclusive attributes are combined, the behaviour is
  undefined.  Attributes not mentioned below are not evaluated by this
  directive and have no effect.  Default attributes can be selected by using
  the ${../../attr/if/default:/name} constant.  The attribute set defines

  * the scope of the message queue: ${../../attr/if/local:/name} (default) or
    ${../../attr/if/global:/name} and

  * the task wait queue discipline used by the message queue:
    ${../../attr/if/fifo:/name} (default) or ${../../attr/if/priority:/name}.

  The message queue has a local or global **scope** in a multiprocessing network
  (this attribute does not refer to SMP systems).  The scope is selected by the
  mutually exclusive ${../../attr/if/local:/name} and
  ${../../attr/if/global:/name} attributes.

  * A **local scope** is the default and can be emphasized through the use of
    the ${../../attr/if/local:/name} attribute.  A local message queue can be
    only used by the node which created it.

  * A **global scope** is established if the ${../../attr/if/global:/name}
    attribute is set.  Setting the global attribute in a single node system has
    no effect.

  The **task wait queue discipline** is selected by the mutually exclusive
  ${../../attr/if/fifo:/name} and ${../../attr/if/priority:/name} attributes.
  The discipline defines the order in which tasks wait for a message to receive
  on a currently empty message queue.

  * The **FIFO discipline** is the default and can be emphasized
    through use of the ${../../attr/if/fifo:/name} attribute.

  * The **priority discipline** is selected by the
    ${../../attr/if/priority:/name} attribute.
enabled-by: true
index-entries:
- create a message queue
interface-type: function
links:
- role: interface-placement
  uid: header
- role: interface-ingroup
  uid: group
- role: constraint
  uid: /constraint/directive-not-pre-qualified
- role: constraint
  uid: /constraint/directive-ctx-devinit
- role: constraint
  uid: /constraint/directive-ctx-task
- role: constraint
  uid: /constraint/object-allocator
- role: constraint
  uid: /constraint/mp-send
- role: constraint
  uid: ../constraint/max
- role: constraint
  uid: /constraint/obj-unlimited-alloc
- role: constraint
  uid: ../../constraint/mp-max-global-objects
name: rtems_message_queue_create
notes: |
  For message queues with a global scope, the maximum message size is
  effectively limited to the longest message which the ${/glossary/mpci:/term}
  is capable of transmitting.

  For control and maintenance of the message queue, RTEMS allocates a
  ${/glossary/qcb:/term} from the local QCB free pool and initializes it.

  The QCB for a global message queue is allocated on the local node.  Message
  queues should not be made global unless remote tasks must interact with the
  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 identifier must be transmitted to every node in the
  system for insertion in the local copy of the global object table.
params:
- description: |
    is the object name of the message queue.
  dir: null
  name: name
- description: |
    is the maximum count of pending messages supported by the message queue.
  dir: null
  name: count
- description: |
    is the maximum size in bytes of a message supported by the message queue.
  dir: null
  name: max_message_size
- description: |
    is the attribute set of the message queue.
  dir: null
  name: attribute_set
- description: |
    is the pointer to an ${../../type/if/id:/name} object.  When the directive
    call is successful, the identifier of the created message queue will be
    stored in this object.
  dir: out
  name: id
return:
  return: null
  return-values:
  - description: |
      The requested operation was successful.
    value: ${../../status/if/successful:/name}
  - description: |
      The ${.:/params[0]/name} parameter was invalid.
    value: ${../../status/if/invalid-name:/name}
  - description: |
      The ${.:/params[4]/name} parameter was ${/c/if/null:/name}.
    value: ${../../status/if/invalid-address:/name}
  - description: |
      The ${.:/params[1]/name} parameter was invalid.
    value: ${../../status/if/invalid-number:/name}
  - description: |
      The ${.:/params[2]/name} parameter was invalid.
    value: ${../../status/if/invalid-size:/name}
  - description: |
      There was no inactive object available to create a message queue.  The
      number of message queue available to the application is configured
      through the ${/acfg/if/max-message-queues:/name} application
      configuration option.
    value: ${../../status/if/too-many:/name}
  - description: |
      In multiprocessing configurations, there was no inactive global object
      available to create a global message queue.  The number of global objects
      available to the application is configured through the
      ${/acfg/if/mp-max-global-objects:/name} application configuration option.
    value: ${../../status/if/too-many:/name}
  - description: |
      The product of ${.:/params[1]/name} and ${.:/params[2]/name} is greater
      than the maximum storage size.
    value: ${../../status/if/invalid-number:/name}
  - description: |
      There was not enough memory available in the RTEMS Workspace to allocate
      the message buffers for the message queue.
    value: ${../../status/if/unsatisfied:/name}
type: interface