======
Loopy
======

Loopy is a package providing a generic interface for developing
events and event loops. It is meant to make integrating different
event loops into a single event loop easier.

Package Contents
==================
Currently, loopy provides generic event and event loop classes as well
as implementations of the libevent, multitask, and the standard library
sched event loops along with examples. It is currently still a bit
awkward in developing an implementation -- I've had to subclass both 
multitask's TaskManager class and sched's scheduler class to hack in
functionality to try and be on par with what the libevent loop can do --
so any suggestions on making it easier to develop implementations
would be very much appreciated!

History
=========
Loopy started life as a single python script meant to wrap a c library
using the ctypes module included in the python2.5 standard library.

Redundant?
~~~~~~~~~~~
After much consideration I eventually chose to try my hand at wrapping the 
libevent_ library even though I know of two implementations that already 
exist: pyevent_ and `libevent-python`_. I wasn't exactly satisfied with
these two implementations for various reasons, and I really was just 
looking for a way to learn how to use the ctypes module.

.. _libevent: http://www.monkey.org/~provos/libevent
.. _pyevent: http://code.google.com/p/pyevent
.. _libevent-python: http://python.org/pypi/libevent-python

Evolving...
~~~~~~~~~~~~
After I managed to wrap the libevent library and port over an `echo server`_
example, I came across the liboop_ library. This was when a thought began
to bubble up into my mind: wouldn't it be nice if there was a way to
implement various different event loops against a set of known behaviours 
and be able to hook them up together into an over-arching event loop? And
all implementations coded in python?

.. _echo server: http://unx.ca/log/category/libevent
.. _liboop: http://liboop.org

The Refactoring
~~~~~~~~~~~~~~~~
It was a somewhat simple job to refactor my simple echo server example
into event and event loop classes. But even though a little bit of
subclassing was needed to hack in needed functionality to the multitask
and scheduler event loops i.e. being able to have precise control over when
a run cycle runs and how to shut down the event loop, the one little python
script wrapping libevent turned into the loopy package.

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

See INSTALL.

Using this package
===================

As this package is still very young, and in fact is the very first
package I'm putting up on the cheeseshop, there is no documentation
as yet. Due to the way it evolved, there are no unit tests yet either.
Thus, uploads of the loopy package in the forseeable future will be
focused on adding tests and documentation.

For now, see the three scripts in the top-level examples directory which
demonstrates simple loopy implementations of libevent, multitask, and
sched event loops.

A note on commented braces
===========================
If you take a look through the code, you will see for every
class or function/method definition commented braces:

::

   def some_func(): #{{{
      do_stuff = True
   # End def #}}}

These commented braces are vim_'s explicit fold markers. In the
past I've tried many implicit fold techniques and plugins, but
it seems for now the best method that provides the most
consistency is map commands for defining skeleton definitions
of python syntax e.g. class, def, for, while, if, etc.

.. _vim: http://vim.org
