Module kiwi.tasklet
Pseudo-thread (coroutines) framework
Introduction
This module adds infrastructure for managing tasklets. In this
context, a 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
coroutines, or 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 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 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 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 generator function,
i.e. a function or method containing one or more yield
statements. Tasklets add a couple more requirements to regular
generator functions:
-
The values contained in
yield
statements cannot be
arbitrary (see below);
-
After each
yield
that indicates events, the
function kiwi.tasklet.get_event
must be called
to retrieve the event that just occurred.
Syntax for yield in tasklets
Inside tasklet functions, yield
statements are used to
suspend execution of the tasklet while waiting for certain events.
Valid yield
values are:
-
A single
Message
object, with a correctly set
dest parameter. With this form, a message is sent to the
indicated tasklet. When yield
returns, no event is
generated, so the tasklet should not call get_event
.
-
One, or a sequence of:
In this case, the tasklet is suspended until either one of the
indicated events occurs. The tasklet must call
get_event
in this case.
Launching a tasklet
To start a tasklet, the Tasklet
constructor must be used:
from kiwi import tasklet
def my_task(x):
[...]
tasklet.Tasklet(my_task(x=0))
Alternatively, 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()
Classes |
Message |
A message that can be received by or sent to a tasklet. |
task |
A decorator that modifies a tasklet function to avoid the need to call
tasklet.run(func()) or
tasklet.Tasklet(func()) . |
Tasklet |
An object that launches and manages a tasklet. |
WaitCondition |
Base class for all wait-able condition objects. |
WaitForIdle |
An object that waits for the main loop to become idle |
WaitForIO |
An object that waits for IO conditions on sockets or file
descriptors. |
WaitForMessages |
An object that waits for messages to arrive |
WaitForProcess |
An object that waits for a process to end |
WaitForSignal |
An object that waits for a signal emission |
WaitForTasklet |
An object that waits for a tasklet to complete |
WaitForTimeout |
An object that waits for a specified ammount of time (a timeout) |
Function Summary |
|
get_event ()
Return the last event that caused the current tasklet to regain
control. |
|
run (gen)
Start running a generator as a Tasklet . |
get_event()
Return the last event that caused the current tasklet to regain
control.
-
Warning: this function should be called exactly once after each yield that
includes a wait condition.
|
run(gen)
Start running a generator as a Tasklet .
-
- Parameters:
gen -
generator object that implements the tasklet body.
- Returns:
-
a new
Tasklet instance, already
running.
Note: this is strictly equivalent to calling Tasklet(gen) .
|