nuttx/Documentation/reference/user/04_message_queue.rst

371 lines
17 KiB
ReStructuredText
Raw Normal View History

2020-07-21 00:18:26 +02:00
==============================
Named Message Queue Interfaces
==============================
NuttX supports POSIX named message queues for inter-task communication.
Any task may send or receive messages on named message queues. Interrupt
handlers may send messages via named message queues.
- :c:func:`mq_open`
- :c:func:`mq_close`
- :c:func:`mq_unlink`
- :c:func:`mq_send`
- :c:func:`mq_timedsend`
- :c:func:`mq_receive`
- :c:func:`mq_timedreceive`
- :c:func:`mq_notify`
- :c:func:`mq_setattr`
- :c:func:`mq_getattr`
.. c:function:: mqd_t mq_open(const char *mqName, int oflags, ...)
Establishes a connection between a named message queue and the calling
task. After a successful call of mq_open(), the task can reference the
message queue using the address returned by the call. The message queue
remains usable until it is closed by a successful call to mq_close().
2020-07-21 00:18:26 +02:00
:param mqName: Name of the queue to open
:param oflags: Open flags. These may be any combination of:
- ``O_RDONLY``. Open for read access.
- ``O_WRONLY``. Open for write access.
- ``O_RDWR``. Open for both read & write access.
- ``O_CREAT``. Create message queue if it does not already exist.
- ``O_EXCL``. Name must not exist when opened.
- ``O_NONBLOCK``. Don't wait for data.
:param ``...``: **Optional parameters**. When the O_CREAT flag is specified,
POSIX requires that a third and fourth parameter be supplied:
- ``mode``. The mode parameter is of type mode_t. In the POSIX
specification, this mode value provides file permission bits for
the message queue. This parameter is required but not used in the
present implementation.
- ``attr``. A pointer to an mq_attr that is provided to initialize.
the message queue. If attr is NULL, then the messages queue is
created with implementation-defined default message queue
attributes. If attr is non-NULL, then the message queue mq_maxmsg
attribute is set to the corresponding value when the queue is
created. The mq_maxmsg attribute determines the maximum number of
messages that can be queued before addition attempts to send
messages on the message queue fail or cause the sender to block;
the mq_msgsize attribute determines the maximum size of a message
that can be sent or received. Other elements of attr are ignored
(i.e, set to default message queue attributes).
:return: A message queue descriptor or -1 (``ERROR``)
**POSIX Compatibility:** Comparable to the POSIX interface of the same
name. Differences from the full POSIX implementation include:
- The mq_msgsize attributes determines the maximum size of a message
that may be sent or received. In the present implementation, this
maximum message size is limited at 22 bytes.
.. c:function:: int mq_close(mqd_t mqdes)
Used to indicate that the calling task is finished with the specified
message queued ``mqdes``. The ``mq_close()`` deallocates any system
resources allocated by the system for use by this task for its message
queue.
2020-07-21 00:18:26 +02:00
If the calling task has attached a notification request to the message
queue via this ``mqdes`` (see ``mq_notify()``), this attachment will be
removed and the message queue is available for another task to attach
for notification.
:param mqdes: Message queue descriptor.
:return: 0 (``OK``) if the message queue is closed successfully, otherwise, -1
(``ERROR``).
**Assumptions/Limitations:**
- The behavior of a task that is blocked on either a ``mq_send()`` or
``mq_receive()`` is undefined when ``mq_close()`` is called.
- The result of using this message queue descriptor after successful
return from ``mq_close()`` is undefined.
**POSIX Compatibility:** Comparable to the POSIX interface of the same
name.
.. c:function:: int mq_unlink(const char *mqName)
Removes the message queue named by
"mqName." If one or more tasks have the message queue open when
``mq_unlink()`` is called, removal of the message queue is postponed
until all references to the message queue have been closed.
:param mqName: Name of the message queue
**POSIX Compatibility:** Comparable to the POSIX interface of the same
name.
.. c:function:: int mq_send(mqd_t mqdes, const void *msg, size_t msglen, int prio)
Adds the specified message, ``msg``, to the message queue, ``mqdes``.
The ``msglen`` parameter specifies the length of the message in bytes
pointed to by ``msg``. This length must not exceed the maximum message
length from the ``mq_getattr()``.
2020-07-21 00:18:26 +02:00
If the message queue is not full, ``mq_send()`` will place the ``msg``
in the message queue at the position indicated by the ``prio`` argument.
Messages with higher priority will be inserted before lower priority
messages The value of ``prio`` must not exceed ``MQ_PRIO_MAX``.
If the specified message queue is full and ``O_NONBLOCK`` is not set in
the message queue, then ``mq_send()`` will block until space becomes
available to the queue the message.
If the message queue is full and ``NON_BLOCK`` is set, the message is
not queued and ``ERROR`` is returned.
**NOTE**: ``mq_send()`` may be called from an interrupt handler.
However, it behaves differently when called from the interrupt level:
- It does not check the size of the queue. It will always post the
message, even if there are already too many messages in queue. This is
2020-07-21 00:18:26 +02:00
because the interrupt handler does not have the option of waiting for
the message queue to become non-full.
- It doesn't allocate new memory (because you cannot allocate memory
from an interrupt handler). Instead, there is a pool of pre-allocated
message structures that may be used just for sending messages from
interrupt handlers. The number of such pre-allocated messages is set
by the ``PREALLOC_MQ_IRQ_MSGS`` configuration parameter.
2020-07-21 00:18:26 +02:00
:param mqdes: Message queue descriptor.
:param msg: Message to send.
:param msglen: The length of the message in bytes.
:param prio: The priority of the message.
:return: On success, ``mq_send()`` returns 0 (``OK``); on
error, -1 (``ERROR``) is returned, with ```errno`` <#ErrnoAccess>`__ set
to indicate the error:
- ``EAGAIN``. The queue was empty, and the ``O_NONBLOCK`` flag was set
for the message queue description referred to by ``mqdes``.
- ``EINVAL``. Either ``msg`` or ``mqdes`` is ``NULL`` or the value of
``prio`` is invalid.
- ``EPERM``. Message queue opened not opened for writing.
- ``EMSGSIZE``. ``msglen`` was greater than the ``maxmsgsize``
attribute of the message queue.
- ``EINTR``. The call was interrupted by a signal handler.
**POSIX Compatibility:** Comparable to the POSIX interface of the same
name.
.. c:function:: int mq_timedsend(mqd_t mqdes, const char *msg, size_t msglen, int prio, \
const struct timespec *abstime);
Adds the specified message, ``msg``, to the message queue, ``mqdes``.
The ``msglen`` parameter specifies the length of the message in bytes
pointed to by ``msg``. This length must not exceed the maximum message
length from the ``mq_getattr()``.
2020-07-21 00:18:26 +02:00
If the message queue is not full, ``mq_timedsend()`` will place the
``msg`` in the message queue at the position indicated by the ``prio``
argument. Messages with higher priority will be inserted before lower
priority messages The value of ``prio`` must not exceed ``MQ_PRIO_MAX``.
If the specified message queue is full and ``O_NONBLOCK`` is not set in
the message queue, then ``mq_send()`` will block until space becomes
available to the queue the message or until a timeout occurs.
``mq_timedsend()`` behaves just like ``mq_send()``, except that if the
queue is full and the ``O_NONBLOCK`` flag is not enabled for the message
queue description, then ``abstime`` points to a structure which
specifies a ceiling on the time for which the call will block. This
ceiling is an absolute timeout in seconds and nanoseconds since the
Epoch (midnight on the morning of 1 January 1970).
If the message queue is full, and the timeout has already expired by the
time of the call, ``mq_timedsend()`` returns immediately.
:param mqdes: Message queue descriptor.
:param msg: Message to send.
:param msglen: The length of the message in bytes.
:param prio: The priority of the message.
:return: On success, ``mq_send()`` returns 0 (``OK``); on
error, -1 (``ERROR``) is returned, with ```errno`` <#ErrnoAccess>`__ set
to indicate the error:
- ``EAGAIN``. The queue was empty, and the ``O_NONBLOCK`` flag was set
for the message queue description referred to by ``mqdes``.
- ``EINVAL``. Either ``msg`` or ``mqdes`` is ``NULL`` or the value of
``prio`` is invalid.
- ``EPERM``. Message queue opened not opened for writing.
- ``EMSGSIZE``. ``msglen`` was greater than the ``maxmsgsize``
attribute of the message queue.
- ``EINTR``. The call was interrupted by a signal handler.
**POSIX Compatibility:** Comparable to the POSIX interface of the same
name.
.. c:function:: ssize_t mq_receive(mqd_t mqdes, void *msg, size_t msglen, int *prio)
Receives the oldest of the highest priority messages from the message
queue specified by ``mqdes``. If the size of the buffer in bytes,
``msgLen``, is less than the ``mq_msgsize`` attribute of the message
queue, ``mq_receive()`` will return an error. Otherwise, the selected
message is removed from the queue and copied to ``msg``.
2020-07-21 00:18:26 +02:00
If the message queue is empty and ``O_NONBLOCK`` was not set,
``mq_receive()`` will block until a message is added to the message
queue. If more than one task is waiting to receive a message, only the
task with the highest priority that has waited the longest will be
unblocked.
If the queue is empty and ``O_NONBLOCK`` is set, ``ERROR`` will be
returned.
:param mqdes: Message Queue Descriptor.
:param msg: Buffer to receive the message.
:param msglen: Size of the buffer in bytes.
:param prio: If not NULL, the location to store message priority.
:return: On success, the length of the selected message in bytes is
returned. On failure, -1 (``ERROR``) is returned and the
2020-07-21 00:18:26 +02:00
```errno`` <#ErrnoAccess>`__ is set appropriately:
- ``EAGAIN`` The queue was empty and the ``O_NONBLOCK`` flag was set
for the message queue description referred to by ``mqdes``.
- ``EPERM`` Message queue opened not opened for reading.
- ``EMSGSIZE`` ``msglen`` was less than the ``maxmsgsize`` attribute of
the message queue.
- ``EINTR`` The call was interrupted by a signal handler.
- ``EINVAL`` Invalid ``msg`` or ``mqdes``
**POSIX Compatibility:** Comparable to the POSIX interface of the same
name.
.. c:function:: ssize_t mq_timedreceive(mqd_t mqdes, void *msg, size_t msglen, \
int *prio, const struct timespec *abstime);
Receives the oldest of the highest priority messages from the message
queue specified by ``mqdes``. If the size of the buffer in bytes,
``msgLen``, is less than the ``mq_msgsize`` attribute of the message
queue, ``mq_timedreceive()`` will return an error. Otherwise, the
selected message is removed from the queue and copied to ``msg``.
2020-07-21 00:18:26 +02:00
If the message queue is empty and ``O_NONBLOCK`` was not set,
``mq_timedreceive()`` will block until a message is added to the message
queue (or until a timeout occurs). If more than one task is waiting to
receive a message, only the task with the highest priority that has
waited the longest will be unblocked.
``mq_timedreceive()`` behaves just like ``mq_receive()``, except that if
the queue is empty and the ``O_NONBLOCK`` flag is not enabled for the
message queue description, then ``abstime`` points to a structure which
specifies a ceiling on the time for which the call will block. This
ceiling is an absolute timeout in seconds and nanoseconds since the
Epoch (midnight on the morning of 1 January 1970).
If no message is available, and the timeout has already expired by the
time of the call, ``mq_timedreceive()`` returns immediately.
:param mqdes: Message Queue Descriptor.
:param msg: Buffer to receive the message.
:param msglen: Size of the buffer in bytes.
:param prio: If not NULL, the location to store message priority.
:param abstime: The absolute time to wait until a timeout is declared.
:return: On success, the length of the selected message in bytes is
returned. On failure, -1 (``ERROR``) is returned and the
2020-07-21 00:18:26 +02:00
```errno`` <#ErrnoAccess>`__ is set appropriately:
- ``EAGAIN``: The queue was empty and the ``O_NONBLOCK`` flag was set
for the message queue description referred to by ``mqdes``.
- ``EPERM``: Message queue opened not opened for reading.
- ``EMSGSIZE``: ``msglen`` was less than the ``maxmsgsize`` attribute
of the message queue.
- ``EINTR``: The call was interrupted by a signal handler.
- ``EINVAL``: Invalid ``msg`` or ``mqdes`` or ``abstime``
- ``ETIMEDOUT``: The call timed out before a message could be
transferred.
**POSIX Compatibility:** Comparable to the POSIX interface of the same
name.
.. c:function:: int mq_notify(mqd_t mqdes, FAR const struct sigevent *notification)
If the ``notification`` input parameter is not ``NULL``, this function
connects the task with the message queue such that the specified signal
will be sent to the task whenever the message queue changes from empty
to non-empty. One notification can be attached to a message queue.
2020-07-21 00:18:26 +02:00
If ``notification``; is ``NULL``, the attached notification is detached
(if it was held by the calling task) and the queue is available to
attach another notification.
When the notification is sent to the registered task, its registration
will be removed. The message queue will then be available for
registration.
:param mqdes: Message queue descriptor
:param notification: Real-time signal structure containing:
- ``sigev_notify``. Should be SIGEV_SIGNAL (but actually ignored)
- ``sigev_signo``. The signo to use for the notification
- ``sigev_value``. Value associated with the signal
:return: On success ``mq_notify()`` returns 0; on error, -1
is returned, with ``errno`` set to indicate the error:
- ``EBADF``. The descriptor specified in ``mqdes`` is invalid.
- ``EBUSY``. Another process has already registered to receive
notification for this message queue.
- ``EINVAL``. ``sevp->sigev_notify`` is not one of the permitted
values; or ``sevp->sigev_notify`` is ``SIGEV_SIGNAL`` and
``sevp->sigev_signo`` is not a valid signal number.
- ``ENOMEM``. Insufficient memory.
**POSIX Compatibility:** Comparable to the POSIX interface of the same
name. Differences from the full POSIX implementation include:
- The notification signal will be sent to the registered task even if
another task is waiting for the message queue to become non-empty.
This is inconsistent with the POSIX specification which states, "If a
process has registered for notification of message arrival at a
message queue and some process is blocked in ``mq_receive`` waiting
to receive a message when a message arrives at the queue, the
arriving message will satisfy the appropriate ``mq_receive()`` ...
The resulting behavior is as if the message queue remains empty, and
no notification will be sent."
.. c:function:: int mq_setattr(mqd_t mqdes, const struct mq_attr *mqStat, \
struct mq_attr *oldMqStat);
Sets the attributes associated with the specified message queue "mqdes."
Only the "O_NONBLOCK" bit of the "mq_flags" can be changed.
2020-07-21 00:18:26 +02:00
If ``oldMqStat`` is non-null, mq_setattr() will store the previous message
queue attributes at that location (just as would have been returned by
mq_getattr()).
:param mqdes: Message queue descriptor
:param mqStat: New attributes
:param oldMqState: Old attributes
:return: 0 (``OK``) if attributes are set successfully, otherwise -1
(``ERROR``).
**POSIX Compatibility:** Comparable to the POSIX interface of the same
name.
.. c:function:: int mq_getattr(mqd_t mqdes, struct mq_attr *mqStat)
Gets status information and attributes associated with the specified
message queue.
2020-07-21 00:18:26 +02:00
:param mqdes: Message queue descriptor
:param mqStat: Buffer in which to return attributes. The returned
attributes include:
- ``mq_maxmsg``. Max number of messages in queue.
- ``mq_msgsize``. Max message size.
- ``mq_flags``. Queue flags.
- ``mq_curmsgs``. Number of messages currently in queue.
:return: 0 (``OK``) if attributes provided, -1 (``ERROR``) otherwise.
**POSIX Compatibility:** Comparable to the POSIX interface of the same
name.