path: root/README

asyncio event loop implemented on top of eventlet.

* Trollius project: http://trollius.readthedocs.org/
* aiogreen at PyPI: https://pypi.python.org/pypi/aiogreen


Usage
=====

Use aiogreen with asyncio
-------------------------

aiogreen implements the asyncio API, see asyncio documentation:
https://docs.python.org/dev/library/asyncio.html

To use aiogreen with asyncio, set the event loop policy before using an event
loop, example::

    import aiogreen
    import asyncio

    asyncio.set_event_loop_policy(aiogreen.EventLoopPolicy())
    # ....

Adding this code should be enough to try examples of the asyncio documentation.

Hello World::

    import aiogreen
    import asyncio

    def hello_world():
        print("Hello World")
        loop.stop()

    asyncio.set_event_loop_policy(aiogreen.EventLoopPolicy())
    loop = asyncio.get_event_loop()
    loop.call_soon(hello_world)
    loop.run_forever()
    loop.close()


Use aiogreen with trollius
-------------------------

To support Python 2, you can use Trollius which uses ``yield`` instead
of ``yield from`` for coroutines:
http://trollius.readthedocs.org/

To use aiogreen with trollius, set the event loop policy before using an event
loop, example::

    import aiogreen
    import trollius

    trollius.set_event_loop_policy(aiogreen.EventLoopPolicy())
    # ....

Hello World::

    import aiogreen
    import trollius as asyncio

    def hello_world():
        print("Hello World")
        loop.stop()

    asyncio.set_event_loop_policy(aiogreen.EventLoopPolicy())
    loop = asyncio.get_event_loop()
    loop.call_soon(hello_world)
    loop.run_forever()
    loop.close()


Installation
============

Requirements:

- eventlet 0.14 or newer
- asyncio or trollius:

  * Python 3.4 and newer: asyncio is now part of the stdlib
  * Python 3.3: need Tulip 0.4.1 or newer (pip install asyncio),
    but Tulip 3.4.1 or newer is recommended
  * Python 2.6-3.2: need Trollius 0.3 or newer (pip install trollius),
    but Trollius 1.0 or newer is recommended

Type::

    pip install aiogreen

or::

    python setup.py install


Run tests
=========

Run tests with tox
------------------

The `tox project <https://testrun.org/tox/latest/>`_ can be used to build a
virtual environment with all runtime and test dependencies and run tests
against different Python versions (2.6, 2.7, 3.2, 3.3).

For example, to run tests with Python 2.7, just type::

    tox -e py27

To run tests against other Python versions:

* ``py26``: Python 2.6
* ``py27``: Python 2.7
* ``py27_patch``: Python 2.7 with eventlet monkey patching
* ``py32``: Python 3.2
* ``py33``: Python 3.3
* ``py34``: Python 3.4

Run tests manually
------------------

Run the following command from the directory of the aiogreen project:

    python runtests.py -r


Changelog
=========

Version 0.2 (development version)
---------------------------------

The core of the event loop was rewritten to fits better in asyncio and
eventlet. aiogreen now reuses more code from asyncio/trollius. The code
handling file descriptors was also fixed to respect asyncio contract:
only call the callback once per loop iteration.

Changes:

* Support also eventlet 0.14, not only eventlet 0.15 or newer
* Support eventlet with monkey-patching
* Rewrite the code handling file descriptors to ensure that the listener is
  only called once per loop iteration, to respect asyncio specification.
* Simplify the loop iteration: remove custom code to reuse instead the
  asyncio/trollius code (_run_once)
* Reuse call_soon, call_soon_threadsafe, call_at, call_later from
  asyncio/trollius, remove custom code
* sock_connect() is now asynchronous
* Add a suite of automated unit tests
* Fix EventLoop.stop(): don't stop immediatly, but schedule stopping the event
  loop with call_soon()
* Add tox.ini to run tests with tox
* Setting debug mode of the event loop doesn't enable "debug_blocking" of
  eventlet on Windows anymore, the feature is not implemented on Windows
  in eventlet.
* add_reader() and add_writer() now cancels the previous handle and sets
  a new handle
* In debug mode, detect calls to call_soon() from greenthreads which are not
  threadsafe (would not wake up the event loop).
* Only set "debug_exceptions" of the eventlet hub when the debug mode of the
  event loop is enabled.

2014-11-19: version 0.1
-----------------------

* First public release


Implemented
===========

Methods:

* call_at()
* call_later()
* call_soon()
* run_forever()
* run_in_executor()
* run_until_complete()
* create_connection(): TCP client
* stop()
* coroutines and tasks

Tests of aiogreen 0.1:

* Tested on Python 2.7, 3.3 and 3.5
* Tested on Linux and Windows
* Tested with Trollius 1.0, 1.0.1 and 1.0.2
* Tested with asyncio 0.4.1 and 3.4.2


To do (Not supported)
=====================

* add_reader() does only support one callback per file descriptor currently.
* run an event loop in a thread different than the main thread
* sockets: create_server, sock_recv
* pipes: connect_read_pipe
* subprocesses: need pipes
* signal handlers: add_signal_handler (only for pyevent hub?)
* tox.ini: add py33_patch. eventlet with Python 3 and monkey-patch causes
  an issue in importlib.


eventlet issues
===============

* eventlet monkey patching on Python 3 is incomplete. The most blocking issue
  is in the importlib: the thread module is patched to use greenthreads, but
  importlib really need to work on real threads. Pull request:
  https://github.com/eventlet/eventlet/pull/168
* eventlet.tpool.setup() seems to be broken on Windows in eventlet 0.15.
  Pull request:
  https://github.com/eventlet/eventlet/pull/167
* hub.debug_blocking is implemented with signal.alarm() which is is not
  available on Windows.


eventlet and Python 3
=====================

Issues:

* https://github.com/eventlet/eventlet/issues/6 (root py3 issue)
* https://github.com/eventlet/eventlet/issues/157 (py3 related?)
* https://github.com/eventlet/eventlet/issues/153 (py3 related?)

Pull requests:

* https://github.com/eventlet/eventlet/pull/99 : complete monkey-patching
* => commit: https://github.com/therve/eventlet/commit/9c3118162cf1ca1e50be330ba2a289f054c48d3c
* https://github.com/eventlet/eventlet/pull/160 (py3 related?)

OpenStack Kilo Summit:

* https://etherpad.openstack.org/p/kilo-oslo-python-3
* https://etherpad.openstack.org/p/kilo-oslo-oslo.messaging
* https://etherpad.openstack.org/p/py34-transition (tangentially related)