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

<refentry xml:id="function.socket-select" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>socket_select</refname>

<refpurpose>Ejecuta la llamada al sistema select() sobre un array de sockets con un tiempo de expiración</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> acepta un array de sockets y

espera a que cambien de estado. Quienes estén familiarizados con los

sockets de BSD reconocerán en estos arrays de sockets los juegos de punteros a ficheros. Tres arrays independientes

de sockets son monitorizados.

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>read</parameter></term>

<listitem>

<para>

Los sockets listados en el argumento <parameter>read</parameter>

serán monitorizados en lectura: para saber cuándo están

disponibles para lectura (más precisamente, si una lectura

no va a bloquear, en particular, un socket ya

ha alcanzado un fin de archivo, en cuyo caso <function>socket_read</function>

devolverá una string de tamaño cero).

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>write</parameter></term>

<listitem>

<para>

Los sockets listados en <parameter>write</parameter> serán monitorizados

en escritura: para ver si una escritura no va a bloquear.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>except</parameter></term>

<listitem>

<para>

Los sockets listados en <parameter>except</parameter> serán monitorizados para

sus excepciones.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>seconds</parameter></term>

<listitem>

<para>

Los argumentos <parameter>seconds</parameter> y <parameter>microseconds</parameter>

juntos forman el argumento <literal>timeout</literal> (duración).

El <literal>timeout</literal> es la duración máxima de tiempo antes de que

<function>socket_select</function> termine.

<parameter>seconds</parameter> puede ser cero, lo que hará que

<function>socket_select</function> devuelva inmediatamente. Esto es muy

útil para hacer polling (sondaje). Si <parameter>seconds</parameter> es &null;

(sin timeout), <function>socket_select</function> puede bloquearse indefinidamente.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>microseconds</parameter></term>

<listitem>

<para>

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

<warning>

<para>

Al salir de la función, los arrays son modificados para indicar

qué sockets han cambiado de estado.

</para>

</warning>

<para>

No es necesario pasar todos los arrays a

<function>socket_select</function>. Pueden ser omitidos, o

puede usarse un array vacío, o incluso &null; en su lugar. No olvide

que estos arrays son pasados por <emphasis>referencia</emphasis> y

serán modificados por <function>socket_select</function>.

</para>

<note>

<para>

Debido a una limitación del motor Zend actual, no es posible

pasar una constante como &null; directamente como argumento a esta

función, que espera una referencia. En su lugar, utilice un array temporal o una expresión donde el miembro izquierdo

sea una variable temporal:

<example>

<title>Pasar &null; a <function>socket_select</function></title>

<programlisting role="php">

</programlisting>

</example>

</para>

</note>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

En caso de éxito, <function>socket_select</function> devuelve el número de

sockets contenidas en los arrays modificados. Este número puede ser cero si

se alcanzó el tiempo máximo de espera. En caso de error, &false;

es devuelto. El código de error generado puede ser obtenido llamando a la

función <function>socket_last_error</function>.

</para>

<note>

<para>

Asegúrese de usar el operador <literal>===</literal>

cuando verifique los errores. Dado que

<function>socket_select</function> puede devolver 0, la comparación

con &false; mediante <literal>==</literal> daría &true;:

<example>

<title>Analizar el resultado de <function>socket_select</function></title>

<programlisting role="php">

</programlisting>

</example>

</para>

</note>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Ejemplo con <function>socket_select</function></title>

<programlisting role="php">

</programlisting>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<note>

<para>

Tenga cuidado con las implementaciones de sockets, que deben ser manipuladas con

delicadeza. Algunas reglas básicas:

<itemizedlist>

<listitem>

<simpara>

Siempre debe intentarse usar <function>socket_select</function>

sin timeout. Su programa no debería hacer nada si

no hay datos disponibles. El código que depende de un

timeout generalmente es poco portable y difícil de depurar.

</simpara>

</listitem>

<listitem>

<simpara>

Un socket no debe ser añadido a uno de los arrays de argumentos,

si no se desea verificar el resultado después de la llamada a

<function>socket_select</function>. Después del retorno de

<function>socket_select</function>, todos los sockets en todos los

arrays deben ser verificados. Todo socket que esté disponible en

escritura o lectura debe ser usado para escribir o leer.

</simpara>

</listitem>

<listitem>

<simpara>

Si escribe o lee con un socket devuelto en un array,

tenga en cuenta que no podrá escribir o leer todas las datos

que solicite. Esté preparado para poder leer solo un byte.

</simpara>

</listitem>

<listitem>

<simpara>

Es común a la mayoría de las implementaciones de sockets que la única

excepción interceptada por los sockets en el array

<parameter>except</parameter> sea el caso de datos fuera de límites,

recibidos por un socket.

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