Pseudo-thread (coroutines) framework
Introduction
============
This module adds infrastructure for managing tasklets. In this
context, a X{tasklet} is defined as a routine that explicitly gives
back control to the main program a certain points in the code, while
waiting for certain events. Other terms that may be used to describe
tasklets include I{coroutines}, or I{cooperative threads}.
The main advantages of tasklets are:
- Eliminates the danger of unexpected race conditions or deadlocks
that happen with preemptive (regular) threads;
- Reduces the number of callbacks in your code, that sometimes are
so many that you end up with I{spaghetti code}.
The fundamental block used to create tasklets is Python's generators.
Generators are objects that are defined as functions, and when called
produce iterators that return values defined by the body of the
function, specifically C{yield} statements.
The neat thing about generators are not the iterators themselves but
the fact that a function's state is completely frozen and restored
between one call to the iterator's C{next()} and the following
one. This allows the function to return control to a program's main
loop while waiting for an event, such as IO on a socket, thus allowing
other code to run in the mean time. When the specified event occurs,
the function regains control and continues executing as if nothing had
happened.
Structure of a tasklet
======================
At the outset, a tasklet is simply a python U{generator
function<http://www.python.org/peps/pep-0255.html>}, i.e. a function
or method containing one or more C{yield} statements. Tasklets add a
couple more requirements to regular generator functions:
1. The values contained in C{yield} statements cannot be arbitrary
(see below);
2. After each C{yield} that indicates events, the function
L{kiwi.tasklet.get_event} must be called to retrieve the event that
just occurred.
Syntax for yield in tasklets
============================
Inside tasklet functions, C{yield} statements are used to suspend
execution of the tasklet while waiting for certain events. Valid
C{yield} values are:
- A single L{Message} object, with a correctly set I{dest}
parameter. With this form, a message is sent to the indicated
tasklet. When C{yield} returns, no event is generated, so the
tasklet should B{not} call L{get_event}.
- One, or a sequence of:
- L{WaitCondition}, meaning to wait for that specific condition
- L{Tasklet}, with the same meaning as L{WaitForTasklet}C{(tasklet)}
- generator, with the same meaning as L{WaitForTasklet}C{(Tasklet(gen))}
In this case, the tasklet is suspended until either one of the
indicated events occurs. The tasklet must call L{get_event} in
this case.
Launching a tasklet
===================
To start a tasklet, the L{Tasklet} constructor must be used::
from kiwi import tasklet
def my_task(x):
[...]
tasklet.Tasklet(my_task(x=0))
Alternatively, L{kiwi.tasklet.run} can be used to the same effect::
from kiwi import tasklet
tasklet.run(my_task(x=0))
Yet another approach is to use the @tasklet.task decorator::
from kiwi import tasklet
@tasklet.task
def my_task(x):
[...]
raise StopIteration("return value")
yield my_task(x=0)
retval = tasklet.get_event().retval
Examples
========
Background timeout task
-----------------------
This example demonstrates basic tasklet structure and timeout events::
import gobject
from kiwi import tasklet
mainloop = gobject.MainLoop()
def simple_counter(numbers):
timeout = tasklet.WaitForTimeout(1000)
for x in xrange(numbers):
print x
yield timeout
tasklet.get_event()
mainloop.quit()
tasklet.run(simple_counter(10))
mainloop.run()
Message passing
---------------
This example extends the previous one and demonstrates message passing::
import gobject
from kiwi import tasklet
mainloop = gobject.MainLoop()
@tasklet.task
def printer():
msgwait = tasklet.WaitForMessages(accept=("quit", "print"))
while True:
yield msgwait
msg = tasklet.get_event()
if msg.name == "quit":
return
assert msg.name == 'print'
print ">>> ", msg.value
@tasklet.task
def simple_counter(numbers, task):
timeout = tasklet.WaitForTimeout(1000)
for x in xrange(numbers):
yield tasklet.Message('print', dest=task, value=x)
yield timeout
tasklet.get_event()
yield tasklet.Message('quit', dest=task)
mainloop.quit()
task = printer()
simple_counter(10, task)
mainloop.run()