stream_select

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

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

Описание

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() будет ожидать до возвращения. Если параметры seconds и microseconds оба установлены в 0, то функция stream_select() не будет ожидать данных - вместо этого она вернётся немедленно, указывая текущий статус потоков.

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

Внимание

Использование значения времени ожидания 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() не удастся и возвратит false под Windows.

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

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

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