document-external-poll-support.patch
Signed-off-by: Andy Green <andy.green@linaro.org>
diff --git a/README-test-server b/README-test-server
index 1cb8e84..2507a67 100644
--- a/README-test-server
+++ b/README-test-server
@@ -175,9 +175,25 @@
Websocket version supported
---------------------------
-The websocket client code is 04 version, the server supports
-both 00/76 in text mode and 04 dynamically per-connection
-depending on the version of the client / browser.
+The websocket client code is 04 and 05 version, the server
+supports 00/76 in text mode and 04 and 05 dynamically
+per-connection depending on the version of the
+client / browser.
-2011-01-22 Andy Green <andy@warmcat.com>
+
+External Polling Loop support
+-----------------------------
+
+libwebsockets maintains an internal poll() array for all of its
+sockets, but you can instead integrate the sockets into an
+external polling array. That's needed if libwebsockets will
+cooperate with an existing poll array maintained by another
+server.
+
+Four callbacks LWS_CALLBACK_ADD_POLL_FD, LWS_CALLBACK_DEL_POLL_FD,
+LWS_CALLBACK_SET_MODE_POLL_FD and LWS_CALLBACK_CLEAR_MODE_POLL_FD
+appear in the callback for protocol 0 and allow interface code to
+manage socket descriptors in other poll loops.
+
+2011-02-12 Andy Green <andy@warmcat.com>
diff --git a/lib/libwebsockets.h b/lib/libwebsockets.h
index 5a870d7..b8a07c9 100644
--- a/lib/libwebsockets.h
+++ b/lib/libwebsockets.h
@@ -132,6 +132,40 @@
* accept another write packet without blocking. If it already
* was able to take another packet without blocking, you'll get
* this callback at the next call to the service loop function.
+ *
+ * The next four reasons are optional and only need taking care of if you
+ * will be integrating libwebsockets sockets into an external polling
+ * array.
+ *
+ * LWS_CALLBACK_ADD_POLL_FD: libwebsocket deals with its poll() loop
+ * internally, but in the case you are integrating with another
+ * server you will need to have libwebsocket sockets share a
+ * polling array with the other server. This and the other
+ * POLL_FD related callbacks let you put your specialized
+ * poll array interface code in the callback for protocol 0, the
+ * first protocol you support, usually the HTTP protocol in the
+ * serving case. This callback happens when a socket needs to be
+ * added to the polling loop: @user contains the fd, and
+ * @len is the events bitmap (like, POLLIN). If you are using the
+ * internal polling loop (the "service" callback), you can just
+ * ignore these callbacks.
+ *
+ * LWS_CALLBACK_DEL_POLL_FD: This callback happens when a socket descriptor
+ * needs to be removed from an external polling array. @user is
+ * the socket desricptor. If you are using the internal polling
+ * loop, you can just ignore it.
+ *
+ * LWS_CALLBACK_SET_MODE_POLL_FD: This callback happens when libwebsockets
+ * wants to modify the events for the socket descriptor in @user.
+ * The handler should OR @len on to the events member of the pollfd
+ * struct for this socket descriptor. If you are using the
+ * internal polling loop, you can just ignore it.
+ *
+ * LWS_CALLBACK_CLEAR_MODE_POLL_FD: This callback occurs when libwebsockets
+ * wants to modify the events for the socket descriptor in @user.
+ * The handler should AND ~@len on to the events member of the
+ * pollfd struct for this socket descriptor. If you are using the
+ * internal polling loop, you can just ignore it.
*/
extern int callback(struct libwebsocket *wsi,
enum libwebsocket_callback_reasons reason, void *user,