comment

Signed-off-by: Jake Smith <[email protected]>

system/jlib/jsocket.cpp

@@ -30,7 +30,10 @@
  * 1. All sockets are created in non-blocking state. All implementations should cope with non-blocking, i.e. wait/retry.
  * 2. read/readtms will block until min_size bytes are read or timeout expires (see readtms for more detail).
  * read/readtms can be called with min_size=0, in which case it will return as soon as no more data is available.
- * 3. write will block until all bytes are written (could introduce a write min_size/max_size version if needed)
+ * 3. Historically, SSL calls + non-SSL write/writetms, used to flip blocking state during the call, this was prone to error,
+ * because socket could [legitimately] be written to whilst being read from, e.g. a server could be writing to a client, and
+ * at the same time, be notified of traffic and start reading it. Flipping the blocking state of a socket is inherently unsafe
+ * in many usage patterns.
  *
  * The non-blocking semantics are designed so that the select handlers can read as much data as possible without blocking.
  * e.g. dafilesrv and MP avoid blocking in their select handlers, thus avoiding up other client traffic.