-
Notifications
You must be signed in to change notification settings - Fork 50
/
stream-select.xml
261 lines (255 loc) · 9.39 KB
/
stream-select.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 3fbb2f9686bd6cf7e9e4adb943fe2e6aef3d5d14 Maintainer: seros Status: ready -->
<refentry xml:id="function.stream-select" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_select</refname>
<refpurpose>Ejecuta el equivalente de la llamada al sistema select() sobre las matrices
de flujos dadas con un tiempo de espera especificado por tv_sec y tv_usec </refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>stream_select</methodname>
<methodparam><type>array</type><parameter role="reference">read</parameter></methodparam>
<methodparam><type>array</type><parameter role="reference">write</parameter></methodparam>
<methodparam><type>array</type><parameter role="reference">except</parameter></methodparam>
<methodparam><type>int</type><parameter>tv_sec</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>tv_usec</parameter><initializer>0</initializer></methodparam>
</methodsynopsis>
<para>
La función <function>stream_select</function> acepta matrices de flujos y
espera a que cambien su estado. Su operación es equivalente a la de la función
<function>socket_select</function> excepto que actúa sobre flujos.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>read</parameter></term>
<listitem>
<para>
Los flujos listados en la matriz <parameter>read</parameter> serán observados para
comprobar si los caracteres están disponibles para la lectura (de manera más precisa, para ver si
una lectura no bloqueará - en particular, un recurso de flujo está también listo en
el final de archivo, en cuyo caso una llamada a <function>fread</function> devolverá
una cadena de longitud cero).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>write</parameter></term>
<listitem>
<para>
Los flujos listados en la matriz <parameter>write</parameter> serán
observados para comprobar si una escritura no bloqueará.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>except</parameter></term>
<listitem>
<para>
Los flujos listados en la matriz <parameter>except</parameter> serán
observados para una llegada de información excepcional de alta prioridad ("fuera de banda").
</para>
<note>
<para>
Cuando <function>stream_select</function> devuelve, las matrices
<parameter>read</parameter>, <parameter>write</parameter> y
<parameter>except</parameter> se modifican para indicar qué recursos de flujo
cambiaron de estado actualmente.
</para>
</note>
<simpara>
No se necesita pasar cada matriz a
<function>stream_select</function>. Se pueden omitir y usar una
matriz vacía o &null; en su lugar. No se olvide también de que estas matrices son
pasadas <emphasis>por referencia</emphasis> y serán modificadas después de que
<function>stream_select</function> devuelva.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>tv_sec</parameter></term>
<listitem>
<para>
Los parámetros <parameter>tv_sec</parameter> y <parameter>tv_usec</parameter>
forman juntos el parámetro <emphasis>timeout</emphasis>,
<parameter>tv_sec</parameter> especifica el número de segundos mientras que
<parameter>tv_usec</parameter> especifica el número de microsegundos.
El <parameter>timeout</parameter> (tiemop de espera) es un límite superior de la cantidad
de tiempo que <function>stream_select</function> esperará antes de devolver.
Si <parameter>tv_sec</parameter> y <parameter>tv_usec</parameter> están
establecidos a <literal>0</literal>, <function>stream_select</function>
no esperará información - en su lugar devolverá inmediantamente, indicando el
estado acutal de los flujos.
</para>
<para>
Si <parameter>tv_sec</parameter> es &null; <function>stream_select</function>
puede bloquear indefinidamente, devolviendo sólo cuando ocurra un evento de los
flujos observados (o si una señal interrumpe la llamada al sistema).
</para>
<warning>
<para>
Usar un valor de tiempo de espera de <literal>0</literal> permite
emitir instantáneamente el estado de los flujos, sin embargo, NO es una buena
idea usar un valor de tiempo de espera de <literal>0</literal> en un bucle ya que
causará que el script consuma demasiado tiempo de la CPU.
</para>
<para>
Es mucho mejor especificar un valor de tiempo de espera de unos pocos segundos, aunque
si se necesita comprobar y ejecutar actualmente otro código, usar un
valor de tiempo de espera de al menos <literal>200000</literal> microsegundos
ayudará a reducir el uso de la CPU del script.
</para>
<para>
Recuerde que el valor del tiempo de espera es el tiempo máximo que transcurrirá;
<function>stream_select</function> devolverá tan pronto como los
flujos requeridos estén listos para su uso.
</para>
</warning>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>tv_usec</parameter></term>
<listitem>
<para>
Véase la descripción de <parameter>tv_sec</parameter>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Si se tuvo éxito <function>stream_select</function> devolverá el número de
recursos de flujo contenidos en las matrices modificadas, lo cual puede ser cero si
el tiempo de espera expira antes de que no ocurra nada interesante. Si se produjo un error
devolverá &false; y se lanzará una advertendia (esto puede suceder si la llamada al sistema es
interrumpida por una señal entrante).
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Ejemplo de <function>stream_select</function></title>
<para>
Este ejemplo hace una comprobación para ver si ha llegado información para leer sobre
<parameter>$stream1</parameter> o <parameter>$stream2</parameter>.
Ya que el tiempo de espera es <literal>0</literal> devolverá
inmediatamente:
</para>
<programlisting role="php">
<![CDATA[
<?php
/* Prepararse para leer una matriz */
$read = array($stream1, $stream2);
$write = NULL;
$except = NULL;
if (false === ($num_changed_streams = stream_select($read, $write, $except, 0))) {
/* Manejo de errores */
} elseif ($num_changed_streams > 0) {
/* Sucedió algo interesante en al menos uno de los flujos */
}
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<para>
Debido a las limitaciones en el actual Zend Engine no es posible pasar un
modificador constante como &null; directamente como un parámetro a una función
que espera que este parámetro sea pasado por referencia. En su lugar use una
variable temporal o una expresión con el miembro más a la izquierda como una
variable temporal:
<programlisting role="php">
<![CDATA[
<?php
$e = NULL;
stream_select($r, $w, $e, 0);
?>
]]>
</programlisting>
</para>
</note>
<note>
<para>
Asegúrese de usar el operador <literal>===</literal> cuando se compruebe un
error. Ya que <function>stream_select</function> puede devolver 0, la
comparación con <literal>==</literal> sería evaluada como &true;:
<programlisting role="php">
<![CDATA[
<?php
$e = NULL;
if (false === stream_select($r, $w, $e, 0)) {
echo "Falló stream_select()\n";
}
?>
]]>
</programlisting>
</para>
</note>
<note>
<para>
Si se lee/escribe en un flujo devuelto en las matrices sea consciente de que
éstas no leen/escriben necesariamente la cantidad total de información que se
solicitó. Inluso sólo pueden ser capaces de leer/escribir un sólo
byte.
</para>
</note>
<note>
<para>
Algunos flujos (como <literal>zlib</literal>) no pueden ser seleccionados por esta
función.
</para>
</note>
<note>
<para>
Compatibilidad con Windows: <function>stream_select</function> usado sobre una
tubería devuelta desde <function>proc_open</function> puede causar pérdida de información
bajo Windows 98.
</para>
<para>
El uso de <function>stream_select</function> sobre
descriptores de archivos devueltos por <function>proc_open</function> fallará
y devolverá &false; bajo Windows.
</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
-->