doc-fr/reference/stream/functions/stream-select.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: a123b24db5b3e42841179fea13cd508418fc45c7 Maintainer: yannick Status: ready -->
<!-- Reviewed: yes -->
<refentry xml:id="function.stream-select" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>stream_select</refname>
  <refpurpose>Surveille la modification d'un ou plusieurs flux</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> accepte un tableau de flux et
   attend que l'un d'entre eux change de statut. Cette opération est
   équivalente à ce que fait la fonction <function>socket_select</function>,
   hormis le fait qu'elle travaille sur un flux.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>read</parameter></term>
     <listitem>
      <para>
       Les flux qui sont listés dans le paramètre <parameter>read</parameter>
       seront surveillés en lecture, c'est-à-dire si de nouveaux octets
       sont disponibles en lecture (pour être précis, si une lecture ne
       bloquera pas, ce qui inclut aussi les flux qui sont en fin de 
       fichier, auquel cas un appel à la fonction <function>fread</function>
       retournera une chaîne de taille 0).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>write</parameter></term>
     <listitem>
      <para>
       Les flux qui sont listés dans le paramètre <parameter>write</parameter>
       seront surveillés en écriture (pour être précis, si une écriture ne
       bloquera pas).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>except</parameter></term>
     <listitem>
      <para>
       Les flux qui sont listés dans le paramètre <parameter>except</parameter>
       seront surveillés pour voir si une exception est levée.
      </para>
      <note>
       <para>
        Lorsque <function>stream_select</function> se termine, les tableaux
        <parameter>read</parameter>, <parameter>write</parameter> et
        <parameter>except</parameter> sont modifiés pour indiquer quels flux
        ont actuellement changé de statut.
        Les clés originales du tableau sont préservées.
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>seconds</parameter></term>
     <listitem>
      <para>
       Les paramètres <parameter>seconds</parameter> et
       <parameter>microseconds</parameter>
       forment le <emphasis>délai d'expiration</emphasis>,
       <parameter>seconds</parameter> spécifie le nombre de secondes
       tandis que <parameter>microseconds</parameter>, le nombre de 
       microsecondes. Le paramètre <parameter>timeout</parameter>
       représente la limite supérieure du temps que 
       <function>stream_select</function> doit attendre avant de
       se terminer. Si <parameter>seconds</parameter> et 
       <parameter>microseconds</parameter> sont tous les deux définis
       à <literal>0</literal>, , <function>stream_select</function> n'attendra 
       pas de données - à la place, elle se terminera immédiatement,
       indiquant le statut courant du flux. 
      </para>
      <para>
       Si <parameter>seconds</parameter> vaut &null;, 
       <function>stream_select</function> peut se bloquer indéfiniment,
       se terminant uniquement lorsqu'un événement sur un des flux surveillés
       survient (ou si un signal interrompt l'appel système).
      </para>
      <warning>
       <para>
        Utiliser un valeur de <literal>0</literal> vous permet de 
        tester instantanément le statut des flux, mais il faut savoir
        qu'il n'est pas recommandé d'utiliser <literal>0</literal> 
        dans une boucle, car cela va faire consommer énormément de
        processeur à votre script.
       </para>
       <para>
        Il est bien mieux de spécifier une valeur de quelques secondes, même
        si vous devez surveiller et exécuter différents codes de manière
        simultanée. Par exemple, utiliser une valeur d'au moins 
        <literal>200000</literal> microsecondes, vous réduirez considérablement
        la consommation processeur de votre script.
       </para>
       <para>
        N'oubliez pas que la valeur d'expiration est la durée maximale
        d'attente, si rien ne se passe : <function>stream_select</function> 
        retournera un résultat dès que l'un des flux soumis est prêt à 
        l'utilisation.
       </para>
      </warning>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>microseconds</parameter></term>
     <listitem>
      <para>
       Voyez la description de <parameter>seconds</parameter>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   En cas de succès, <function>stream_select</function> retourne
   le nombre de flux qui ont évolué, ce qui peut être <literal>0</literal>,  si 
   le délai d'expiration a été atteint avant que les flux n'évoluent.
   En cas d'erreur, la fonction retournera &false; et un 
   avertissement sera renvoyé (cela peut apparaître si l'appel
   système est interrompu par un signal entrant).
  </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> est désormais nullable.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>stream_select</function></title>
    <para>
     Cet exemple surveille si des données arrivent pour être
     lues soit dans <parameter>$stream1</parameter>, soit dans
     <parameter>$stream2</parameter>. Si le délai d'expiration
     vaut &zero;, la fonction se termine immédiatement :
    </para>
    <programlisting role="php">
<![CDATA[
<?php
/* Preparation du tableau de flux lecture */
$read   = array($stream1, $stream2);
$write  = NULL;
$except = NULL;
if (false === ($num_changed_streams = stream_select($read, $write, $except, 0))) {
    /* Gestion d'erreur */
} elseif ($num_changed_streams > 0) {
    /* Au moins un des flux a évolué  */
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    À cause d'une limitation du moteur Zend actuel, il n'est pas possible
    de passer la valeur &null; directement comme paramètre d'une fonction
    qui s'attend à des paramètres passés par référence. Au lieu de cela,
    il est recommandé d'utiliser une variable temporaire, ou une expression
    dont le membre de gauche est une variable temporaire. Comme ceci :
    <programlisting role="php">
<![CDATA[
<?php
$e = NULL;
stream_select($r, $w, $e, 0);
?>
]]>
    </programlisting>
   </para>
  </note>
  <note>
   <para>
    Assurez-vous de bien utiliser l'opérateur <literal>===</literal> lorsque vous
    recherchez des erreurs. Comme <function>stream_select</function> peut retourner
    0, une comparaison effectuée à l'aide de <literal>==</literal>
    l'évaluerait à &true; :
    <programlisting role="php">
<![CDATA[
<?php
$e = NULL;
if (false === stream_select($r, $w, $e, 0)) {
    echo "stream_select() failed\n";
}
?>
]]>
    </programlisting>
   </para>
  </note>
  <note>
   <para>
    Si vous avez écrit ou lu dans un flux qui est retourné dans les tableaux
    de flux, soyez bien conscient que ces flux n'ont peut être pas écrit
    ou lu la totalité des données demandées. Soyez en
    mesure de lire un seul octet.
   </para>
  </note>
  <note>
   <para>
    Quelques flux (comme <literal>zlib</literal>) ne peuvent pas être
    sélectionnés par cette fonction.
   </para>
  </note>
  <note>
   <title>Compabilité Windows</title>
   <para>
    Utiliser la fonction <function>stream_select</function>
    sur un pointeur de fichier retourné par <function>proc_open</function>
    échouera et retournera &false; sous Windows.
   </para>
   <para>
    <constant>STDIN</constant> fdepuis une console change son statut dés que
    <emphasis>n'importe</emphasis> quel évenements d'entrées sont disponible,
    mais lire depuis un flux peut toujours être bloquant.
   </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
-->