diff --git a/README.rst b/README.rst index 112dbfb8..80a196de 100644 --- a/README.rst +++ b/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 `_ 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. diff --git a/doc/site/configuration.rst b/doc/site/configuration.rst index ee1b421c..fcc3a53e 100644 --- a/doc/site/configuration.rst +++ b/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), @@ -34,7 +38,13 @@ Parameter Descriptions ---------------------- after_fork(server, worker): - This is called by the worker after initialization. + 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 `_. + +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. @@ -53,6 +63,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. @@ -71,6 +84,14 @@ 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 diff --git a/doc/site/faq.rst b/doc/site/faq.rst index 01825c88..0dbccc15 100644 --- a/doc/site/faq.rst +++ b/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? - By designing a web server to only handle fast clients we can greatly simplify - 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. +What are sleepy applications? + Applications that expect long request/response times and/or slow clients. Gunicorn use `Eventlet`_ or `Gevent`_ to manage concurrency. How might I test a proxy configuration? Check out slowloris_ for a script that will generate significant slow @@ -53,4 +50,6 @@ How to name processes? file you can set the process name with the proc_name option. .. _slowloris: http://ha.ckers.org/slowloris/ -.. _setproctitle: http://pypi.python.org/pypi/setproctitle \ No newline at end of file +.. _setproctitle: http://pypi.python.org/pypi/setproctitle +.. _Eventlet: http://eventlet.net +.. _Gevent: http://gevent.org \ No newline at end of file diff --git a/doc/site/index.rst b/doc/site/index.rst index 7e306f11..e80b9fc4 100644 --- a/doc/site/index.rst +++ b/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,13 +22,30 @@ 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 `_) +* Reverse proxy implementation (with `Restkit WSGI proxy `_) +* 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 .. _LICENSE: http://github.com/benoitc/gunicorn/blob/master/LICENSE .. _Gunicorn: http://gunicorn.org .. _Django: http://djangoproject.com -.. _Paster: http://pythonpaste.org/ \ No newline at end of file +.. _Paster: http://pythonpaste.org/ +.. _Eventlet: http://eventlet.net +.. _Gevent: http://gevent.org +.. _Pylons: http://pylonshq.com/ +.. _Turbogears 2: http://turbogears.org/2.0/ \ No newline at end of file diff --git a/doc/site/installation.rst b/doc/site/installation.rst index b9a5f137..88427803 100644 --- a/doc/site/installation.rst +++ b/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 `_ 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 `_ for more information. + Installing on Ubuntu/Debian systems ----------------------------------- @@ -66,3 +79,6 @@ Signing key:: Fingerprint:: 49AEEDFF5CDCD82CEA8AB4DABC981A8115E5EB06 + +.. _Eventlet: http://eventlet.net +.. _Gevent: http://gevent.org \ No newline at end of file diff --git a/doc/site/usage.rst b/doc/site/usage.rst index 88f948a8..2ee17f53 100644 --- a/doc/site/usage.rst +++ b/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 @@ -20,6 +20,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 `_ 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. @@ -99,4 +109,5 @@ And then all you need to do is:: .. _`admin command`: http://docs.djangoproject.com/en/dev/howto/custom-management-commands/ .. _Paste: http://pythonpaste.org/script/ .. _Pylons: http://pylonshq.com/ -.. _Turbogears 2: http://turbogears.org/2.0/ \ No newline at end of file +.. _Turbogears 2: http://turbogears.org/2.0/ +.. _Eventlet: http://eventlet.net \ No newline at end of file diff --git a/gunicorn/async/base.py b/gunicorn/async/base.py index 029a0fb5..284a97f2 100644 --- a/gunicorn/async/base.py +++ b/gunicorn/async/base.py @@ -84,8 +84,7 @@ class KeepaliveWorker(Worker): if not self.debug: raise util.write_error(client, traceback.format_exc()) - break - + break except socket.error, e: if e[0] != errno.EPIPE: self.log.exception("Error processing request.")