php-doc-ru/reference/stream/functions/stream-select.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: a123b24db5b3e42841179fea13cd508418fc45c7 Maintainer: mch Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.stream-select" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>stream_select</refname>
  <refpurpose>
   Запускает эквивалент системного вызова select() на массивах
   потоков со временем ожидания в секундах и микросекундах
  </refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>int</type><type>false</type></type><methodname>stream_select</methodname>
   <methodparam><type class="union"><type>array</type><type>null</type></type><parameter role="reference">read</parameter></methodparam>
   <methodparam><type class="union"><type>array</type><type>null</type></type><parameter role="reference">write</parameter></methodparam>
   <methodparam><type class="union"><type>array</type><type>null</type></type><parameter role="reference">except</parameter></methodparam>
   <methodparam><type class="union"><type>int</type><type>null</type></type><parameter>seconds</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>microseconds</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Функция <function>stream_select</function> принимает массивы потоков и ждёт
   изменения их статуса. Функция работает так же, как функции
   <function>socket_select</function>, за исключением того, что она работает с потоками.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>read</parameter></term>
     <listitem>
      <para>
       Потоки массива <parameter>read</parameter> будут отслеживаться,
       чтобы определить, не стали ли символы доступны для чтения (точнее, чтобы понять, не будет ли
       блокироваться чтение — в качестве конкретного примера, ресурс потока также готов для чтения в
       конце файла, но тогда функция <function>fread</function> будет возвращать
       строку нулевой длины).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>write</parameter></term>
     <listitem>
      <para>
       Потоки массива <parameter>write</parameter> будут отслеживаться,
       чтобы определить, не будет ли блокироваться запись.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>except</parameter></term>
     <listitem>
      <para>
       Потоки массива <parameter>except</parameter> будут отслеживаться
       на предмет поступления высокоприоритетных исключительных (внеполосных, или «out-of-band») данных.
      </para>
      <note>
       <para>
        Когда функция <function>stream_select</function> возвращает значение,
        массивы <parameter>read</parameter>, <parameter>write</parameter>
        и <parameter>except</parameter> изменяются, чтобы указать, какие
        ресурсы потоков на самом деле изменили статус.
        Исходные ключи массивов (&array;) сохраняются.
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>seconds</parameter></term>
     <listitem>
      <para>
       Параметры <parameter>seconds</parameter> и <parameter>microseconds</parameter>
       складываются в параметр <emphasis>timeout</emphasis>,
       <parameter>seconds</parameter> указывает количество секунд,
       а <parameter>microseconds</parameter> — количество микросекунд.
       Параметр  <parameter>timeout</parameter> — это верхняя граница времени,
       в течение которого функция <function>stream_select</function> будет ждать,
       прежде чем вернёт результат.
       Функция <function>stream_select</function> не будет ждать данные,
       если обоим параметрам — <parameter>seconds</parameter>
       и <parameter>microseconds</parameter> —
       установлено значение <literal>0</literal>, вместо этого функция вернёт
       результат немедленно, указывая текущий статус потоков.
      </para>
      <para>
       Функция <function>stream_select</function> блокируется на неопределённый срок,
       если значение параметра <parameter>seconds</parameter> равно &null;.
       Функция возвращается только тогда, когда случается событие
       на отслеживаемом потоке, или если сигнал прерывает системный вызов.
      </para>
      <warning>
       <para>
        Разработчик может мгновенно опросить статус потоков,
        если установит значение времени ожидания равное <literal>0</literal>,
        однако, ПЛОХАЯ идея устанавливать значение времени ожидания <literal>0</literal> в цикле,
        поскольку тогда скрипт будет потреблять слишком много процессорного времени.
       </para>
       <para>
        Лучше указать значение времени ожидания в несколько секунд, хотя,
        если нужно проверять и одновременно запускать другой код,
        установка для времени ожидания значения хотя бы в <literal>200000</literal> микросекунд
        поможет снизить нагрузку скрипта на процессор.
       </para>
       <para>
        При работе с функцией помнят, что значение времени ожидания — это максимальное время,
        которое пройдёт; функция <function>stream_select</function> вернёт значение, как только
        запрошенные потоки будут готовы к работе.
       </para>
      </warning>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>microseconds</parameter></term>
     <listitem>
      <para>
       Смотрите описание параметра <parameter>seconds</parameter>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   В случае успешного выполнения функция <function>stream_select</function>
   возвращает количество ресурсов потоков, которые содержится
   в изменённых массивах. Значение будет равно нулю,
   если время ожидания закончилось до изменений.
   При ошибке функция возвращает &false;
   и выдаёт предупреждение — это случится, если системный вызов
   будет прерван входящим сигналом.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.1.0</entry>
      <entry>
       Параметр <parameter>microseconds</parameter> теперь принимает значение &null;.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Пример использования функции <function>stream_select</function></title>
    <para>
     Этот пример проверяет, что получены данные для чтения на потоках
     <parameter>$stream1</parameter> или <parameter>$stream2</parameter>.
     Поскольку значение времени ожидания равно <literal>0</literal>, функция возвратится
     немедленно:
    </para>
    <programlisting role="php">
<![CDATA[
<?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) {
    /* Как минимум на одном из потоков произошли изменения */
}

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Из-за ограничений движка Zend Engine невозможно передать
    модификатор константы, например, значение &null;,
    в качестве параметра функции, которая ожидает, что этот параметр
    передадут по ссылке. Вместо этого объявляют временную переменную
    или записывают выражение с крайним левым членом в качестве временной переменной:
    <programlisting role="php">
<![CDATA[
<?php

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

?>
]]>
   </programlisting>
   </para>
  </note>
  <note>
   <para>
   Ошибку проверяют оператором строгого сравнения <literal>===</literal>.
   Иногда функция <function>stream_select</function> возвращает значение 0,
   и сравнение через оператор <literal>==</literal> вычислится как &true;:
   <programlisting role="php">
<![CDATA[
<?php

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

?>
]]>
   </programlisting>
   </para>
  </note>
  <note>
   <para>
    При чтении или записи в поток, который возвращается в массивах, учитывают,
    что поток читает или записывает не полный объём данных,
    которые запросили. Разработчику лучше быть готовым даже к тому,
    что получится читать или записывать только один байт.
   </para>
  </note>
  <note>
   <para>
    Ряд потоков нельзя выбрать этой функцией, например, поток модуля <literal>zlib</literal>.
   </para>
  </note>
  <note>
   <title>Совместимость с операционной системой Windows</title>
   <para>
    Вызов функции <function>stream_select</function>
    на файловых дескрипторах, которые возвращает функция
    <function>proc_open</function> в системах Windows,
    завершится ошибкой и вернёт &false;.
   </para>
   <para>
    При запуске из консоли константа <constant>STDIN</constant> изменяет статус,
    как только становятся доступны <emphasis>какие угодно</emphasis>
    входные события, но процесс по-прежнему может блокировать чтение из потока.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><function>stream_set_blocking</function></member>
  </simplelist>
 </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->