stream-select.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 3fbb2f9686bd6cf7e9e4adb943fe2e6aef3d5d14 Maintainer: seros Status: ready -->
<refentry xml:id="function.stream-select" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>stream_select</refname>
  <refpurpose>Ejecuta el equivalente de la llamada al sistema select() sobre las matrices
   de flujos dadas con un tiempo de espera especificado por tv_sec y tv_usec </refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>int</type><methodname>stream_select</methodname>
   <methodparam><type>array</type><parameter role="reference">read</parameter></methodparam>
   <methodparam><type>array</type><parameter role="reference">write</parameter></methodparam>
   <methodparam><type>array</type><parameter role="reference">except</parameter></methodparam>
   <methodparam><type>int</type><parameter>tv_sec</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>tv_usec</parameter><initializer>0</initializer></methodparam>
  </methodsynopsis>
  <para>
   La función <function>stream_select</function> acepta matrices de flujos y
   espera a que cambien su estado. Su operación es equivalente a la de la función
   <function>socket_select</function> excepto que actúa sobre flujos.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>read</parameter></term>
     <listitem>
      <para>
       Los flujos listados en la matriz <parameter>read</parameter> serán observados para
       comprobar si los caracteres están disponibles para la lectura (de manera más precisa, para ver si
       una lectura no bloqueará - en particular, un recurso de flujo está también listo en
       el final de archivo, en cuyo caso una llamada a <function>fread</function> devolverá
       una cadena de longitud cero).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>write</parameter></term>
     <listitem>
      <para>
       Los flujos listados en la matriz <parameter>write</parameter> serán
       observados para comprobar si una escritura no bloqueará.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>except</parameter></term>
     <listitem>
      <para>
       Los flujos listados en la matriz <parameter>except</parameter> serán
       observados para una llegada de información excepcional de alta prioridad ("fuera de banda").
      </para>
      <note>
       <para>
        Cuando <function>stream_select</function> devuelve, las matrices
        <parameter>read</parameter>, <parameter>write</parameter> y
        <parameter>except</parameter> se modifican para indicar qué recursos de flujo
        cambiaron de estado actualmente.
       </para>
      </note>
      <simpara>
       No se necesita pasar cada matriz a
       <function>stream_select</function>. Se pueden omitir y usar una
       matriz vacía o &null; en su lugar. No se olvide también de que estas matrices son
       pasadas <emphasis>por referencia</emphasis> y serán modificadas después de que
       <function>stream_select</function> devuelva.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>tv_sec</parameter></term>
     <listitem>
      <para>
       Los parámetros <parameter>tv_sec</parameter> y <parameter>tv_usec</parameter>
       forman juntos el parámetro <emphasis>timeout</emphasis>,
       <parameter>tv_sec</parameter> especifica el número de segundos mientras que
       <parameter>tv_usec</parameter> especifica el número de microsegundos.
       El <parameter>timeout</parameter> (tiemop de espera) es un límite superior de la cantidad
       de tiempo que <function>stream_select</function> esperará antes de devolver.
       Si <parameter>tv_sec</parameter> y <parameter>tv_usec</parameter> están
       establecidos a <literal>0</literal>, <function>stream_select</function>
       no esperará información - en su lugar devolverá inmediantamente, indicando el
       estado acutal de los flujos.
      </para>
      <para>
       Si <parameter>tv_sec</parameter> es &null; <function>stream_select</function>
       puede bloquear indefinidamente, devolviendo sólo cuando ocurra un evento de los
       flujos observados (o si una señal interrumpe la llamada al sistema).
      </para>
      <warning>
       <para>
        Usar un valor de tiempo de espera de <literal>0</literal> permite
        emitir instantáneamente el estado de los flujos, sin embargo, NO es una buena
        idea usar un valor de tiempo de espera de <literal>0</literal> en un bucle ya que
        causará que el script consuma demasiado tiempo de la CPU.
       </para>
       <para>
        Es mucho mejor especificar un valor de tiempo de espera de unos pocos segundos, aunque
        si se necesita comprobar y ejecutar actualmente otro código, usar un
        valor de tiempo de espera de al menos <literal>200000</literal> microsegundos
        ayudará a reducir el uso de la CPU del script.
       </para>
       <para>
        Recuerde que el valor del tiempo de espera es el tiempo máximo que transcurrirá;
        <function>stream_select</function> devolverá tan pronto como los
        flujos requeridos estén listos para su uso.
       </para>
      </warning>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>tv_usec</parameter></term>
     <listitem>
      <para>
       Véase la descripción de <parameter>tv_sec</parameter>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Si se tuvo éxito <function>stream_select</function> devolverá el número de
   recursos de flujo contenidos en las matrices modificadas, lo cual puede ser cero si
   el tiempo de espera expira antes de que no ocurra nada interesante. Si se produjo un error
   devolverá &false; y se lanzará una advertendia (esto puede suceder si la llamada al sistema es
   interrumpida por una señal entrante).
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ejemplo de <function>stream_select</function></title>
    <para>
     Este ejemplo hace una comprobación para ver si ha llegado información para leer sobre
     <parameter>$stream1</parameter> o <parameter>$stream2</parameter>.
     Ya que el tiempo de espera es <literal>0</literal> devolverá
     inmediatamente:
    </para>
    <programlisting role="php">
<![CDATA[
<?php
/* Prepararse para leer una matriz */
$read   = array($stream1, $stream2);
$write  = NULL;
$except = NULL;
if (false === ($num_changed_streams = stream_select($read, $write, $except, 0))) {
    /* Manejo de errores */
} elseif ($num_changed_streams > 0) {
    /* Sucedió algo interesante en al menos uno de los flujos */
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Debido a las limitaciones en el actual Zend Engine no es posible pasar un
    modificador constante como &null; directamente como un parámetro a una función
    que espera que este parámetro sea pasado por referencia. En su lugar use una
    variable temporal o una expresión con el miembro más a la izquierda como una
    variable temporal:
    <programlisting role="php">
<![CDATA[
<?php
$e = NULL;
stream_select($r, $w, $e, 0);
?>
]]>
    </programlisting>
   </para>
  </note>
  <note>
   <para>
    Asegúrese de usar el operador <literal>===</literal> cuando se compruebe un
    error. Ya que <function>stream_select</function> puede devolver 0, la
    comparación con <literal>==</literal> sería evaluada como &true;:
    <programlisting role="php">
<![CDATA[
<?php
$e = NULL;
if (false === stream_select($r, $w, $e, 0)) {
    echo "Falló stream_select()\n";
}
?>
]]>
    </programlisting>
   </para>
  </note>
  <note>
   <para>
    Si se lee/escribe en un flujo devuelto en las matrices sea consciente de que
    éstas no leen/escriben necesariamente la cantidad total de información que se
    solicitó. Inluso sólo pueden ser capaces de leer/escribir un sólo
    byte.
   </para>
  </note>
  <note>
   <para>
    Algunos flujos (como <literal>zlib</literal>) no pueden ser seleccionados por esta
    función.
   </para>
  </note>
  <note>
   <para>
    Compatibilidad con Windows: <function>stream_select</function> usado sobre una
    tubería devuelta desde <function>proc_open</function> puede causar pérdida de información
    bajo Windows 98.
   </para>
   <para>
    El uso de <function>stream_select</function> sobre
    descriptores de archivos devueltos por <function>proc_open</function> fallará
    y devolverá &false; bajo Windows.
   </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
-->