From b59cefcfdb42e13646b4f1bee50e483935b8e57c Mon Sep 17 00:00:00 2001 From: Miguel Grinberg Date: Wed, 19 Aug 2015 22:46:21 -0700 Subject: [PATCH] Added docs on websocket support with gevent --- docs/index.rst | 28 +++++++++++++++++++++++----- setup.py | 3 +-- 2 files changed, 24 insertions(+), 7 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index c9c42e6..9254da6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -248,29 +248,44 @@ Gevent ~~~~~~ `Gevent `_ is another asynchronous framework based on -coroutines, very similar to eventlet. Only the long-polling transport is -currently available when using gevent. +coroutines, very similar to eventlet. An Socket.IO server deployed with +gevent has access to the long-polling transport. If project +`gevent-websocket `_ is +installed, the WebSocket transport is also available. Instances of class ``socketio.Server`` will automatically use gevent for asynchronous operations if the library is installed and eventlet is not installed. To request gevent to be selected explicitly, the ``async_mode`` option can be given in the constructor:: - eio = socketio.Server(async_mode='gevent') + sio = socketio.Server(async_mode='gevent') A server configured for gevent is deployed as a regular WSGI application, using the provided ``socketio.Middleware``:: - app = socketio.Middleware(eio) + app = socketio.Middleware(sio) from gevent import pywsgi pywsgi.WSGIServer(('', 8000), app).serve_forever() -An alternative to running the eventlet WSGI server as above is to use +If the WebSocket transport is installed, then the server must be started as +follows:: + + from gevent import pywsgi + from geventwebsocket.handler import WebSocketHandler + app = socketio.Middleware(sio) + pywsgi.WSGIServer(('', 8000), app, + handler_class=WebSocketHandler).serve_forever() + +An alternative to running the gevent WSGI server as above is to use `gunicorn `_, a fully featured pure Python web server. The command to launch the application under gunicorn is shown below:: $ gunicorn -k gevent -w 1 module:app +Or to include WebSocket:: + + $ gunicorn -k geventwebsocket.gunicorn.workers.GeventWebSocketWorker -w 1 module: app + Same as with eventlet, due to limitations in its load balancing algorithm, gunicorn can only be used with one worker process, so the ``-w 1`` option is required. Note that a single eventlet worker can handle a large number of @@ -316,6 +331,9 @@ can handle multiple concurrent requests using threads, since a client can have up to two outstanding requests at any given time. The Werkzeug server is single-threaded by default, so the ``threaded=True`` option is required. +Note that servers that use worker processes instead of threads, such as +gunicorn, do not support a Socket.IO server configured in threading mode. + Multi-process deployments ~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/setup.py b/setup.py index 6ea043c..35d37ee 100755 --- a/setup.py +++ b/setup.py @@ -25,8 +25,7 @@ setup( platforms='any', install_requires=[ 'six>=1.9.0', - 'eventlet>=0.17.4', - 'python-engineio>=0.5.0' + 'python-engineio>=0.6.0' ], tests_require=[ 'mock',