socket_select(): document key preservation, and correct both select pages - #5829
Merged
Conversation
The page already warns that the arrays are modified on exit, but not that an entry that stays keeps the key it came in with, which is what callers need in order to map a ready socket back to whatever it belongs to. stream_select() documents it; php_sock_array_from_fd_set() reinserts each surviving entry under its original key, integer or string, so the two functions agree. Fixes: php#5787
The page said the arrays could be left out. They cannot: the function
takes at least four arguments, an uninteresting one has to be an empty
array or null, and all three empty raises a ValueError. The microseconds
entry was an empty paragraph, and the notes carried a sentence that never
parsed ("If you read/write to a socket returns in the arrays").
Also stream_select() in seealso, since the two functions are each other's
counterpart, and the usual typos: happens.On, zero , causing, Due a
limitation, socket_select return.
The page claimed the two functions operate identically apart from what they act on. They do not. A negative timeout is a ValueError here and a warning plus false there, an invalid element is skipped here and a TypeError there, and microseconds is nullable only here. The larger difference had no mention anywhere: when a stream already has buffered data on the PHP side, select() is never called, and the write and except arrays come back empty without having been looked at. A caller watching for writability silently gets nothing. Also socket_select() in seealso, and the same unparseable sentence about partial reads that the socket_select() page carries.
lacatoire
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
socket_select()already warns that the arrays are modified on exit, but not that an entry that stays keeps the key it came in with. That is what callers need in order to map a ready socket back to whatever it belongs to.php_sock_array_from_fd_set()reinserts each surviving entry under its original key, integer or string. Checked on 8.5.4 with non-contiguous integer keys, string keys and mixed arrays, forreadas well aswrite. No changelog: keys have been preserved since 5.3.0.The second commit fixes what the surrounding twenty lines got wrong. The page said the arrays could be left out; they cannot, the function takes at least four arguments and
ValueErrors when all three are empty. Themicrosecondsentry was an empty paragraph, and the notes carried a sentence that never parsed.The third one is about
stream_select(), which is where this started: its page says its operation is equivalent tosocket_select()apart from what it acts on, and that is not true. A negative timeout is aValueErroron one side and a warning plusfalseon the other, an invalid element is skipped on one side and aTypeErroron the other, andmicrosecondsis nullable only on the stream side. The one worth documenting had no mention anywhere: when a stream already holds buffered data on the PHP side,select()is never called and thewriteandexceptarrays come back empty without having been looked at, so a caller watching for writability silently gets nothing.The two pages now point at each other in seealso. Paragraphs that are touched become
simparawhere the style check asks for it.Fixes: #5787