manager doc

Lawouach · Lawouach · commit 0af1f140fa76 · 2013-02-08T23:28:22.000+01:00
diff --git a/docs/clienttutorial.rst b/docs/clienttutorial.rst
@@ -42,12 +42,15 @@ An example is better than any word so let's have a look at a basic client:
 
 This example demonstrates how to implement a client, here based on a thread-model, that is able to send and receive messages from a connected endpoint at ws://localhost:9000/.
 
-In this snippet, when the handshake is successful, the :func:`opened() <ws4py.websocket.WebSocket.opened>` method is called and within this method we immediatly send to the server a bunch of messages. First we demonstrate how you can use a generator to do so, then we simply send strings.
+In this snippet, when the handshake is successful, the :meth:`opened() <ws4py.websocket.WebSocket.opened>` method is called and within this method we immediatly send to the server a bunch of messages. First we demonstrate how you can use a generator to do so, then we simply send strings.
 
 Assuming the server echoes messages as they arrive, the :func:`received_message(message) <ws4py.websocket.WebSocket.received_message>` method will print out the messages returned by the server and simply closes the connection once it receives the last sent messages , which length is 175.
 
 Finally the :func:`closed(code, reason=None) <ws4py.websocket.WebSocket.closed>` method is called with the code and reason given by the server.
 
+.. seealso::
+   :ref:`manager`.
+
 Tornado
 -------
 
diff --git a/docs/managertutorial.rst b/docs/managertutorial.rst
@@ -0,0 +1,35 @@
+.. _manager:
+
+Managing a pool of WebSockets
+=============================
+
+ws4py provides a :class:`ws4py.manager.WebSocketManager` class that takes care of 
+:class:`ws4py.websocket.WebSocket` instances once they the HTTP upgrade handshake
+has been performed.
+
+The manager is not compulsory but makes it simpler to track and let them run
+in your application's process.
+
+When you :meth:`add(websocket) <ws4py.manager.WebSocketManager.add>` a 
+websocket to the manager, the file-descriptor is registered with the 
+manager's poller and the :meth:`opened() <ws4py.websocket.WebSocket.opened>` 
+method on is called.
+
+Polling
+-------
+
+The manager uses a polling mechanism to dispatch on socket incoming events.
+Two pollers are implemented, one using the traditionnal :py:mod:`select` 
+and another one based on `select.epoll <http://docs.python.org/2.7/library/select.html#epoll-objects>`_ 
+which is used only if available on the system.
+
+The polling is executed in its own thread, it keeps looping until
+the manager :meth:`stop() <ws4py.websocket.WebSocket.stop>` method.
+
+On every loop, the poller is called to poll for all registered file-descriptors.
+If any one of them is ready, we retrieve the websocket using that descriptor
+and, if the websocket is not yet terminated, we call its `once` method
+so that the incoming bytes are processed.
+
+If the processing fails in anyway, the manager terminates the websocket and
+remove it from itself. 
