socket-select.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 14dc7c47365f2b71f6c907a5ba5bccf42534d5a9 Maintainer: nobody Status: ready -->
<refentry xml:id="function.socket-select" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>socket_select</refname>
  <refpurpose>
   Führt einen select()-Systemaufruf auf den gegebenen Socket-Arrays aus,
   wobei ein Zeitlimit bestimmt wird
  </refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>int</type><type>false</type></type><methodname>socket_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>int</type><parameter>microseconds</parameter><initializer>0</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>socket_select</function> nimmt als Parameter Socket-Arrays entgegen
   und wartet, ob diese ihren Status ändern. Diejenigen, die Hintergrundwissen
   über BSD-Sockets haben, werden feststellen, dass diese Socket-Arrays in
   Wirklichkeit die sogenannten Dateideskriptor-Mengen sind. Drei voneinander
   unabhängige Arrays mit Sockets werden überwacht.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>read</parameter></term>
     <listitem>
      <para>
       Die Sockets, die im <parameter>read</parameter>-Array aufgelistet sind,
       werden daraufhin überwacht, ob Zeichen zum Auslesen zur Verfügung
       gestellt werden. (Um genauer zu sein: es wird überwacht, ob ein
       Lesevorgang nicht blockiert würde - ein Socket ist nämlich auch dann
       bereit, wenn er bis zum Dateiende gelesen hat. In diesem Fall gibt
       <function>socket_read</function> einen leeren String zurück.)
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>write</parameter></term>
     <listitem>
      <para>
       Die Sockets, die im <parameter>write</parameter>-Array aufgelistet
       sind, werden daraufhin überwacht, ob ein Schreibvorgang nicht blockiert
       würde.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>except</parameter></term>
     <listitem>
      <para>
       Die Sockets, die im <parameter>except</parameter>-Array aufgelistet
       sind, werden auf Ausnahmen überwacht.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>seconds</parameter></term>
     <listitem>
      <para>
       <parameter>seconds</parameter> und <parameter>microseconds</parameter>
       bilden zusammen den <literal>timeout</literal>-Parameter. Der
       <literal>timeout</literal> ist eine obere Schranke für die Zeit, die
       verstreichen kann, bis <function>socket_select</function> zurückkehrt.
       <parameter>seconds</parameter> kann 0 sein, wodurch
       <function>socket_select</function> sofort zurückkehrt. Dies ist
       nützlich beim Polling. Falls der Parameter <parameter>seconds</parameter>
       &null; ist (kein Timeout), kann <function>socket_select</function>
       unendlich lange blockieren.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>microseconds</parameter></term>
     <listitem>
      <para>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
  <warning>
   <para>
    Beim Beenden werden alle Arrays aktualisiert, und zeigen an, welche
    Sockets ihren Status geändert haben.
   </para>
  </warning>
  <para>
   Sie brauchen nicht jedes Array einzeln an <function>socket_select</function>
   übergeben. Sie können die Arrays auch weglassen und stattdessen leere
   Arrays oder &null; angeben. Vergessen Sie nicht, dass diese Arrays
   <emphasis>per Referenz</emphasis> übergeben werden, und dass sie
   verändert werden, nachdem die Funktion <function>socket_select</function>
   beendet ist.
  </para>
  <note>
   <para>
    Wegen einer Einschränkung in der aktuellen Zend Engine ist es nicht möglich,
    eine Konstante, wie etwa &null;, direkt als Parameter an Funktionen zu
    übergeben, die ihre Argumente als Referenzen erwarten.
    Statt dessen kann eine temporäre Variable oder eine Ausdruck, in dem der am
    weitesten links stehende Teilausdruck eine temporäre Variable ist, verwendet
    werden.
    <example>
     <title>&null; mit <function>socket_select</function> benutzen:</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>
   Bei Erfolg gibt <function>socket_select</function> die Anzahl der
   Sockets zurück, die in den aktualisierten Arrays enthalten sind.
   Falls der Timeout wirksam wird, bevor irgend etwas Interessantes passiert,
   ist das Funktionsergebnis 0. Falls ein Fehler auftritt, wird &false;
   zurückgegeben. Der Fehlercode kann dann mit
   <function>socket_last_error</function> abgefragt werden.
  </para>
  <note>
   <para>
    Wenn ein Fehler aufgespürt werden soll, muss unbedingt der
    Operator <literal>===</literal> benutzt werden. Weil
    <function>socket_select</function> auch 0 zurückgeben kann, wird der
    Vergleich mit <literal>==</literal> sonst zu &true; ausgewertet.
    <example>
     <title>Rückgaben von <function>socket_select</function> verstehen</title>
     <programlisting role="php">
<![CDATA[
<?php
$e = NULL;
if (false === socket_select($r, $w, $e, 0)) {
    echo "socket_select() fehlgeschlagen, Grund: " .
        socket_strerror(socket_last_error()) . "\n";
}
?>
]]>
     </programlisting>
    </example>
   </para>
  </note>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>socket_select</function>-Beispiel</title>
    <programlisting role="php">
<![CDATA[
<?php
/* Das Array read vorbereiten */
$read   = array($socket1, $socket2);
$write  = NULL;
$except = NULL;
$num_changed_sockets = socket_select($read, $write, $except, 0);

if ($num_changed_sockets === false) {
    /* Fehlerbehandlung */
} else if ($num_changed_sockets > 0) {
    /* Mindestens an einem Socket ist etwas Interessantes passiert */
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Seien Sie sich bewusst, dass manche Socket-Implementierungen sehr
    sorgfältig benutzt werden müssen. Ein paar grundsätzliche Regeln:
    <itemizedlist>
     <listitem>
      <simpara>
       Sie sollten immer versuchen, <function>socket_select</function> ohne
       Timeout zu benutzen. Ihr Programm sollte nichts zu tun haben, wenn
       keine Daten verfügbar sind. Code, der von Zeitbegrenzungen abhängig
       ist, ist normalerweise nicht portierbar und schwierig zu debuggen.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Es darf kein Socket in die Arrays eingefügt werden, wenn Sie nicht
       vorhaben, die Ergebnisse nach der Ausführung von
       <function>socket_select</function> zu prüfen und entsprechend darauf zu
       reagieren. Nachdem <function>socket_select</function> beendet ist,
       müssen alle Sockets in allen Socket-Arrays geprüft werden. Jeder
       Socket, der zum Schreiben zur Verfügung steht, muss beschrieben werden
       und aus jedem Socket, der zum Lesen verfügbar ist, muss gelesen werden.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Bei Schreib-/Leseoperationen auf den Sockets in den Arrays muss damit
       gerechnnet werden, dass nicht notwendigerweise alle Daten
       geschrieben/gelesen werden, die angeben wurden. Seien Sie darauf
       vorbereitet, dass Sie möglicherweise nur ein einziges Byte
       schreiben/lesen können.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Fast allen Socket-Implementierungen ist gemeinsam, dass sie nur eine
       einzige Ausnahme in dem Array <parameter>except</parameter> auffangen
       können. Und zwar, wenn bandexterne Daten von einem Socket empfangen
       werden.
      </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:"~/.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
-->