doc-fr/reference/sockets/functions/socket-select.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 14dc7c47365f2b71f6c907a5ba5bccf42534d5a9 Maintainer: yannick Status: ready -->
<!-- Reviewed: yes -->
<refentry xml:id="function.socket-select" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>socket_select</refname>
  <refpurpose>Exécute l'appel système select() sur un tableau de sockets avec une durée d'expiration</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>int</type><type>false</type></type><methodname>socket_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>int</type><parameter>microseconds</parameter><initializer>0</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>socket_select</function> accepte un tableau de sockets et
   attend qu'elles changent de statut. Ceux qui sont familiers avec les
   sockets de BSD reconnaîtront dans ces tableaux de sockets les
   jeux de pointeurs de fichiers. Trois tableaux indépendants
   de sockets sont surveillés.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>read</parameter></term>
     <listitem>
      <para>
       Les sockets listés dans le paramètre <parameter>read</parameter>
       seront surveillés en lecture : pour savoir quand ils sont
       disponibles en lecture (plus précisément, si une lecture
       ne va pas bloquer, en particulier, un socket a déjà
       atteint une fin de fichier, auquel cas <function>socket_read</function>
       retournera une chaîne de taille zéro).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>write</parameter></term>
     <listitem>
      <para>
       Les sockets listés dans <parameter>write</parameter> seront surveillés
       en écriture : pour voir si une écriture ne va pas bloquer.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>except</parameter></term>
     <listitem>
      <para>
       Les sockets listés dans <parameter>except</parameter> seront surveillés pour
       leurs exceptions.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>seconds</parameter></term>
     <listitem>
      <para>
       Les paramètres <parameter>seconds</parameter> et <parameter>microseconds</parameter>
       ensembles forment le paramètre <literal>timeout</literal> (durée de vie).
       Le <literal>timeout</literal> est la durée maximale de temps avant que
       <function>socket_select</function> ne se termine.
       <parameter>seconds</parameter> peut être zéro, ce qui fera que
       <function>socket_select</function> retournera immédiatement. C'est très
       pratique pour faire du polling (sondage). Si <parameter>seconds</parameter> est &null;
       (pas de timeout), <function>socket_select</function> peut se bloquer indéfiniment.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>microseconds</parameter></term>
     <listitem>
      <para>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
  <warning>
   <para>
    En sortie de fonction, les tableaux sont modifiées pour indiquer
    quels sockets ont changé d'état.
   </para>
  </warning>
  <para>
   Vous n'avez pas besoin de passer tous les tableaux à
   <function>socket_select</function>. Vous pouvez les omettre, ou
   utiliser un tableau vide, ou encore &null; à la place. N'oubliez pas
   que ces tableaux sont passés par <emphasis>référence</emphasis> et
   seront modifiés par <function>socket_select</function>.
  </para>
  <note>
   <para>
    À cause d'une limitation du moteur Zend actuel, il n'est pas possible
    de passer une constante comme &null; directement comme paramètre à cette
    fonction, qui attend une valeur par référence. À la place, utilisez
    un tableau temporaire ou une expression dont le membre de gauche
    est une variable temporaire :
    <example>
     <title>Passer &null; à <function>socket_select</function></title>
     <programlisting role="php">
<![CDATA[
<?php
$e = NULL;
socket_select($r, $w, $e, 0);
?>
]]>
     </programlisting>
    </example>
   </para>
  </note>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   En cas de succès, <function>socket_select</function> retourne le nombre de
   sockets contenues dans les tableaux modifiés. Ce nombre peut être zéro si
   la durée maximale d'attente a été atteinte. En cas d'erreur, &false;
   est retourné. Le code d'erreur généré peut être obtenu en appelant la
   fonction <function>socket_last_error</function>.
  </para>
  <note>
   <para>
    Assurez-vous bien d'utiliser l'opérateur <literal>===</literal>
    lorsque vous vérifiez les erreurs. Étant donnée que
    <function>socket_select</function> peut retourner 0, la comparaison
    avec &false; via <literal>==</literal> donnerait &true; :
    <example>
     <title>Analyser le résultat de <function>socket_select</function></title>
     <programlisting role="php">
<![CDATA[
<?php
$e = NULL;
if (false === socket_select($r, $w, $e, 0)) {
    echo "socket_select() a échoué. Raison : " .
        socket_strerror(socket_last_error()) . "\n";
}
?>
]]>
     </programlisting>
    </example>
   </para>
  </note>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>socket_select</function></title>
    <programlisting role="php">
<![CDATA[
<?php
/* Prépare le tableau read (socket surveillées en lecture) */
$read   = array($socket1, $socket2);
$write  = NULL;
$except = NULL;
$num_changed_sockets = socket_select($read, $write, $except, 0);

if ($num_changed_sockets === false) {
  /* Gestion des erreurs */
} else if ($num_changed_sockets > 0) {
  /* Au moins une des sockets a été modifiée */
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Méfiez-vous des implémentations de sockets, qui doivent être manipulées avec
    délicatesse. Quelques règles de base :
    <itemizedlist>
     <listitem>
      <simpara>
       Vous devez toujours essayer d'utiliser <function>socket_select</function>
       sans timeout. Votre programme ne devrait avoir rien à faire si
       il n'y a pas de données disponibles. Le code qui dépend d'un
       timeout est généralement peu portable, et difficile à déboguer.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Un socket ne doit pas être ajouté à l'un des tableaux en paramètre,
       si vous ne souhaitez pas vérifier le résultat après l'appel à
       <function>socket_select</function>. Après le retour de
       <function>socket_select</function>, tous les sockets dans tous les
       tableaux doivent être vérifiés. Tout socket qui est disponible en
       écriture ou en lecture doit être utilisé pour écrire ou lire.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Si vous écrivez ou lisez avec un socket retourné dans un tableau,
       soyez conscient qu'il ne pourra pas écrire ou lire toutes les données
       que vous demandez. Soyez prêt à ne pouvoir lire qu'un seul octet.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Il est commun à la plupart des implémentations de socket que la seule
       exception interceptée par les sockets dans le tableau
       <parameter>except</parameter> soit le cas des données hors limites,
       reçues par un socket.
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>socket_read</function></member>
    <member><function>socket_write</function></member>
    <member><function>socket_last_error</function></member>
    <member><function>socket_strerror</function></member>
   </simplelist>
  </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:"~/.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
-->