update doc

README.rst

@@ -1,7 +1,7 @@
 About
 -----
 
-gunicorn 'Green Unicorn' is a WSGI HTTP Server for UNIX, fast clients and nothing else.
+gunicorn 'Green Unicorn' is a WSGI HTTP Server for UNIX handle fast clients **and** sleepy application.
 
 This is a port of Unicorn (http://unicorn.bogomips.org/) in Python. Meet us on `#gunicorn irc channel <http://webchat.freenode.net/?channels=gunicorn>`_ on `Freenode`_.
 
@@ -33,6 +33,9 @@ Usage
                             unix:/tmp/gunicorn.sock
       -w WORKERS, --workers=WORKERS
                             Number of workers to spawn. [1]
+      -a ARBITER, --arbiter=ARBITER
+                              gunicorn arbiter entry point or module
+                              [egg:gunicorn#main]
       -p PIDFILE, --pid=PIDFILE
                             set the background PID FILE
       -D, --daemon          Run daemonized in the background.

doc/site/configuration.rst

@@ -10,9 +10,12 @@ Example gunicorn.conf.py
 ------------------------
 ::
 
+    arbiter="egg:gunicorn"  # Or "egg:gunicorn#eventlet" (eventlet or gevent)
+    backlog = 2048
     bind = "127.0.0.1:8000" # Or "unix:/tmp/gunicorn.sock"
     daemon = False          # Whether work in the background
     debug = False           # Some extra logging
+    keepalive = 2           # Time we wait for next connection (in ms)
     logfile = "-"           # Name of the log file
     loglevel = "info"       # The level at which to log
     pidfile = None          # Path to a PID file
@@ -22,6 +25,7 @@ Example gunicorn.conf.py
     group = None            # Change process group to group
     proc_name = None        # Change the process name
     tmp_upload_dir = None   # Set path used to store temporary uploads
+    worker_connections=1000 # Number of connections accepted by a worker
     
     after_fork=lambda server, worker: server.log.info(
             "Worker spawned (pid: %s)" % worker.pid),
@@ -36,6 +40,12 @@ Parameter Descriptions
 after_fork(server, worker):
     This is called by the worker after initialization.
     
+arbiter:
+    The arbiter you want to use.  An arbiter maintain the workers processes alive. It launches or kills them if needed. It also manages application reloading  via SIGHUP/USR2. By default it's `egg:gunicorn#main`. This arbiter only support fast clients connections. If you need to create a sleepy application or handling keepalive set it to `egg:gunicorn#eventlet` to use it with `Eventlet`_ or `egg:gunicorn#gevent` with `Gevent`_. Eventlet arbiter can also be used with `Twisted`_ by using `Eventlet helper <http://bitbucket.org/which_linden/eventlet/src/tip/README.twisted>`_.
+    
+backlog:
+    The backlog parameter defines the maximum length for the queue of pending connections see listen(2) for more information. The default is 2048.
+  
 before_fork(server, worker):
     This is called by the worker just before forking.
   
@@ -54,6 +64,9 @@ debug:
 group:
     The group in which worker processes will be launched.
     
+keepalive:
+    Keepalive timeout. The default is 2 seconds, which should be enough under most conditions for browsers to render the page and start retrieving extra elements for. Increasing this beyond 5 seconds is not recommended. Zero disables keepalive entirely.
+  
 logfile:
     The path to the log file ``-`` (stdout) by default.
   
@@ -72,5 +85,13 @@ umask:
 user:
     The user as which worker processes will by launched.
     
+worker_connections:
+    Number of connections a worker can handle when used with Eventlet or Gevent arbiter. The default is 1000.
+
 tmp_upload_dir:
     Set the path used to store temporarily the body of the request.
+    
+    
+.. _Eventlet: http://eventlet.net
+.. _Gevent: http://gevent.org
+.. _Twisted: http://twistedmatrix.com

doc/site/faq.rst

@@ -16,11 +16,8 @@ What is a fast client?
   forwarded from an upstream proxy. Also see the above FAQ for what a fast
   client is not.
  
-Why only fast clients?
+What are sleepy applications?
-  By designing a web server to only handle fast clients we can greatly simplify
+  Applications that expect long request/response times and/or slow clients. Gunicorn use `Eventlet`_ or `Gevent`_ to manage concurrency.
-  the implementation. Think of it as a separation of concerns where your proxy
-  handles talking to the big bad world of the internet and filters the requests
-  to your application code.
 
 How might I test a proxy configuration?
   Check out slowloris_ for a script that will generate significant slow
@@ -54,3 +51,5 @@ How to name processes?
 
 .. _slowloris: http://ha.ckers.org/slowloris/
 .. _setproctitle: http://pypi.python.org/pypi/setproctitle
+.. _Eventlet: http://eventlet.net
+.. _Gevent: http://gevent.org

doc/site/index.rst

@@ -3,7 +3,7 @@ template: index.html
 Green Unicorn
 =============
 
-Green Unicorn (gunicorn) is an HTTP/WSGI Server for UNIX designed to serve `fast clients`_ and nothing else.
+Green Unicorn (gunicorn) is an HTTP/WSGI Server for UNIX designed to serve `fast clients`_ or `sleepy applications`_.
 
 This is a port of Unicorn_ in Python. Meet us on the `#gunicorn IRC channel`_  on Freenode_.
 
@@ -12,9 +12,9 @@ Gunicorn is released under the MIT License. See the LICENSE_ for more details.
 Features
 --------
 
-- Designed for Unix, WSGI, and fast clients
+- Designed for Unix, WSGI_, fast clients and sleepy applications.
 - Compatible with Python 2.x (>= 2.5)
-- Easy integration with Django_ and Paster_ compatible applications (Pylons, TurboGears 2, ...)
+- Easy integration with Django_ and Paster_ compatible applications (`Pylons`_, `TurboGears 2`_, ...)
 - Process management: Gunicorn_ reaps and restarts workers that die.
 - Load balancing via pre-fork and a shared socket
 - Graceful worker process restarts
@@ -22,9 +22,22 @@ Features
 - Simple and easy Python configuration
 - Decode chunked transfers on-the-fly, allowing upload progress notifications or
   stream-based protocols over HTTP
+- Support for `Eventlet`_ and `Gevent`_ .
 - Post- and pre-fork hooks
 
+Applications
+------------
+
+* Any WSGI_, Django_ and Paster_ compatible applications (`Pylons`_, `TurboGears 2`_, ...)
+* Websockets (see `example <http://github.com/benoitc/gunicorn/blob/master/examples/websocket.py>`_)
+* Reverse proxy implementation (with `Restkit WSGI proxy <http://benoitc.github.com/restkit/wsgi_proxy.html>`_)
+* Comet
+* Long Polling
+* ...
+
+.. _WSGI:  http://www.python.org/dev/peps/pep-0333/
 .. _`fast clients`: faq.html
+.. _`sleepy applications`: faq.html
 .. _Unicorn: http://unicorn.bogomips.org/
 .. _`#gunicorn IRC channel`: http://webchat.freenode.net/?channels=gunicorn
 .. _Freenode: http://freenode.net
@@ -32,3 +45,7 @@ Features
 .. _Gunicorn: http://gunicorn.org
 .. _Django: http://djangoproject.com
 .. _Paster: http://pythonpaste.org/
+.. _Eventlet: http://eventlet.net
+.. _Gevent: http://gevent.org
+.. _Pylons: http://pylonshq.com/
+.. _Turbogears 2: http://turbogears.org/2.0/

doc/site/installation.rst

@@ -49,6 +49,19 @@ If you've cloned the git repository, its highly recommended that you use the ``d
 
   $ python setup.py develop
   
+Installing requirements for sleepy application handling
+-------------------------------------------------------
+
+If you want to handle `sleepy application <faq.html>`_ you will need to install `Eventlet`_ or `Gevent`_.
+
+To install eventlet::
+
+  $ easy_install -U eventlet
+  
+Replace `eventlet` by **gevent** if you want to use `gevent`. 
+
+You can now launch gunicorn with Eventlet or Gevent arbiter, see `usage <usage.html>`_ for more information.
+  
 Installing on Ubuntu/Debian systems
 -----------------------------------
 
@@ -66,3 +79,6 @@ Signing key::
 Fingerprint::
 
   49AEEDFF5CDCD82CEA8AB4DABC981A8115E5EB06
+
+.. _Eventlet: http://eventlet.net
+.. _Gevent: http://gevent.org

doc/site/usage.rst

@@ -11,7 +11,7 @@ Command Line Usage
 WSGI applications
 -----------------
 
-Thirty seconds to launch the `example application`_ packaged with Gunicorn::
+To launch the `example application`_ packaged with Gunicorn::
 
     $ cd /path/to/gunicorn/examples/
     $ gunicorn --workers=2 test:app
@@ -21,6 +21,13 @@ The module ``test:app`` specifies the complete module name and WSGI callable. Yo
     $ cd ~/
     $ gunicorn --workers=12 awesomeproject.wsgi.main:main_app
     
+To launch the `websocket example application <http://github.com/benoitc/gunicorn/blob/master/examples/websocket.py>`_ using `Eventlet`_::
+
+        $ cd /path/to/gunicorn/examples/
+        $ gunicorn -w 12 -a "egg:gunicorn#eventlet" websocket:app
+
+and then go on `http://localhost:8000` to see the result.
+
 Full command line usage
 +++++++++++++++++++++++
 
@@ -36,6 +43,9 @@ Full command line usage
                           unix:/tmp/gunicorn.sock
     -w WORKERS, --workers=WORKERS
                           Number of workers to spawn. [1]
+    -a ARBITER, --arbiter=ARBITER
+                            gunicorn arbiter entry point or module
+                            [egg:gunicorn#main]
     -p PIDFILE, --pid=PIDFILE
                           set the background PID FILE
     -D, --daemon          Run daemonized in the background.
@@ -100,3 +110,4 @@ And then all you need to do is::
 .. _Paste: http://pythonpaste.org/script/
 .. _Pylons: http://pylonshq.com/
 .. _Turbogears 2: http://turbogears.org/2.0/
+.. _Eventlet: http://eventlet.net

gunicorn/async/base.py

@@ -85,7 +85,6 @@ class KeepaliveWorker(Worker):
                         raise
                     util.write_error(client, traceback.format_exc())
                     break
-                
         except socket.error, e:
             if e[0] != errno.EPIPE:
                 self.log.exception("Error processing request.")