mq_timedreceive(), mq_timedreceive_monotonic()

Получить сообщение от очереди сообщений

Прототип:

#include <mqueue.h>
#include <time.h>
        
ssize_t mq_timedreceive( mqd_t mqdes,
                         char *msg_ptr,
                         size_t msg_len,
                         unsigned int *msg_prio,
                         const struct timespec *abs_timeout );
        
ssize_t mq_timedreceive_monotonic( mqd_t mqdes,
                                   char *msg_ptr,
                                   size_t msg_len,
                                   unsigned int *msg_prio,
                                   const struct timespec *abs_timeout );

Аргументы:

mqdes

Дескриптор очереди сообщений, из которой необходимо получить сообщение, возвращённый функцией mq_open().

msg_ptr

Указатель на буфер, в котором функция может хранить данные сообщения.

msg_len

Размер буфера в байтах.

msg_prio

NULL, или указатель на место, где функция может хранить приоритет сообщения, которое она удалила из очереди.

abs_timeout

Указатель на структуру struct timespec, определяющую абсолютное время (время, не относительное к текущему времени) ожидания, прежде чем функция прекратит попытки получить сообщения.

Библиотека:

• libc — для классической реализации.
• libmq — для альтернативной реализации с использованием асинхронных сообщений.

Описание:

Функция mq_timedreceive() получает самое старое из сообщений с наивысшим приоритетом в очереди, заданной mqdes. Функция mq_timedreceive_monotonic() является расширением ЗОСРВ «Нейтрино», она аналогична mq_timedreceive(), но использует CLOCK_MONOTONIC, поэтому на время ожидания не влияют изменения системного времени.

---

Нейтрино поддерживает две реализации очередей сообщений: классическую реализацию и альтернативную, использующую асинхронные сообщения. Для дополнительной информации см. документацию по mq и mqueue.

---

Если при вызове функции mq_timedreceive() задано значение msg_len, отличное от значения mq_msgsize для заданной очереди, то mq_timedreceive() возвращает ошибку, а errno устанавливается в EINVAL.

Если в заданной очереди нет сообщений и O_NONBLOCK не установлен (в параметре oflag при вызове функции mq_open()), то вызов mq_timedreceive() блокируется. Если несколько вызовов mq_timedreceive() заблокированы для одной очереди, они разблокируются в порядке FIFO по мере поступления сообщений.

В классической реализации ( mqueue), вызов фукнции read() с дескриптором mqdes аналогичен вызову функции mq_timedreceive() с параметром msg_prio, равным NULL.

Возвращаемое значение:

Размер сообщения, удалённого из очереди. Если возникла ошибка, функция возвращает -1, код ошибки записывается в errno.

Коды ошибок:

EAGAIN

Был установлен флаг O_NONBLOCK, и в указанной очереди в настоящее время нет сообщений.

EBADF

Параметр mqdes не представляет собой допустимый дескриптор очереди сообщений, открытый для чтения.

EINTR

Вызов прерван сигналом.

EINVAL

Верно одно из следующего:

• Параметр msg_ptr не является допустимым указателем, или msg_len меньше, чем 0, или msg_len меньше размера сообщения, заданного в mq_open(). Размер сообщения по умолчанию составляет 4096 байт.
• Процесс или поток может быть заблокирован, и заданное значение поля параметра abs_timeout, содержащее количество наносекунд, меньше нуля или больше или равно 1000 миллионов.

EMSGSIZE

Заданный msg_len меньше, чем mq_msgsize для данной очереди, или заданный msg_len слишком маленький для сообщения, которое может быть получено.

ETIMEDOUT

Превышено значение времени ожидания.

Примеры:

Укажите абсолютное время ожидания в 1 секунду:

struct   timespec tm;
        
clock_gettime( CLOCK_REALTIME, &tm );
tm.tv_sec += 1;
if ( 0 > mq_timedreceive( fd, buf, 4096, NULL,  &tm ) )
{
    ...
}

Классификация:

mq_timedreceive() — POSIX 1003.1 Message Passing; mq_timedreceive_monotonic() — ЗОСРВ «Нейтрино»

Безопасность использования

Точка остановки потока

Да

Обработчик прерываний

Нет

Обработчик сигналов

Да

В потоке

Да

Тематические ссылки:

mq_close(), mq_open(), mq_receive(), mq_send(), mq_timedsend(), struct timespec

mq, mqueue в Справочнике по Утилитам

Предыдущий раздел: Описание API системной библиотеки