Skip to content

socket_select(): document key preservation, and correct both select pages #5829

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lacatoire merged 3 commits into from
Sep 3, 2026
Merged

socket_select(): document key preservation, and correct both select pages #5829

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0173f33
socket_select(): say that the array keys are preserved
lacatoire Sep 3, 2026
1153284
socket_select(): fix the surrounding page while we are here
lacatoire Sep 3, 2026
8b2a990
stream_select(): it is not equivalent to socket_select()
lacatoire Sep 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 30 additions & 30 deletions reference/sockets/functions/socket-select.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,43 +61,45 @@
<varlistentry>
<term><parameter>seconds</parameter></term>
<listitem>
<para>
<simpara>
The <parameter>seconds</parameter> and <parameter>microseconds</parameter>
together form the <literal>timeout</literal> parameter. The
<literal>timeout</literal> is an upper bound on the amount of time
elapsed before <function>socket_select</function> return.
<parameter>seconds</parameter> may be zero , causing
elapsed before <function>socket_select</function> returns.
<parameter>seconds</parameter> may be zero, causing
<function>socket_select</function> to return immediately. This is useful
for polling. If <parameter>seconds</parameter> is &null; (no timeout),
<function>socket_select</function> can block indefinitely.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>microseconds</parameter></term>
<listitem>
<para>
</para>
<simpara>
See <parameter>seconds</parameter> description.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
<warning>
<para>
<simpara>
On exit, the arrays are modified to indicate which socket
actually changed status.
</para>
The original keys of the &array;s are preserved.
</simpara>
</warning>
<para>
You do not need to pass every array to
<function>socket_select</function>. You can leave it out and use an
empty array or &null; instead. Also do not forget that those arrays are
passed <emphasis>by reference</emphasis> and will be modified after
<simpara>
The three arrays all have to be passed, but an array that is of no
interest can be an empty &array; or &null;; at least one of them must be
a non-empty &array;. They are passed
<emphasis>by reference</emphasis> and are modified once
<function>socket_select</function> returns.
</para>
</simpara>
<note>
<para>
Due a limitation in the current Zend Engine it is not possible to pass a
Due to a limitation in the current Zend Engine it is not possible to pass a
constant modifier like &null; directly as a parameter to a function
which expects this parameter to be passed by reference. Instead use a
temporary variable or an expression with the leftmost member being a
Expand All @@ -119,13 +121,13 @@ socket_select($r, $w, $e, 0);

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
On success <function>socket_select</function> returns the number of
sockets contained in the modified arrays, which may be zero if
the timeout expires before anything interesting happens.On error &false;
the timeout expires before anything interesting happens. On error &false;
is returned. The error code can be retrieved with
<function>socket_last_error</function>.
</para>
</simpara>
<note>
<para>
Be sure to use the <literal>===</literal> operator when checking for an
Expand Down Expand Up @@ -202,10 +204,9 @@ if ($num_changed_sockets === false) {
</listitem>
<listitem>
<simpara>
If you read/write to a socket returns in the arrays be aware that
they do not necessarily read/write the full amount of data you have
requested. Be prepared to even only be able to read/write a single
byte.
When reading from or writing to a socket returned in the arrays, be
aware that the full amount of data requested is not necessarily read
or written. Be prepared for as little as a single byte.
</simpara>
</listitem>
<listitem>
Expand All @@ -222,14 +223,13 @@ if ($num_changed_sockets === false) {

<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>
<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>
<member><function>stream_select</function></member>
</simplelist>
</refsect1>

</refentry>
Expand Down
39 changes: 26 additions & 13 deletions reference/stream/functions/stream-select.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,14 @@
<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>
The <function>stream_select</function> function accepts arrays of streams and
waits for them to change status. Its operation is equivalent to that of
the <function>socket_select</function> function except in that it acts on streams.
</para>
<simpara>
The <function>stream_select</function> function accepts arrays of streams
and waits for them to change status. It is the stream counterpart of
<function>socket_select</function>, but the two do not behave alike in
every respect: they report invalid arguments differently, and
<function>stream_select</function> can return without consulting the
operating system at all, as described in the notes below.
</simpara>
</refsect1>

<refsect1 role="parameters">
Expand Down Expand Up @@ -219,18 +222,27 @@ if (false === stream_select($r, $w, $e, 0)) {
</para>
</note>
<note>
<para>
If you read/write to a stream returned in the arrays be aware that
they do not necessarily read/write the full amount of data you have
requested. Be prepared to even only be able to read/write a single
byte.
</para>
<simpara>
When reading from or writing to a stream returned in the arrays, be aware
that the full amount of data requested is not necessarily read or
written. Be prepared for as little as a single byte.
</simpara>
</note>
<note>
<para>
<simpara>
Some streams (like <literal>zlib</literal>) cannot be selected by this
function.
</para>
</simpara>
</note>
<note>
<simpara>
A stream that already holds buffered data on the PHP side is reported as
ready without the underlying <literal>select()</literal> call being made.
When that happens the <parameter>write</parameter> and
<parameter>except</parameter> arrays are emptied without having been
examined, so a stream that was ready for writing goes unreported and the
return value counts the readable streams only.
</simpara>
</note>
<note>
<title>Windows compatibility</title>
Expand All @@ -250,6 +262,7 @@ if (false === stream_select($r, $w, $e, 0)) {
&reftitle.seealso;
<simplelist>
<member><function>stream_set_blocking</function></member>
<member><function>socket_select</function></member>
</simplelist>
</refsect1>
</refentry>
Expand Down