archived-doc-es/reference/stream/functions/stream-select.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: a123b24db5b3e42841179fea13cd508418fc45c7 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no Maintainer: Marqitos -->
<refentry xml:id="function.stream-select" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>stream_select</refname>
  <refpurpose>Supervisa la modificación de uno o varios flujos</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> acepta un array de flujos y
   espera a que alguno de ellos cambie de estado. Esta operación es
   equivalente a lo que hace la función <function>socket_select</function>,
   salvo que trabaja sobre un flujo.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>read</parameter></term>
     <listitem>
      <para>
       Los flujos que están listados en el parámetro <parameter>read</parameter>
       serán supervisados en lectura, es decir, si hay nuevos bytes
       disponibles para lectura (para ser precisos, si una lectura no
       bloqueará, lo que incluye también flujos que están al final de
       archivo, en cuyo caso una llamada a la función <function>fread</function>
       retornará un string de tamaño 0).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>write</parameter></term>
     <listitem>
      <para>
       Los flujos que están listados en el parámetro <parameter>write</parameter>
       serán supervisados en escritura (para ser precisos, si una escritura no
       bloqueará).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>except</parameter></term>
     <listitem>
      <para>
       Los flujos que están listados en el parámetro <parameter>except</parameter>
       serán supervisados para ver si se lanza una excepción.
      </para>
      <note>
       <para>
        Cuando <function>stream_select</function> termina, los arrays
        <parameter>read</parameter>, <parameter>write</parameter> y
        <parameter>except</parameter> son modificados para indicar qué flujos
        han cambiado de estado actualmente.
        Las claves originales del array se preservan.
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>seconds</parameter></term>
     <listitem>
      <para>
       Los parámetros <parameter>seconds</parameter> y
       <parameter>microseconds</parameter>
       forman el <emphasis>tiempo límite</emphasis>,
       <parameter>seconds</parameter> especifica el número de segundos
       mientras que <parameter>microseconds</parameter>, el número de
       microsegundos. El parámetro <parameter>timeout</parameter>
       representa el límite superior del tiempo que
       <function>stream_select</function> debe esperar antes de
       terminar. Si <parameter>seconds</parameter> y
       <parameter>microseconds</parameter> están ambos definidos
       a <literal>0</literal>, <function>stream_select</function> no esperará
       datos - en su lugar, terminará inmediatamente,
       indicando el estado actual del flujo.
      </para>
      <para>
       Si <parameter>seconds</parameter> vale &null;,
       <function>stream_select</function> puede bloquearse indefinidamente,
       terminando únicamente cuando un evento en alguno de los flujos supervisados
       ocurra (o si una señal interrumpe la llamada al sistema).
      </para>
      <warning>
       <para>
        Utilizar un valor de <literal>0</literal> permite
        probar instantáneamente el estado de los flujos, pero debe saberse
        que no se recomienda utilizar <literal>0</literal>
        en un bucle, ya que esto hará que el script consuma una gran cantidad
        de procesador.
       </para>
       <para>
        Es mucho mejor especificar un valor de algunos segundos, incluso
        si se debe supervisar y ejecutar diferentes códigos de manera
        simultánea. Por ejemplo, utilizar un valor de al menos
        <literal>200000</literal> microsegundos, se reducirá considerablemente
        el consumo de procesador del script.
       </para>
       <para>
        No se debe olvidar que el valor de expiración es la duración máxima
        de espera, si no ocurre nada: <function>stream_select</function>
        retornará un resultado tan pronto como uno de los flujos suministrados esté listo para
        su uso.
       </para>
      </warning>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>microseconds</parameter></term>
     <listitem>
      <para>
       Véase la descripción de <parameter>seconds</parameter>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   En caso de éxito, <function>stream_select</function> retorna
   el número de flujos que han cambiado, lo que puede ser <literal>0</literal>, si
   el tiempo límite fue alcanzado antes de que los flujos cambien.
   En caso de error, la función retornará &false; y un
   aviso será devuelto (esto puede ocurrir si la llamada
   al sistema es interrumpida por una señal entrante).
  </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> ahora es nullable.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ejemplo con <function>stream_select</function></title>
    <para>
     Este ejemplo supervisa si los datos llegan para ser
     leídos ya sea en <parameter>$stream1</parameter> o en
     <parameter>$stream2</parameter>. Si el tiempo límite
     es <literal>0</literal>, la función termina inmediatamente:
    </para>
    <programlisting role="php">
<![CDATA[
<?php
/* Preparación del array de flujos de lectura */
$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) {
    /* Al menos uno de los flujos ha cambiado */
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Debido a una limitación del motor Zend actual, no es posible
    pasar el valor &null; directamente como parámetro de una función
    que espera parámetros pasados por referencia. En su lugar,
    se recomienda utilizar una variable temporal, o una expresión
    cuyo miembro izquierdo sea una variable temporal. Como esto:
    <programlisting role="php">
<![CDATA[
<?php
$e = NULL;
stream_select($r, $w, $e, 0);
?>
]]>
    </programlisting>
   </para>
  </note>
  <note>
   <para>
    Asegúrese de utilizar el operador <literal>===</literal> cuando
    busque errores. Como <function>stream_select</function> puede retornar
    0, una comparación realizada con <literal>==</literal>
    lo evaluaría como &true;:
    <programlisting role="php">
<![CDATA[
<?php
$e = NULL;
if (false === stream_select($r, $w, $e, 0)) {
    echo "stream_select() falló\n";
}
?>
]]>
    </programlisting>
   </para>
  </note>
  <note>
   <para>
    Si ha escrito o leído en un flujo que es retornado en los arrays
    de flujos, sea consciente de que estos flujos pueden no haber escrito
    o leído la totalidad de los datos solicitados. Sea
    capaz de leer un solo byte.
   </para>
  </note>
  <note>
   <para>
    Algunos flujos (como <literal>zlib</literal>) no pueden ser
    seleccionados por esta función.
   </para>
  </note>
  <note>
   <title>Compatibilidad con Windows</title>
   <para>
    Utilizar la función <function>stream_select</function>
    en un puntero de archivo retornado por <function>proc_open</function>
    fallará y retornará &false; en Windows.
   </para>
   <para>
    <constant>STDIN</constant> desde una consola cambia su estado tan pronto como
    <emphasis>cualquier</emphasis> evento de entrada esté disponible,
    pero leer desde un flujo puede seguir siendo bloqueante.
   </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
-->