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

Описание

msg_receive(
    SysvMessageQueue $queue,
    int $desired_message_type,
    int &$received_message_type,
    int $max_message_size,
    mixed &$message,
    bool $unserialize = true,
    int $flags = 0,
    int &$error_code = null
): bool

Функция msg_receive() получает первое сообщение из очереди сообщений queue с типом, который указали в параметре desired_message_type.

Список параметров

queue

Очередь сообщений.

desired_message_type

Если для параметра desired_message_type указали значение 0, возвращается первое сообщение из очереди. Если значение параметра desired_message_type больше 0, то возвращается первое сообщение с указанным типом. Если значение параметра desired_message_type меньше 0, то возвращается первое сообщение с типом, которое меньше или равно по модулю значению параметра desired_message_type. Если нет сообщений, которые соответствуют критериям, скрипт ожидает их появления в очереди. Это поведение изменяют через константу MSG_IPC_NOWAIT в параметре flags.

received_message_type

В этом параметре сохраняется тип полученного сообщения.

max_message_size

Максимальный размер принимаемого сообщения задаётся в параметре max_message_size; если сообщение в очереди больше этого размера, то функция завершается ошибкой (если флаг flags не установили так, как рассказывает описание этого параметра).

message

Полученное сообщение сохраняется в параметре message, если не было ошибок при получении.

unserialize

Если для параметра установили значение true, сообщение рассматривается как сериализованое тем же механизмом, что и в модуле сессий. Сообщение десериализуется, а затем возвращается в скрипт. Это помогает легко получать массивы и сложные объекты из других PHP-скриптов, или, если используется WDDX-сериализатор, из любых совместимых с WDDX источников.

Если для параметра unserialize указали значение false, сообщение возвращается в виде бинарно-безопасной строки.

flags

Необязательный параметр flags разрешает передать флаги в низкоуровневый системный вызов msgrcv. По умолчанию его значение 0, но можно указать одно или несколько следующих значений (путём сложения или через операцию побитового ИЛИ).

**Flag values for msg_receive**
`MSG_IPC_NOWAIT`	Если нет сообщений, которые удовлетворяют условиям параметра `desired_message_type`, возвращаться немедленно, а не ждать. Функция завершается ошибкой и возвращает целочисленное значение `MSG_ENOMSG`.
`MSG_EXCEPT`	Установка этого флага в комбинации с положительным значением параметра `desired_message_type`, позволяет получить первое сообщение, тип которого не равен значению `desired_message_type`.
`MSG_NOERROR`	Если размер сообщения превышает значение параметра `max_message_size`, то установка этого флага приводит к усечению сообщения до значения параметра `max_message_size` без сигнализирования об ошибке.

error_code

Если функция завершается аварийно, необязательный параметр error_code будет содержать значение системной переменной errno.

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

Функция возвращает true, если выполнилась успешно, или false, если возникла ошибка.

При успешном завершении, структура данных очереди сообщений обновляется следующим образом: элемент msg_lrpid содержит идентификатор вызвавшего процесса, msg_qnum уменьшается на 1, а msg_rtime устанавливается в соответствии с текущим временем.

Список изменений

Версия	Описание
8.0.0	Параметр `queue` теперь ожидает экземпляр класса SysvMessageQueue; раньше ожидался ресурс (resource).

Смотрите также

msg_remove_queue() - Удаляет очередь сообщений
msg_send() - Отправляет сообщение в очередь сообщений
msg_stat_queue() - Получает информацию из структуры данных очереди сообщений
msg_set_queue() - Устанавливает информацию в структуре данных очереди сообщений