<?xml version="1.0" encoding="utf-8"?>

<!-- EN-Revision: a758e79c3bf173203550cb78ef07509cf859b212 Maintainer: lacatoire 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>

retourne 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 détecter l'arrivée de données exceptionnelles ("out-of-band") de haute priorité.

</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> est défini

à <literal>0</literal> et <parameter>microseconds</parameter>

vaut <literal>0</literal> ou &null;,

<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 une valeur de <literal>0</literal> 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 au script.

</para>

<para>

Il est bien mieux de spécifier une valeur de quelques secondes, même

si l'on doit surveiller et exécuter différents codes de manière

simultanée. Par exemple, utiliser une valeur d'au moins

<literal>200000</literal> microsecondes, l'on réduira considérablement

la consommation processeur du script.

</para>

<para>

Il ne faut pas oublier que la valeur d'expiration est la durée maximale

d'attente, si rien ne se passe : <function>stream_select</function>

retourne 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>

Voir 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 retourne &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>

Il faut s'assurer de bien utiliser l'opérateur <literal>===</literal> lorsque l'on

recherche 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 l'on a é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>Compatibilité Windows</title>

<para>

Utiliser la fonction <function>stream_select</function>

sur un pointeur de fichier retourné par <function>proc_open</function>

échoue et retourne &false; sous Windows.

</para>

<para>

<constant>STDIN</constant> depuis une console change son statut dès que

<emphasis>n'importe</emphasis> quels événements d'entrées sont disponibles,

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

-->