stream-select.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: a123b24db5b3e42841179fea13cd508418fc45c7 Maintainer: hirokawa Status: ready -->
<!-- Credits: mumumu -->
<refentry xml:id="function.stream-select" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>stream_select</refname>
  <refpurpose>select() システムコールと同等の操作を、
   ストリームの配列に対して seconds と microseconds で指定されたタイムアウト時間をもって行う</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> はストリームの配列を受け取ると、
   それらの状態が変化するまで待ちます。機能としては、ストリームに対して
   働くという点以外では <function>socket_select</function> と同一です。
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>read</parameter></term>
     <listitem>
      <para>
       <parameter>read</parameter> 配列に列挙されたストリームに対しては、
       何らかのデータがそのストリーム内で読み出せる状態にあるかどうか
       監視が行われます
       (より正確にいえば、ブロックしないで読み出せる状態かどうか -
       特にストリームが EOF に達したかどうか、です。このとき、
       <function>fread</function> は長さ 0 の文字列を返します)。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>write</parameter></term>
     <listitem>
      <para>
       <parameter>write</parameter> 配列に列挙されたストリームに対しては、
       ブロックしないで書き込みができるかどうかの監視が行われます。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>except</parameter></term>
     <listitem>
      <para>
       <parameter>except</parameter> 配列に列挙されたストリームに対しては、
       重大な例外（"帯域外の"）データが発生したかどうかの監視が行われます。
      </para>
      <note>
       <para>
        <function>stream_select</function> の終了時には、
        どのストリームの状態が実際に変化したのかが分かるよう、
        配列 <parameter>read</parameter>、<parameter>write</parameter> および
        <parameter>except</parameter> に変更が加えられます。
        但し、配列のキーは保存されます。
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>seconds</parameter></term>
     <listitem>
      <para>
       <parameter>seconds</parameter> と <parameter>microseconds</parameter>
       は、一体となって、<emphasis>timeout</emphasis> パラメータを表現します。
       <parameter>seconds</parameter> は秒数を指定し、一方
       <parameter>microseconds</parameter> はマイクロ秒数を指定します。
       <emphasis>timeout</emphasis> は、<function>stream_select</function>
       の実行から戻るまでの時間の上限です。
       <parameter>seconds</parameter> および <parameter>microseconds</parameter>
       の両方に <literal>0</literal> を指定すると
       <function>stream_select</function> はデータを待たずに一瞬で戻ります。
       これは現在のストリームの状態を示します。
      </para>
      <para>
       <parameter>seconds</parameter> が &null; (タイムアウトなし) の場合、
       <function>stream_select</function> はブロックしつづけ、調べている
       ストリームのひとつでイベントが発生する（あるいはシグナルがシステム
       コールを中断する）まで終了しません。
      </para>
      <warning>
       <para>
        タイムアウト値に <literal>0</literal> を指定すると、ストリームの
        状態を即時に取得することが可能です。しかし、ループ内でタイムアウト
        <literal>0</literal> を指定するのは良い考えではありません。
        そうすると大量の CPU 時間を消費してしまいます。
       </para>
       <para>
        タイムアウト値を数秒にするとかなりましになります。しかし、どうしても
        他のコードを同時に実行させながらチェックをする必要がある場合には、
        少なくとも <literal>200000</literal> マイクロ秒以上のタイムアウトを
        設定するようにしましょう。これであなたのスクリプトの CPU 使用量を
        抑えることができます。
       </para>
       <para>
        タイムアウト値は、あくまでも経過時間の最大値であることを覚えておきましょう。
        <function>stream_select</function> は、指定したストリームが使用可能に
        なるとすぐに結果を返します。
       </para>
      </warning>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>microseconds</parameter></term>
     <listitem>
      <para>
       <parameter>seconds</parameter> の説明を参照ください。
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   成功した場合 <function>stream_select</function> は、変更された
   配列に何個のストリームリソースが格納されたかを示す数を返します。
   もしタイムアウトの時間内に何も規定された事象が起こらなかった場合は
   0 になることもあります。エラーの際は &false; を返し、警告を発生させます
   （システムコールが別のシグナルによって中断された場合などに起こりえます）。
  </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> は、nullable になりました。
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>stream_select</function> の例</title>
    <para>
     この例では、<parameter>$stream1</parameter> あるいは
     <parameter>$stream2</parameter> のどちらかに読み込めるデータが
     到達したかどうかを調べます。
     タイムアウトが <literal>0</literal> なので、すぐに結果を返します。
    </para>
    <programlisting role="php">
<![CDATA[
<?php
/* read 配列を用意 */
$read   = array($stream1, $stream2);
$write  = NULL;
$except = NULL;
if (false === ($num_changed_streams = stream_select($read, $write, $except, 0))) {
    /* エラー処理 */
} elseif ($num_changed_streams > 0) {
    /* 少なくとも 1 つのストリームに何らかの事象が起こりました。*/
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    現在の Zend Engine の実装上の制約により、&null; のような定数を
    この関数の参照渡しが行われるパラメータに直接指定することはできません。
    代わりに一時的な変数を指定するか、一番左の変数が一時的な変数になるような
    式を指定してください:
    <programlisting role="php">
<![CDATA[
<?php
$e = NULL;
stream_select($r, $w, $e, 0);
?>
]]>
   </programlisting>
   </para>
  </note>
  <note>
   <para>
   エラーかどうかをチェックするには <literal>===</literal> を使ってください。
   <function>stream_select</function> は 0 を返すことがあるため、その場合
   &false; と <literal>==</literal> 演算子で比較すると &true;
   と評価されてしまうからです:
   <programlisting role="php">
<![CDATA[
<?php
$e = NULL;
if (false === stream_select($r, $w, $e, 0)) {
    echo "stream_select() に失敗しました\n";
}
?>
]]>
   </programlisting>
   </para>
  </note>
  <note>
   <para>
    配列に返されたストリームに対して読み込みまたは書き込み操作を行う際に、
    必ずしもあなたの希望しただけデータが読まれたり書かれたりはしないことに
    注意してください。たった 1 バイトしか読み出せない場合も、書き込めない
    場合もあるのです。
   </para>
  </note>
  <note>
   <para>
    ストリームの中には、(<literal>zlib</literal> などのように)
    この関数で select できないものもあります。
   </para>
  </note>
  <note>
   <title>Windows の互換性</title>
   <para>
    Windows では、<function>proc_open</function> が返すファイル記述子に
    対して <function>stream_select</function> を使用すると
    失敗して &false; を返すことがあります。
   </para>
   <para>
    <emphasis>あらゆる</emphasis> 入力イベントが利用可能になるとすぐに、
    コンソールからの <constant>STDIN</constant> の状態も変化しますが、
    ストリームからの読み出しはブロックされたままかもしれません。
   </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
-->