(PHP 4 >= 4.3.0, PHP 5)
stream_select -- select() システムコールと同等の操作を、 ストリームの配列に対して tv_sec と tv_usec で指定されたタイムアウト時間をもって行うstream_select() はストリームの配列を受け取ると、 それらの状態が変化するまで待ちます。機能としては、ストリームに対して 働くという点以外では socket_select() と同一です。
read 配列に列挙されたストリームに対しては、 何らかのデータがそのストリーム内で読み出せる状態にあるかどうか 監視が行われます。 (より正確にいえば、ブロックしないで読み出せる状態かどうか - 特にストリームが EOF に達したかどうか、です。このとき、 fread() は長さ 0 の文字列を返します。)
write 配列に列挙されたストリームに対しては、 ブロックしないで書き込みができるかどうかの監視が行われます。
except 配列に列挙されたストリームに対しては、 例外が発生したかどうかの監視が行われます。
警告 |
関数の終了時には、どのストリームの状態が実際に変化したのかが 分かるよう、これらの配列に変更が加えられます。 |
stream_select() のすべてのパラメータに配列を 渡す必要はありません。代わりに そのままにしておくことも、空の配列を渡すことも、NULL を渡すことも できます。このとき、それらの変数は参照渡しで渡されるため、 stream_select() から戻った時点で変更されている 可能性があることに注意してください。
例:
/* read 配列を用意 */ |
注意: 現在の Zend Engine の実装上の制約により、NULL のような定数を この関数の参照渡しが行われるパラメータに直接指定することはできません。 代わりに一時的な変数を指定するか、一番左の変数が一時的な変数になるような 式を指定してください:
stream_select($r, $w, $e = NULL, 0);
tv_sec と tv_usec は、一体となって、timeout パラメータを表現します。 timeout は、stream_select() の実行から戻るまでの時間の上限です。 tv_sec に 0 を指定すると stream_select() から一瞬で戻ります。 これはポーリングを実現するのに向いています。 tv_sec が NULL (タイムアウトなし) の場合、 stream_select() はブロックしつづけます。
成功した場合 stream_select() は、変更された 配列に何個のストリームリソースが格納されたかを示す数を返します。 もしタイムアウトの時間内に何も規定された事象が起こらなかった場合は 0 になることもあります。エラーの際は FALSE を返します。
注意: エラーかどうかをチェックするには === を使ってください。 stream_select() は 0 を返すことがあるため、その場合 FALSE と == 演算子で比較すると TRUE と評価されてしまうからです:
if (false === stream_select($r, $w, $e = NULL, 0)) {
echo "stream_select() に失敗しました\n";
}
注意: 幾つかのストリームの実装は、注意深く扱わなくてはならないことに 気をつけてください。基本的なルールとしては、次のようなものがあります。
なるべく stream_select() はタイムアウト なしで用いてください。もし有効なデータが到着していなかったとしたら、 あなたのスクリプト内ではどうすることもできないはずだからです。 タイムアウトに依存するコードは概ね移植可能性が低く、 デバッグも大変です。
配列に返されたストリームに対して読み込みまたは書き込み操作を行う際に、 必ずしもあなたの希望しただけデータが読まれたり書かれたりはしないことに 注意してください。たった 1 バイトしか読み出せない場合も、書き込めない 場合もあるのです。
Windows 98 に関する注意: stream_select() を proc_open() に対して行った場合、Windows 98 ではデータが失われる可能性があります。
stream_set_blocking() も参照下さい。