evict all broadcast support
Libwebsockets is fundamentally singlethreaded... the existence of the
fork and broadcast support, especially in the sample server is
giving the wrong idea about how to use it.
This replaces broadcast in the sample server with
libwebsocket_callback_on_writable_all_protocol(). The whole idea of
'broadcast' is removed.
All of the broadcast proxy stuff is removed: data must now be sent
from the callback only. Doing othherwise is not reliable since the
service loop may close the socket and free the wsi at any time,
invalidating a wsi pointer held by another thread (don't do that!)
Likewise the confirm_legit_wsi api added recently does not help the
other thread case, since if the wsi has been freed dereferencing the
wsi to study if it is legit or not will segfault in that case. So
this is removed too.
The overall effect is to push user code to only operate inside the
protocol callbacks or external poll loops, ie, single thread context.
Signed-off-by: Andy Green <andy.green@linaro.org>
diff --git a/README.coding b/README.coding
index 05bc09f..dfe6a41 100644
--- a/README.coding
+++ b/README.coding
@@ -25,24 +25,46 @@
libwebsockets will adapt accordingly.
-Procedure for sending data from other threads or process contexts
------------------------------------------------------------------
+Libwebsockets is singlethreaded
+-------------------------------
-Libwebsockets is carefully designed to work with no blocking in a single thread.
-In some cases where you will add libwebsockets to something else that uses the
-same single thread approach, you can so a safe implementation by combining the
-poll() loops as described in "External Polling loop support" below.
+Directly performing websocket actions from other threads is not allowed.
+Aside from the internal data being inconsistent in forked() processes,
+the scope of a wsi (struct websocket) can end at any time during service
+with the socket closing and the wsi freed.
-In other cases, you find you have asynchronous events coming from other thread
-or process contexts and there's not much you can do about it. If you just try
-to randomly send, or broadcast using libwebsockets_broadcast() from these other
-places things will blow up either quickly or when the events on the two threads
-interefere with each other. It's not legal to do this.
+Websocket write activities should only take place in the
+"LWS_CALLBACK_SERVER_WRITEABLE" callback as described below.
-For those situations, you can use libwebsockets_broadcast_foreign(). This
-serializes the data you're sending using a private, per-protocol socket, so the
-service thread picks it up when it's ready, and it is serviced from the service
-thread context only.
+Only live connections appear in the user callbacks, so this removes any
+possibility of trying to used closed and freed wsis.
+
+If you need to service other socket or file descriptors as well as the
+websocket ones, you can combine them together with the websocket ones
+in one poll loop, see "External Polling Loop support" below, and
+still do it all in one thread / process context.
+
+
+Only send data when socket writeable
+------------------------------------
+
+You should only send data on a websocket connection from the user callback
+"LWS_CALLBACK_SERVER_WRITEABLE" (or "LWS_CALLBACK_CLIENT_WRITEABLE" for
+clients).
+
+If you want to send something, do not just send it but request a callback
+when the socket is writeable using
+
+ - libwebsocket_callback_on_writable(context, wsi) for a specific wsi, or
+ - libwebsocket_callback_on_writable_all_protocol(protocol) for all connections
+using that protocol to get a callback when next writeable.
+
+Usually you will get called back immediately next time around the service
+loop, but if your peer is slow or temporarily inactive the callback will be
+delayed accordingly. Generating what to write and sending it should be done
+in the ...WRITEABLE callback.
+
+See the test server code for an example of how to do this.
Fragmented messages