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

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.9 $ -->
<!-- EN-Revision: 1.18 Maintainer: yannick Status: ready -->
<!-- Reviewed: yes -->

<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.socket-select">
 <refnamediv>
  <refname>socket_select</refname>
  <refpurpose>Exécute l'appel système select() un tableau de sockets avec une durée d'expiration</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>int</type><methodname>socket_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>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 ressources
   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ées dans le paramètre <parameter>read</parameter>
       seront surveillées en lecture : pour savoir quand elles sont
       disponibles en lecture (plus précisément, si une lecture
       ne va pas bloquer, en particulier, une ressource de 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ées dans <parameter>write</parameter> seront surveillées
       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ées dans <parameter>except</parameter> seront surveillées pour
       leurs exceptions.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>tv_sec</parameter></term>
     <listitem>
      <para>
       Les paramètres <parameter>tv_sec</parameter> et <parameter>tv_usec</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>tv_sec</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>tv_sec</parameter> est &null;
       (pas de timeout), <function>socket_select</function> peut se bloquer indéfiniment.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>tv_usec</parameter></term>
     <listitem>
      <para>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
  <warning>
   <para>
    En sortie de fonction, les tableaux sont modifiées pour indiquer
    quelles 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>
       Une socket ne doit pas être ajoutée à 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>, toutes les sockets dans tous les
       tableaux doivent être vérifiées. Toute socket qui est disponible en
       écriture ou en lecture doit être utilisée pour écrire ou lire.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Si vous écrivez ou lisez avec une socket retournée dans un tableau,
       soyez conscient qu'elle 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 une 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:"../../../../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
-->