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

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.22 $ -->
<!-- EN-Revision: 1.17 Maintainer: dams 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>
   &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>
    <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 quel flux
        ont actuellement changé de statut.
       </para>
      </note>
      <simpara>
       Vous n'êtes pas obligés de remplir tous les tableaux arguments de
       la fonction <function>stream_select</function>. Vous pouvez les laisser
       et utiliser un tableau vide, ou encore &null;. De plus, n'oubliez
       pas que ces tableaux sont passés par <emphasis>référence</emphasis> 
       et seront modifiés une fois que <function>stream_select</function> 
       s'achève.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>tv_sec</parameter></term>
     <listitem>
      <para>
       Les paramètres <parameter>tv_sec</parameter> et
       <parameter>tv_usec</parameter>
       forment le <emphasis>délai d'expiration</emphasis>,
       <parameter>tv_sec</parameter> spécifie le nombre de secondes
       tandis que <parameter>tv_usec</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>tv_sec</parameter> et 
       <parameter>tv_usec</parameter> sont tous les deux définis
       à &zero;, <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>tv_sec</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>tv_usec</parameter></term>
     <listitem>
      <para>
       Voyez la description de <parameter>tv_sec</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 &zero; 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="examples">
  &reftitle.examples;
   <example>
    <title><function>stream_select</function> Example</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>
  </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>
      Notes aux utilisateurs de Windows : <function>stream_select</function> 
      utilisé sur une pipe retournée par <function>proc_open</function> 
      peut causer la perte de données sous Windows 98.
     </para>
     <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>
    </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:"../../../../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
-->