.. _implementing-servers:

======================
 Implementing servers
======================

.. currentmodule:: gevent.baseserver

There are a few classes to simplify server implementation with gevent.
They all share a similar interface, inherited from :class:`BaseServer`::

  def handle(socket, address):
       print('new connection!')

  server = StreamServer(('127.0.0.1', 1234), handle) # creates a new server
  server.start() # start accepting new connections

At this point, any new connection accepted on ``127.0.0.1:1234`` will result in a new
:class:`gevent.Greenlet` spawned running the *handle* function. To stop a server use :meth:`BaseServer.stop` method.

In case of a :class:`gevent.pywsgi.WSGIServer`, *handle* must be a WSGI application callable.

It is possible to limit the maximum number of concurrent connections,
by passing a :class:`gevent.pool.Pool` instance. In addition, passing
a pool allows the :meth:`BaseServer.stop` method to kill requests that
are in progress::

  pool = Pool(10000) # do not accept more than 10000 connections
  server = StreamServer(('127.0.0.1', 1234), handle, spawn=pool)
  server.serve_forever()


.. tip:: If you don't want to limit concurrency, but you *do* want to
         be able to kill outstanding requests, use a pool created with
         a size of ``None``.


The :meth:`BaseServer.serve_forever` method calls
:meth:`BaseServer.start` and then waits until interrupted or until the
server is stopped.

The :mod:`gevent.pywsgi` module contains an implementation of a :pep:`3333`
:class:`WSGI server <gevent.pywsgi.WSGIServer>`. In addition,
gunicorn_ is a stand-alone server that supports gevent.

.. important::

   The provided server implementations are intended primarily for
   development and testing, or internal usage, and otherwise only
   generally "safe" scenarios. They have not been security audited.
   Expose them to the public Internet at your own risk.

API Reference
=============

- :doc:`api/gevent.baseserver`
- :doc:`api/gevent.server`
- :doc:`api/gevent.pywsgi`


Examples
========

More :doc:`examples <examples/index>` are available:

- :doc:`examples/echoserver` - demonstrates :class:`gevent.server.StreamServer`
- :doc:`examples/wsgiserver` - demonstrates :class:`gevent.pywsgi.WSGIServer <gevent.pywsgi.WSGIServer>`
- :doc:`examples/wsgiserver_ssl` - demonstrates :class:`WSGIServer with ssl <gevent.pywsgi.WSGIServer>`



.. _gunicorn: http://gunicorn.org
