array ( 0 => 'index.php', 1 => 'PHP Manual', ), 'head' => array ( 0 => 'UTF-8', 1 => 'fr', ), 'this' => array ( 0 => 'function.stream-select.php', 1 => 'stream_select', 2 => 'Surveille la modification d\'un ou plusieurs flux', ), 'up' => array ( 0 => 'ref.stream.php', 1 => 'Fonctions sur les flux', ), 'prev' => array ( 0 => 'function.stream-resolve-include-path.php', 1 => 'stream_resolve_include_path', ), 'next' => array ( 0 => 'function.stream-set-blocking.php', 1 => 'stream_set_blocking', ), 'alternatives' => array ( ), 'source' => array ( 'lang' => 'fr', 'path' => 'reference/stream/functions/stream-select.xml', ), 'history' => array ( ), ); $setup["toc"] = $TOC; $setup["toc_deprecated"] = $TOC_DEPRECATED; $setup["parents"] = $PARENTS; manual_setup($setup); contributors($setup); ?>

stream_select

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_select — Surveille la modification d'un ou plusieurs flux

Description

stream_select(
    ?array &$read,
    ?array &$write,
    ?array &$except,
    ?int $seconds,
    ?int $microseconds = null
): int|false

stream_select() 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 socket_select(), hormis le fait qu'elle travaille sur un flux.

Liste de paramètres

read

Les flux qui sont listés dans le paramètre read 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 fread() retourne une chaîne de taille 0).

write

Les flux qui sont listés dans le paramètre write seront surveillés en écriture (pour être précis, si une écriture ne bloquera pas).

except

Les flux qui sont listés dans le paramètre except seront surveillés pour détecter l'arrivée de données exceptionnelles ("out-of-band") de haute priorité.

Note:

Lorsque stream_select() se termine, les tableaux read, write et except sont modifiés pour indiquer quels flux ont actuellement changé de statut. Les clés originales du tableau sont préservées.

seconds

Les paramètres seconds et microseconds forment le délai d'expiration, seconds spécifie le nombre de secondes tandis que microseconds, le nombre de microsecondes. Le paramètre timeout représente la limite supérieure du temps que stream_select() doit attendre avant de se terminer. Si seconds est défini à 0 et microseconds vaut 0 ou null, stream_select() n'attendra pas de données - à la place, elle se terminera immédiatement, indiquant le statut courant du flux.

Si seconds vaut null, stream_select() 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).

Avertissement

Utiliser une valeur de 0 permet de tester instantanément le statut des flux, mais il faut savoir qu'il n'est pas recommandé d'utiliser 0 dans une boucle, car cela va faire consommer énormément de processeur au script.

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 200000 microsecondes, l'on réduira considérablement la consommation processeur du script.

Il ne faut pas oublier que la valeur d'expiration est la durée maximale d'attente, si rien ne se passe : stream_select() retourne un résultat dès que l'un des flux soumis est prêt à l'utilisation.

microseconds

Voir la description de seconds.

Valeurs de retour

En cas de succès, stream_select() retourne le nombre de flux qui ont évolué, ce qui peut être 0, 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).

Historique

Version Description
8.1.0 microseconds est désormais nullable.

Exemples

Exemple #1 Exemple avec stream_select()

Cet exemple surveille si des données arrivent pour être lues soit dans $stream1, soit dans $stream2. Si le délai d'expiration vaut 0, la fonction se termine immédiatement :

<?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é */
}
?>

Notes

Note:

À 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 :

<?php
$e = NULL;
stream_select($r, $w, $e, 0);
?>

Note:

Il faut s'assurer de bien utiliser l'opérateur === lorsque l'on recherche des erreurs. Comme stream_select() peut retourner 0, une comparaison effectuée à l'aide de == l'évaluerait à true :

<?php
$e = NULL;
if (false === stream_select($r, $w, $e, 0)) {
echo "stream_select() failed\n";
}
?>

Note:

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.

Note:

Quelques flux (comme zlib) ne peuvent pas être sélectionnés par cette fonction.

Note: Compatibilité Windows

Utiliser la fonction stream_select() sur un pointeur de fichier retourné par proc_open() échoue et retourne false sous Windows.

STDIN depuis une console change son statut dès que n'importe quels événements d'entrées sont disponibles, mais lire depuis un flux peut toujours être bloquant.

Voir aussi