stream_select

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_select — Запускает эквивалент системного вызова select() на массивах потоков со временем ожидания в секундах и микросекундах

Описание

stream_select(
    ?array &$read,
    ?array &$write,
    ?array &$except,
    ?int $seconds,
    ?int $microseconds = null
): int|false

Функция stream_select() принимает массивы потоков и ждёт изменения их статуса. Функция работает так же, как функции socket_select(), за исключением того, что она работает с потоками.

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

read

Потоки массива read будут отслеживаться, чтобы определить, не стали ли символы доступны для чтения (точнее, чтобы понять, не будет ли блокироваться чтение — в качестве конкретного примера, ресурс потока также готов для чтения в конце файла, но тогда функция fread() будет возвращать строку нулевой длины).

write

Потоки массива write будут отслеживаться, чтобы определить, не будет ли блокироваться запись.

except

Потоки массива except будут отслеживаться на предмет поступления высокоприоритетных исключительных (внеполосных, или «out-of-band») данных.

Замечание:

Когда функция stream_select() возвращает значение, массивы read, write и except изменяются, чтобы указать, какие ресурсы потоков на самом деле изменили статус. Исходные ключи массивов (array) сохраняются.

seconds

Параметры seconds и microseconds складываются в параметр timeout, seconds указывает количество секунд, а microseconds — количество микросекунд. Параметр timeout — это верхняя граница времени, в течение которого функция stream_select() будет ждать, прежде чем вернёт результат. Функция stream_select() не будет ждать данные, если обоим параметрам — seconds и microseconds — установлено значение 0, вместо этого функция вернёт результат немедленно, указывая текущий статус потоков.

Функция stream_select() блокируется на неопределённый срок, если значение параметра seconds равно null. Функция возвращается только тогда, когда случается событие на отслеживаемом потоке, или если сигнал прерывает системный вызов.

Внимание

Разработчик может мгновенно опросить статус потоков, если установит значение времени ожидания равное 0, однако, ПЛОХАЯ идея устанавливать значение времени ожидания 0 в цикле, поскольку тогда скрипт будет потреблять слишком много процессорного времени.

Лучше указать значение времени ожидания в несколько секунд, хотя, если нужно проверять и одновременно запускать другой код, установка для времени ожидания значения хотя бы в 200000 микросекунд поможет снизить нагрузку скрипта на процессор.

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

microseconds

Смотрите описание параметра seconds.

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

В случае успешного выполнения функция stream_select() возвращает количество ресурсов потоков, которые содержится в изменённых массивах. Значение будет равно нулю, если время ожидания закончилось до изменений. При ошибке функция возвращает false и выдаёт предупреждение — это случится, если системный вызов будет прерван входящим сигналом.

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

Версия Описание
8.1.0 Параметр microseconds теперь принимает значение null.

Примеры

Пример #1 Пример использования функции stream_select()

Этот пример проверяет, что получены данные для чтения на потоках $stream1 или $stream2. Поскольку значение времени ожидания равно 0, функция возвратится немедленно:

<?php

/* Подготовить массив для чтения */
$read = array($stream1, $stream2);
$write = NULL;
$except = NULL;

if (false === ($num_changed_streams = stream_select($read, $write, $except, 0))) {
/* Обработка ошибок */
} elseif ($num_changed_streams > 0) {
/* Как минимум на одном из потоков произошли изменения */
}

?>

Примечания

Замечание:

Из-за ограничений движка Zend Engine невозможно передать модификатор константы, например, значение null, в качестве параметра функции, которая ожидает, что этот параметр передадут по ссылке. Вместо этого объявляют временную переменную или записывают выражение с крайним левым членом в качестве временной переменной:

<?php

$e = NULL;
stream_select($r, $w, $e, 0);

?>

Замечание:

Ошибку проверяют оператором строгого сравнения ===. Иногда функция stream_select() возвращает значение 0, и сравнение через оператор == вычислится как true:

<?php

$e = NULL;
if (false === stream_select($r, $w, $e, 0)) {
echo "Произошла ошибка при вызове функции stream_select()\n";
}

?>

Замечание:

При чтении или записи в поток, который возвращается в массивах, учитывают, что поток читает или записывает не полный объём данных, которые запросили. Разработчику лучше быть готовым даже к тому, что получится читать или записывать только один байт.

Замечание:

Ряд потоков нельзя выбрать этой функцией, например, поток модуля zlib.

Замечание: Совместимость с операционной системой Windows

Вызов функции stream_select() на файловых дескрипторах, которые возвращает функция proc_open() в системах Windows, завершится ошибкой и вернёт false.

При запуске из консоли константа STDIN изменяет статус, как только становятся доступны какие угодно входные события, но процесс по-прежнему может блокировать чтение из потока.

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

  • stream_set_blocking() - Устанавливает блокирующий или неблокирующий режим для потока