
asyncoro
********

asyncoro is a Python framework for asynchronous, *concurrent*,
*distributed* programming using generator functions, asynchronous
completions and message passing. asyncoro API can be used to create
coroutines with generator functions, similar to the way threads are
created with functions with Python's threading module. Thus, programs
developed with asyncoro have **same logic and structure** as programs
with threads, except for a few syntactic changes - mostly using
*yield* with asynchronous completions that give control to asyncoro's
scheduler, which interleaves executions of generators, similar to the
way an operating system executes multiple processes.

Unlike threads, creating processes (coroutines) with asyncoro is very
efficient. Moreover, with asyncoro context switch occurs only when
coroutines use *yield* (typically with an asychronous call), so there
is no need for locking and there is no overhead of unnecessary context
switches.

asyncoro features include:

* No callbacks or event loops! No need to lock critical sections
  either,

* Efficient polling mechanisms epoll, kqueue, /dev/poll, Windows I/O
  Completion Ports (IOCP) for high performance and scalability,

* Asynchronous (non-blocking) *sockets* and *pipes*, for concurrent
  processing of I/O,

* SSL for security,

* Asynchronous timers, including non-blocking sleep,

* Asynchronous locking primitives similar to Python threading
  module,

* Message passing for (local and remote) coroutines to exchange
  messages one-to-one with Message Queue Pattern or through
  broadcasting channels with Publish-Subscribe Pattern,

* Location transparency with naming and locating (local and remote)
  resources,

* Remote execution of coroutines for distributed/parallel
  programming with Remote Coroutine Invocation "RCI" and message
  passing,

* Monitoring and restarting of (local or remote) coroutines, for
  fault detection and fault-tolerance,

* Hot-swapping of coroutine functions, for dynamic system
  reconfiguration,

* Distributing computation fragments for remote execution of
  coroutines with *Distributed Communicating Processes*,

* Thread pools with asynchronous task completions, for executing
  synchronous tasks, e.g., blocking functions, such as reading input.

For reference purposes, asyncoro with Python 2.7 on Ubuntu Linux 12.04
running the concurrent program:

   import asyncoro, resource, time
   def coro_proc(coro=None):
       yield coro.suspend()

   coros = [asyncoro.Coro(coro_proc) for i in xrange(100000)]
   time.sleep(5)
   ru = resource.getrusage(resource.RUSAGE_SELF)
   print('Max RSS: %.1f MB' % (ru.ru_maxrss / 1024.0))
   for coro in coros:
       coro.resume()

shows that 100,000 coroutines take about 200 MB of resident memory
(RSS field).

asyncoro is implemented with standard modules in Python. Under Windows
efficient polling notifier I/O Completion Ports is supported only if
pywin32 is installed; otherwise, inefficient 'select' notifier is
used.

asyncoro works with Python 2.7+ and Python 3.1+ and tested on Linux,
Mac OS X and Windows; it may work on other platforms too. asyncoro
works with PyPy as well.


Download/Installation
=====================

asyncoro package is available in Python Package Index (PyPI) so it can
be installed for Python 2.7+ with:

   pip install asyncoro

and/or for Python 3.1+ with:

   pip3 install asyncoro

asyncoro can also be downloaded from Sourceforge Files.

Examples illustrating some of the features of asyncoro are installed
in 'examples' directory under where asyncoro module is.


Contents
========

* Introduction

* Asynchronous Concurrenct Programming

  * AsynCoro scheduler

  * Coroutines

  * Locking Primitives

  * Channels

  * Message Passing

* Asynchronous Network Programming

  * Asynchronous Sockets

* Asynchronous Files and Pipes

  * Asynchronous File

  * Asynchronous Pipe

* Distributed Programming

  * Location

  * Distributed AsynCoro

  * Distributed Coroutines

  * Distributed Channels

  * Remote Coroutine (Callable) Invocation (RCI)

* Distributed Communicating Processes

  * Node / Processes

  * Scheduler

  * Computation

* Tutorial / Examples

  * Asynchronous Concurrent Programming

  * Asynchronous Network Programming

  * Distributed Programming

  * Distributed Communicating Processes


Indices and tables
==================

* Index

* Module Index

* Search Page
