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

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.11 $ -->
<!-- EN-Revision: 1.10 Maintainer: yannick Status: ready -->
  <refentry id="function.stream-select">
   <refnamediv>
    <refname>stream_select</refname>
    <refpurpose>Retourne l'équivalent de l'appel système select() sur un tableau
     de flux avec un délai d'expiration spécifié par tv_sec et tv_usec</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>stream_select</methodname>
      <methodparam><type>array</type><parameter>&amp;read</parameter></methodparam>
      <methodparam><type>array</type><parameter>&amp;write</parameter></methodparam>
      <methodparam><type>array</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>
     <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.
    </simpara>
    <simpara>
     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).
    </simpara>
    <simpara>
     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).
    </simpara>
    <simpara>
     Les flux qui sont listés dans le paramètre <parameter>except</parameter>
     seront surveillés pour voir si une exception est levée.
    </simpara>
    <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>
     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.
     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).
    </simpara>
    <simpara>
     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).
    </simpara>

    <warning>
     <para>
      Utiliser comme délai d'expiration une valeur de &zero; vous permet de renvoyer instantanément
      le statut des flux, sinon, ce <emphasis>n'est pas</emphasis> une bonne idée d'utiliser une valeur de &zero; dans une
      boucle, ce qui ferait que votre script consommerait beaucoup trop de temps processeur.
     </para>
     <para>
      Il est préférable de spécifier une valeur de délai d'expiration de quelques secondes. Même
      si vous avez besoin d'exécuter d'autres codes en même temps, l'utilisation d'un délai d'expiration
      de moins de <literal>200000</literal> microsecondes devrait vous aider à réduire le temps
      processeur de votre script.
     </para>
     <para>
      Souvenez-vous que le délai d'expiration représente le temps maximal qui s'écoulera ;
      <function>stream_select</function> se terminera dès que les flux désirés seront prêts à
      être utilisés.
     </para>
    </warning>
    <simpara>
     Vous n'êtes pas obligés de passer tous les tableaux à la fonction
     <function>stream_select</function>. Vous pouvez en omettre certains,
     en utilisant un tableau vide ou la valeur &null;. N'oubliez pas que ces
     tableaux sont passés <emphasis>par référence</emphasis> et qu'ils seront
     modifiés lorsque <function>stream_select</function> s'achèvera.
    </simpara>
    <para>
     Cet exemple surveille si des données arrivent pour être lues dans soit
     <parameter>$stream1</parameter>, soit <parameter>$stream2</parameter>.
     Si le délai d'expiration vaut &zero;, la fonction se terminera immédiatement :
     <programlisting role="php">
<![CDATA[
<?php
/* Preparation du tableau de flux lecture */
$read = array($stream1, $stream2);

if (false === ($num_changed_streams = stream_select($read, $write = NULL, $except = NULL, 0))) {
    /* Gestion d'erreur */
} elseif ($num_changed_streams > 0) {
    /* Au moins un des flux a évolué  */
}
?>
]]>
     </programlisting>
    </para>
    <note>
     <para>
      A 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
stream_select($r, $w, $e = NULL, 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
if (false === stream_select($r, $w, $e = NULL, 0)) {
    echo "stream_select() failed\n";
}
?>
]]>
     </programlisting>
     </para>
    </note>
    <note>
     <para>
      Si vous avez écrit ou lu dans un flux qui retournés 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 préparés à être en
      mesure de lire un seul octet.
     </para>
    </note>
    <note>
     <title>Notes aux utilisateurs de Windows</title>
     <para>
      <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 descripteur de fichier retourné par <function>proc_open</function>
      échoura et retournera &false; sous Windows.
     </para>
    </note>
    <para>
     Voir aussi
     <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
-->