diff options
Diffstat (limited to 'posix_users/message_passing.rst')
| -rw-r--r-- | posix_users/message_passing.rst | 741 |
1 files changed, 0 insertions, 741 deletions
diff --git a/posix_users/message_passing.rst b/posix_users/message_passing.rst deleted file mode 100644 index 64c64a3..0000000 --- a/posix_users/message_passing.rst +++ /dev/null @@ -1,741 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -.. COMMENT: COPYRIGHT (c) 1988-2014. -.. COMMENT: On-Line Applications Research Corporation (OAR). -.. COMMENT: All rights reserved. - -Message Passing Manager -####################### - -Introduction -============ - -The message passing manager is the means to provide communication and -synchronization capabilities using POSIX message queues. - -The directives provided by the message passing manager are: - -- mq_open_ - Open a Message Queue - -- mq_close_ - Close a Message Queue - -- mq_unlink_ - Remove a Message Queue - -- mq_send_ - Send a Message to a Message Queue - -- mq_receive_ - Receive a Message from a Message Queue - -- mq_notify_ - Notify Process that a Message is Available - -- mq_setattr_ - Set Message Queue Attributes - -- mq_getattr_ - Get Message Queue Attributes - -Background -========== - -Theory ------- - -Message queues are named objects that operate with readers and writers. In -addition, a message queue is a priority queue of discrete messages. POSIX -message queues offer a certain, basic amount of application access to, and -control over, the message queue geometry that can be changed. - -Messages --------- - -A message is a variable length buffer where information can be stored to -support communication. The length of the message and the information stored in -that message are user-defined and can be actual data, pointer(s), or -empty. There is a maximum acceptable length for a message that is associated -with each message queue. - -Message Queues --------------- - -Message queues are named objects similar to the pipes of POSIX. They are a -means of communicating data between multiple processes and for passing messages -among tasks and ISRs. Message queues can contain a variable number of messages -from 0 to an upper limit that is user defined. The maximum length of the -message can be set on a per message queue basis. Normally messages are sent -and received from the message queue in FIFO order. However, messages can also -be prioritized and a priority queue established for the passing of -messages. Synchronization is needed when a task waits for a message to arrive -at a queue. Also, a task may poll a queue for the arrival of a message. - -.. index:: mqd_t - -The message queue descriptor ``mqd_t`` represents the message queue. It is -passed as an argument to all of the message queue functions. - -Building a Message Queue Attribute Set --------------------------------------- - -The ``mq_attr`` structure is used to define the characteristics of the message -queue. - -.. index:: mq_attr - -.. code-block:: c - - typedef struct mq_attr{ - long mq_flags; - long mq_maxmsg; - long mq_msgsize; - long mq_curmsgs; - }; - -All of these attributes are set when the message queue is created using -mq_open. The mq_flags field is not used in the creation of a message queue, it -is only used by ``mq_setattr`` and ``mq_getattr``. The structure ``mq_attr`` is -passed as an argument to ``mq_setattr`` and ``mq_getattr``. - -The mq_flags contain information affecting the behavior of the message -queue. The ``O_NONBLOCK`` ``mq_flag`` is the only flag that is defined. In -``mq_setattr``, the ``mq_flag`` can be set to dynamically change the blocking -and non-blocking behavior of the message queue. If the non-block flag is set -then the message queue is non-blocking, and requests to send and receive -messages do not block waiting for resources. For a blocking message queue, a -request to send might have to wait for an empty message queue, and a request to -receive might have to wait for a message to arrive on the queue. Both -``mq_maxmsg`` and ``mq_msgsize`` affect the sizing of the message -queue. ``mq_maxmsg`` specifies how many messages the queue can hold at any one -time. ``mq_msgsize`` specifies the size of any one message on the queue. If -either of these limits is exceeded, an error message results. - -Upon return from ``mq_getattr``, the ``mq_curmsgs`` is set according to the -current state of the message queue. This specifies the number of messages -currently on the queue. - -Notification of a Message on the Queue --------------------------------------- - -Every message queue has the ability to notify one (and only one) process -whenever the queue's state changes from empty (0 messages) to nonempty. This -means that the process does not have to block or constantly poll while it waits -for a message. By calling ``mq_notify``, you can attach a notification request -to a message queue. When a message is received by an empty queue, if there are -no processes blocked and waiting for the message, then the queue notifies the -requesting process of a message arrival. There is only one signal sent by the -message queue, after that the notification request is de-registered and another -process can attach its notification request. After receipt of a notification, a -process must re-register if it wishes to be notified again. - -If there is a process blocked and waiting for the message, that process gets -the message, and notification is not sent. It is also possible for another -process to receive the message after the notification is sent but before the -notified process has sent its receive request. - -Only one process can have a notification request attached to a message queue at -any one time. If another process attempts to register a notification request, -it fails. You can de-register for a message queue by passing a NULL to -mq_notify, this removes any notification request attached to the -queue. Whenever the message queue is closed, all notification attachments are -removed. - -POSIX Interpretation Issues ---------------------------- - -There is one significant point of interpretation related to the RTEMS -implementation of POSIX message queues: - - | What happens to threads already blocked on a message queue when the mode - | of that same message queue is changed from blocking to non-blocking? - -The RTEMS POSIX implementation decided to unblock all waiting tasks with an -``EAGAIN`` status just as if a non-blocking version of the same operation had -returned unsatisfied. This case is not discussed in the POSIX standard and -other implementations may have chosen alternative behaviors. - -Operations -========== - -Opening or Creating a Message Queue ------------------------------------ - -If the message queue already exists, ``mq_open()`` opens it, if the message -queue does not exist, ``mq_open()`` creates it. When a message queue is -created, the geometry of the message queue is contained in the attribute -structure that is passed in as an argument. This includes mq_msgsize that -dictates the maximum size of a single message, and the mq_maxmsg that dictates -the maximum number of messages the queue can hold at one time. The blocking or -non-blocking behavior of the queue can also specified. - -Closing a Message Queue ------------------------ - -The ``mq_close()`` function is used to close the connection made to a message -queue that was made during mq_open. The message queue itself and the messages -on the queue are persistent and remain after the queue is closed. - -Removing a Message Queue ------------------------- - -The ``mq_unlink()`` function removes the named message queue. If the message -queue is not open when mq_unlink is called, then the queue is immediately -eliminated. Any messages that were on the queue are lost, and the queue can not -be opened again. If processes have the queue open when mq_unlink is called, the -removal of the queue is delayed until the last process using the queue has -finished. However, the name of the message queue is removed so that no other -process can open it. - -Sending a Message to a Message Queue ------------------------------------- - -The ``mq_send()`` function adds the message in priority order to the message -queue. Each message has an assigned a priority. The highest priority message is -be at the front of the queue. - -The maximum number of messages that a message queue may accept is specified at -creation by the ``mq_maxmsg`` field of the attribute structure. If this amount -is exceeded, the behavior of the process is determined according to what -``oflag`` was used when the message queue was opened. If the queue was opened -with ``O_NONBLOCK`` flag set, the process does not block, and an error is -returned. If the ``O_NONBLOCK`` flag was not set, the process does block and -wait for space on the queue. - -Receiving a Message from a Message Queue ----------------------------------------- - -The ``mq_receive()`` function is used to receive the oldest of the highest -priority message(s) from the message queue specified by mqdes. The messages are -received in FIFO order within the priorities. The received message's priority -is stored in the location referenced by the ``msg_prio``. If the ``msg_prio`` -is a ``NULL``, the priority is discarded. The message is removed and stored in -an area pointed to by ``msg_ptr`` whose length is of ``msg_len``. The -``msg_len`` must be at least equal to the ``mq_msgsize`` attribute of the -message queue. - -The blocking behavior of the message queue is set by ``O_NONBLOCK`` at -``mq_open`` or by setting ``O_NONBLOCK`` in ``mq_flags`` in a call to -``mq_setattr``. If this is a blocking queue, the process does block and wait on -an empty queue. If this a non-blocking queue, the process does not block. Upon -successful completion, ``mq_receive`` returns the length of the selected -message in bytes and the message is removed from the queue. - -Notification of Receipt of a Message on an Empty Queue ------------------------------------------------------- - -The ``mq_notify()`` function registers the calling process to be notified of -message arrival at an empty message queue. Every message queue has the ability -to notify one (and only one) process whenever the queue's state changes from -empty (0 messages) to nonempty. This means that the process does not have to -block or constantly poll while it waits for a message. By calling -``mq_notify``, a notification request is attached to a message queue. When a -message is received by an empty queue, if there are no processes blocked and -waiting for the message, then the queue notifies the requesting process of a -message arrival. There is only one signal sent by the message queue, after that -the notification request is de-registered and another process can attach its -notification request. After receipt of a notification, a process must -re-register if it wishes to be notified again. - -If there is a process blocked and waiting for the message, that process gets -the message, and notification is not sent. Only one process can have a -notification request attached to a message queue at any one time. If another -process attempts to register a notification request, it fails. You can -de-register for a message queue by passing a ``NULL`` to ``mq_notify``, this -removes any notification request attached to the queue. Whenever the message -queue is closed, all notification attachments are removed. - -Setting the Attributes of a Message Queue ------------------------------------------ - -The ``mq_setattr()`` function is used to set attributes associated with the -open message queue description referenced by the message queue descriptor -specified by mqdes. The ``*omqstat`` represents the old or previous -attributes. If ``omqstat`` is non-``NULL``, the function ``mq_setattr()`` -stores, in the location referenced by omqstat, the previous message queue -attributes and the current queue status. These values are the same as would be -returned by a call to ``mq_getattr()`` at that point. - -There is only one ``mq_attr.mq_flag`` that can be altered by this call. This is -the flag that deals with the blocking and non-blocking behavior of the message -queue. If the flag is set then the message queue is non-blocking, and requests -to send or receive do not block while waiting for resources. If the flag is -not set, then message send and receive may involve waiting for an empty queue -or waiting for a message to arrive. - -Getting the Attributes of a Message Queue ------------------------------------------ - -The ``mq_getattr()`` function is used to get status information and attributes -of the message queue associated with the message queue descriptor. The results -are returned in the mq_attr structure referenced by the mqstat argument. All of -these attributes are set at create time, except the blocking/non-blocking -behavior of the message queue which can be dynamically set by using -mq_setattr. The attribute mq_curmsg is set to reflect the number of messages on -the queue at the time that ``mq_getattr`` was called. - -Directives -========== - -This section details the message passing manager's directives. A subsection is -dedicated to each of this manager's directives and describes the calling -sequence, related constants, usage, and status codes. - -.. _mq_open: - -mq_open - Open a Message Queue ------------------------------- -.. index:: mq_open -.. index:: open a message queue - -**CALLING SEQUENCE:** - -.. code-block:: c - - #include <mqueue.h> - mqd_t mq_open( - const char *name, - int oflag, - mode_t mode, - struct mq_attr *attr - ); - -**STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``EACCES`` - - Either the message queue exists and the permissions requested in - ``oflags`` were denied, or the message does not exist and permission to - create one is denied. - * - ``EEXIST`` - - You tried to create a message queue that already exists. - * - ``EINVAL`` - - An inappropriate name was given for the message queue, or the values of - ``mq-maxmsg`` or ``mq_msgsize`` were less than 0. - * - ``ENOENT`` - - The message queue does not exist, and you did not specify to create it. - * - ``EINTR`` - - The call to mq_open was interrupted by a signal. - * - ``EMFILE`` - - The process has too many files or message queues open. This is a process - limit error. - * - ``ENFILE`` - - The system has run out of resources to support more open message - queues. This is a system error. - * - ``ENAMETOOLONG`` - - ``mq_name`` is too long. - -**DESCRIPTION:** - -The ``mq_open()`` function establishes the connection between a process and a -message queue with a message queue descriptor. If the message queue already -exists, ``mq_open`` opens it, if the message queue does not exist, ``mq_open`` -creates it. Message queues can have multiple senders and receivers. If -``mq_open`` is successful, the function returns a message queue -descriptor. Otherwise, the function returns a -1 and sets ``errno`` to indicate -the error. - -The name of the message queue is used as an argument. For the best of -portability, the name of the message queue should begin with a "/" and no other -"/" should be in the name. Different systems interpret the name in different -ways. - -The ``oflags`` contain information on how the message is opened if the queue -already exists. This may be ``O_RDONLY`` for read only, ``O_WRONLY`` for write -only, of O_RDWR, for read and write. - -In addition, the ``oflags`` contain information needed in the creation of a message -queue. - -.. list-table:: - :class: rtems-table - - * - ``O_NONBLOCK`` - - If the non-block flag is set then the message queue is non-blocking, and - requests to send and receive messages do not block waiting for - resources. If the flag is not set then the message queue is blocking, and - a request to send might have to wait for an empty message - queue. Similarly, a request to receive might have to wait for a message to - arrive on the queue. - * - ``O_CREAT`` - - This call specifies that the call the mq_open is to create a new message - queue. In this case the mode and attribute arguments of the function call - are utilized. The message queue is created with a mode similar to the - creation of a file, read and write permission creator, group, and others. - The geometry of the message queue is contained in the attribute structure. - This includes mq_msgsize that dictates the maximum size of a single - message, and the mq_maxmsg that dictates the maximum number of messages - the queue can hold at one time. If a ``NULL`` is used in the mq_attr - argument, then the message queue is created with implementation defined - defaults. - * - ``O_EXCL`` - - is always set if ``O_CREAT`` flag is set. If the message queue already - exists, ``O_EXCL`` causes an error message to be returned, otherwise, the - new message queue fails and appends to the existing one. - -**NOTES:** - -The ``mq_open()`` function does not add or remove messages from the queue. -When a new message queue is being created, the ``mq_flag`` field of the -attribute structure is not used. - -.. _mq_close: - -mq_close - Close a Message Queue --------------------------------- -.. index:: mq_close -.. index:: close a message queue - -**CALLING SEQUENCE:** - -.. code-block:: c - - #include <mqueue.h> - int mq_close( - mqd_t mqdes - ); - -**STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``EINVAL`` - - The descriptor does not represent a valid open message queue - -**DESCRIPTION:** - -The ``mq_close`` function removes the association between the message queue -descriptor, mqdes, and its message queue. If ``mq_close()`` is successfully -completed, the function returns a value of zero; otherwise, the function -returns a value of -1 and sets ``errno`` to indicate the error. - -**NOTES:** - -If the process had successfully attached a notification request to the message -queue via ``mq_notify``, this attachment is removed, and the message queue is -available for another process to attach for notification. ``mq_close`` has no -effect on the contents of the message queue, all the messages that were in the -queue remain in the queue. - -.. _mq_unlink: - -mq_unlink - Remove a Message Queue ----------------------------------- -.. index:: mq_unlink -.. index:: remove a message queue - -**CALLING SEQUENCE:** - -.. code-block:: c - - #include <mqueue.h> - int mq_unlink( - const char *name - ); - -**STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``EINVAL`` - - The descriptor does not represent a valid message queue - -**DESCRIPTION:** - -The ``mq_unlink()`` function removes the named message queue. If the message -queue is not open when ``mq_unlink`` is called, then the queue is immediately -eliminated. Any messages that were on the queue are lost, and the queue can not -be opened again. If processes have the queue open when ``mq_unlink`` is called, -the removal of the queue is delayed until the last process using the queue has -finished. However, the name of the message queue is removed so that no other -process can open it. Upon successful completion, the function returns a value -of zero. Otherwise, the named message queue is not changed by this function -call, and the function returns a value of --1 and sets ``errno`` to indicate the error. - -**NOTES:** - -Calls to ``mq_open()`` to re-create the message queue may fail until the -message queue is actually removed. However, the ``mq_unlink()`` call need not -block until all references have been closed; it may return immediately. - -.. _mq_send: - -mq_send - Send a Message to a Message Queue -------------------------------------------- -.. index:: mq_send -.. index:: send a message to a message queue - -**CALLING SEQUENCE:** - -.. code-block:: c - - #include<mqueue.h> - int mq_send( - mqd_t mqdes, - const char *msg_ptr, - size_t msg_len, - unsigned int msg_prio - ); - -**STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``EBADF`` - - The descriptor does not represent a valid message queue, or the queue was - opened for read only ``O_RDONLY`` - * - ``EINVAL`` - - The value of msg_prio was greater than the ``MQ_PRIO_MAX``. - * - ``EMSGSIZE`` - - The msg_len is greater than the ``mq_msgsize`` attribute of the message - queue - * - ``EAGAIN`` - - The message queue is non-blocking, and there is no room on the queue for - another message as specified by the ``mq_maxmsg``. - * - ``EINTR`` - - The message queue is blocking. While the process was waiting for free - space on the queue, a signal arrived that interrupted the wait. - -**DESCRIPTION:** - -The ``mq_send()`` function adds the message pointed to by the argument -``msg_ptr`` to the message queue specified by mqdes. Each message is assigned a -priority , from 0 to ``MQ_PRIO_MAX``. ``MQ_PRIO_MAX`` is defined in -``<limits.h>`` and must be at least 32. Messages are added to the queue in -order of their priority. The highest priority message is at the front of the -queue. - -The maximum number of messages that a message queue may accept is specified at -creation by the ``mq_maxmsg`` field of the attribute structure. If this amount is -exceeded, the behavior of the process is determined according to what oflag was -used when the message queue was opened. If the queue was opened with ``O_NONBLOCK`` -flag set, then the ``EAGAIN`` error is returned. If the ``O_NONBLOCK`` flag was not -set, the process blocks and waits for space on the queue, unless it is -interrupted by a signal. - -Upon successful completion, the ``mq_send()`` function returns a value of -zero. Otherwise, no message is enqueued, the function returns -1, and ``errno`` -is set to indicate the error. - -**NOTES:** - -If the specified message queue is not full, ``mq_send`` inserts the message at -the position indicated by the ``msg_prio`` argument. - -.. _mq_receive: - -mq_receive - Receive a Message from a Message Queue ---------------------------------------------------- -.. index:: mq_receive -.. index:: receive a message from a message queue - -**CALLING SEQUENCE:** - -.. code-block:: c - - #include <mqueue.h> - size_t mq_receive( - mqd_t mqdes, - char *msg_ptr, - size_t msg_len, - unsigned int *msg_prio - ); - -**STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``EBADF`` - - The descriptor does not represent a valid message queue, or the queue was - opened for write only ``O_WRONLY`` - * - ``EMSGSIZE`` - - The msg_len is less than the ``mq_msgsize`` attribute of the message queue - * - ``EAGAIN`` - - The message queue is non-blocking, and the queue is empty - * - ``EINTR`` - - The message queue is blocking. While the process was waiting for a message - to arrive on the queue, a signal arrived that interrupted the wait. - -**DESCRIPTION:** - -The ``mq_receive`` function is used to receive the oldest of the highest -priority message(s) from the message queue specified by mqdes. The messages are -received in FIFO order within the priorities. The received message's priority -is stored in the location referenced by the ``msg_prio``. If the ``msg_prio`` -is a ``NULL``, the priority is discarded. The message is removed and stored in -an area pointed to by ``msg_ptr`` whose length is of ``msg_len``. The -``msg_len`` must be at least equal to the mq_msgsize attribute of the message -queue. - -The blocking behavior of the message queue is set by ``O_NONBLOCK`` at -``mq_open`` or by setting ``O_NONBLOCK`` in ``mq_flags`` in a call to -``mq_setattr``. If this is a blocking queue, the process blocks and waits on an -empty queue. If this a non-blocking queue, the process does not block. - -Upon successful completion, ``mq_receive`` returns the length of the selected -message in bytes and the message is removed from the queue. Otherwise, no -message is removed from the queue, the function returns a value of -1, and sets -``errno`` to indicate the error. - -**NOTES:** - -If the size of the buffer in bytes, specified by the ``msg_len`` argument, is -less than the ``mq_msgsize`` attribute of the message queue, the function fails -and returns an error - -.. _mq_notify: - -mq_notify - Notify Process that a Message is Available ------------------------------------------------------- -.. index:: mq_notify -.. index:: notify process that a message is available - -**CALLING SEQUENCE:** - -.. code-block:: c - - #include <mqueue.h> - int mq_notify( - mqd_t mqdes, - const struct sigevent *notification - ); - -**STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``EBADF`` - - The descriptor does not refer to a valid message queue - * - ``EBUSY`` - - A notification request is already attached to the queue - -**DESCRIPTION:** - -If the argument notification is not ``NULL``, this function registers the -calling process to be notified of message arrival at an empty message queue -associated with the specified message queue descriptor, ``mqdes``. - -Every message queue has the ability to notify one (and only one) process -whenever the queue's state changes from empty (0 messages) to nonempty. This -means that the process does not have to block or constantly poll while it waits -for a message. By calling ``mq_notify``, a notification request is attached to -a message queue. When a message is received by an empty queue, if there are no -processes blocked and waiting for the message, then the queue notifies the -requesting process of a message arrival. There is only one signal sent by the -message queue, after that the notification request is de-registered and another -process can attach its notification request. After receipt of a notification, a -process must re-register if it wishes to be notified again. - -If there is a process blocked and waiting for the message, that process -gets the message, and notification is not be sent. Only one process can -have a notification request attached to a message queue at any one time. -If another process attempts to register a notification request, it fails. -You can de-register for a message queue by passing a NULL to mq_notify; -this removes any notification request attached to the queue. Whenever the -message queue is closed, all notification attachments are removed. - -Upon successful completion, mq_notify returns a value of zero; otherwise, the -function returns a value of -1 and sets ``errno`` to indicate the error. - -**NOTES:** - -It is possible for another process to receive the message after the -notification is sent but before the notified process has sent its receive -request. - -.. _mq_setattr: - -mq_setattr - Set Message Queue Attributes ------------------------------------------ -.. index:: mq_setattr -.. index:: set message queue attributes - -**CALLING SEQUENCE:** - -.. code-block:: c - - #include <mqueue.h> - int mq_setattr( - mqd_t mqdes, - const struct mq_attr *mqstat, - struct mq_attr *omqstat - ); - -**STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``EBADF`` - - The message queue descriptor does not refer to a valid, open queue. - * - ``EINVAL`` - - The mq_flag value is invalid. - -**DESCRIPTION:** - -The ``mq_setattr`` function is used to set attributes associated with the open -message queue description referenced by the message queue descriptor specified -by mqdes. The ``*omqstat`` represents the old or previous attributes. If -``omqstat`` is non-``NULL``, the function ``mq_setattr()`` stores, in the -location referenced by ``omqstat``, the previous message queue attributes and -the current queue status. These values are the same as would be returned by a -call to ``mq_getattr()`` at that point. - -There is only one mq_attr.mq_flag which can be altered by this call. This is -the flag that deals with the blocking and non-blocking behavior of the message -queue. If the flag is set then the message queue is non-blocking, and requests -to send or receive do not block while waiting for resources. If the flag is not -set, then message send and receive may involve waiting for an empty queue or -waiting for a message to arrive. - -Upon successful completion, the function returns a value of zero and the -attributes of the message queue have been changed as specified. Otherwise, the -message queue attributes is unchanged, and the function returns a value of -1 -and sets ``errno`` to indicate the error. - -**NOTES:** - -All other fields in the ``mq_attr`` are ignored by this call. - -.. _mq_getattr: - -mq_getattr - Get Message Queue Attributes ------------------------------------------ -.. index:: mq_getattr -.. index:: get message queue attributes - -**CALLING SEQUENCE:** - -.. code-block:: c - - #include <mqueue.h> - int mq_getattr( - mqd_t mqdes, - struct mq_attr *mqstat - ); - -**STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``EBADF`` - - The message queue descriptor does not refer to a valid, open message - queue. - -**DESCRIPTION:** - -The ``mqdes`` argument specifies a message queue descriptor. The ``mq_getattr`` -function is used to get status information and attributes of the message queue -associated with the message queue descriptor. The results are returned in the -``mq_attr`` structure referenced by the mqstat argument. All of these -attributes are set at create time, except the blocking/non-blocking behavior of -the message queue which can be dynamically set by using mq_setattr. The -attribute ``mq_curmsg`` is set to reflect the number of messages on the queue -at the time that ``mq_getattr`` was called. - -Upon successful completion, the ``mq_getattr`` function returns zero. -Otherwise, the function returns -1 and sets ``errno`` to indicate the error. - -**NOTES:** |