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

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
  <refentry id="function.stream-select">
   <refnamediv>
    <refname>stream_select</refname>
    <refpurpose>Runs the equivalent of the select() system call on the given 
     arrays of streams with a timeout specified by tv_sec and tv_usec </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>stream_select</methodname>
      <methodparam><type>resource</type><parameter>&amp;read</parameter></methodparam>
      <methodparam><type>resource</type><parameter>&amp;write</parameter></methodparam>
      <methodparam><type>resource</type><parameter>&amp;except</parameter></methodparam>
      <methodparam><type>int</type><parameter>tv_sec</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>tv_usec</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     The <function>stream_select</function> function accepts arrays of streams and
     waits for them to change status. Its operation is equivalent to that of
     the <function>socket_select</function> function except in that it acts on streams.
    </simpara>
    <simpara>
     The streams listed in the <parameter>read</parameter> array will be watched to
     see if characters become available for reading (more precisely, to see if
     a read will not block - in particular, a stream resource is also ready on
     end-of-file, in which case an <function>fread</function> will return
     a zero length string).
    </simpara>
    <simpara>
     The streams listed in the <parameter>write</parameter> array will be
     watched to see if a write will not block.
    </simpara>
    <simpara>
     The streams listed in the <parameter>except</parameter> array will be
     watched for high priority exceptional ("out-of-band") data arriving.
    </simpara>
    <note>
     <para>
      When <function>stream_select</function> returns, the arrays
      <parameter>read</parameter>, <parameter>write</parameter> and
      <parameter>except</parameter> are modified to indicate which stream
      resource(s) actually changed status.
     </para>
    </note>
    <simpara>
     The <parameter>tv_sec</parameter> and <parameter>tv_usec</parameter>
     together form the <emphasis>timeout</emphasis> parameter,
     <parameter>tv_sec</parameter> specifies the number of seconds while
     <parameter>tv_usec</parameter> the number of microseconds.
     The <emphasis>timeout</emphasis> is an upper bound on the amount of time
     that <function>stream_select</function> will wait before it returns.
     If <parameter>tv_sec</parameter> and <parameter>tv_usec</parameter> are
     both set to <literal>0</literal>, <function>stream_select</function> will
     not wait for data - instead it will return immediately, indicating the
     current status of the streams.
     If <parameter>tv_sec</parameter> is &null; <function>stream_select</function>
     can block indefinitely, returning only when an event on one of the
     watched streams occurs (or if a signal interrupts the system call).
    </simpara>
    <simpara>
     On success <function>stream_select</function> returns the number of
     stream resorces contained in the modified arrays, which may be zero if
     the timeout expires before anything interesting happens. On error &false;
     is returned and a warning raised (this can happen if the system call is
     interrupted by an incoming signal).
    </simpara>

    <warning>
     <para>
      Using a timeout value of <literal>0</literal> allows you to
      instantaneously poll the status of the streams, however, it is NOT a
      good idea to use a <literal>0</literal> timeout value in a loop as it
      will cause your script to consume too much CPU time.
     </para>
     <para>
      It is much better to specify a timeout value of a few seconds, although
      if you need to be checking and running other code concurrently, using a
      timeout value of at least <literal>200000</literal> microseconds will
      help reduce the CPU usage of your script.
     </para>
     <para>
      Remember that the timeout value is the
      maximum time that will elapse; <function>stream_select</function> will
      return as soon as the requested streams are ready for use.
     </para>
    </warning>
    <simpara>
     You do not need to pass every array to
     <function>stream_select</function>. You can leave it out and use an
     empty array or &null; instead. Also do not forget that those arrays are
     passed <emphasis>by reference</emphasis> and will be modified after
     <function>stream_select</function> returns.
    </simpara>
    <para>
     This example checks to see if data has arrived for reading on either
     <parameter>$stream1</parameter> or <parameter>$stream2</parameter>.
     Since the timeout value is <literal>0</literal> it will return
     immediately:
     <programlisting role="php">
<![CDATA[
<?php
/* Prepare the read array */
$read = array($stream1, $stream2);

if (false === ($num_changed_streams = stream_select($read, $write = NULL, $except = NULL, 0))) {
    /* Error handling */
} elseif ($num_changed_streams > 0) {
    /* At least on one of the streams something interesting happened */
}
?>
]]>
     </programlisting>
    </para>
    <note>
     <para>
      Due to a limitation in the current Zend Engine it is not possible to pass a
      constant modifier like &null; directly as a parameter to a function
      which expects this parameter to be passed by reference. Instead use a
      temporary variable or an expression with the leftmost member being a
      temporary variable:
      <programlisting role="php">
<![CDATA[
<?php
stream_select($r, $w, $e = NULL, 0);
?>
]]>
     </programlisting>
     </para>
    </note>
    <note>
     <para>
     Be sure to use the <literal>===</literal> operator when checking for an
     error. Since the <function>stream_select</function> may return 0 the
     comparison with <literal>==</literal> would evaluate to &true;:
     <programlisting role="php">
<![CDATA[
<?php
if (false === stream_select($r, $w, $e = NULL, 0)) {
    echo "stream_select() failed\n";
}
?>
]]>
     </programlisting>
     </para>
    </note>
    <note>
     <para>
      If you read/write to a stream returned in the arrays be aware that
      they do not necessarily read/write the full amount of data you have
      requested. Be prepared to even only be able to read/write a single
      byte.
     </para>
    </note>
    <note>
     <title>Windows 98 Note</title>
     <para>
      <function>stream_select</function> used on a pipe returned from
      <function>proc_open</function> may cause data loss under
      Windows 98.
     </para>
    </note>
    <para>
     See also
     <function>stream_set_blocking</function>
    </para>
   </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:"../../../../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
-->