/usr/share/doc/python-kiwi/api/kiwi.tasklet.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
        <html><head>
        <link rel="stylesheet" type="text/css" href="apidocs.css"/>
        <title>API docs for &ldquo;kiwi.tasklet&rdquo;</title>
        </head>
        <body><h1 class="module">Module k.tasklet</h1><span id="part">Part of <a href="kiwi.html">kiwi</a></span><div class="toplevel"><div><p>Pseudo-thread (coroutines) framework</p>
<h1 class="heading">Introduction</h1>
  <p>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 <i>coroutines</i>, or <i>cooperative threads</i>.</p>
  <p>The main advantages of tasklets are:</p>
  <ul>
    <li>
      Eliminates the danger of unexpected race conditions or deadlocks that
      happen with preemptive (regular) threads;
    </li>
    <li>
      Reduces the number of callbacks in your code, that sometimes are so 
      many that you end up with <i>spaghetti code</i>.
    </li>
  </ul>
  <p>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 <code>yield</code> statements.</p>
  <p>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 <code>next()</code> 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.</p>
<h1 class="heading">Structure of a tasklet</h1>
  <p>At the outset, a tasklet is simply a python <a 
  href="http://www.python.org/peps/pep-0255.html" target="_top">generator 
  function</a>, i.e. a function or method containing one or more 
  <code>yield</code> statements.  Tasklets add a couple more requirements 
  to regular generator functions:</p>
  <ol start="1">
    <li>
      The values contained in <code>yield</code> statements cannot be 
      arbitrary (see below);
    </li>
    <li>
      After each <code>yield</code> that indicates events, the function <a 
      href="kiwi.tasklet.get_event.html">kiwi.tasklet.get_event</a> must be
      called to retrieve the event that just occurred.
    </li>
  </ol>
<h1 class="heading">Syntax for yield in tasklets</h1>
  <p>Inside tasklet functions, <code>yield</code> statements are used to 
  suspend execution of the tasklet while waiting for certain events.  Valid
  <code>yield</code> values are:</p>
  <ul>
    <li>
      A single <a href="kiwi.tasklet.Message.html">Message</a> object, with
      a correctly set <i>dest</i> parameter.  With this form, a message is 
      sent to the indicated tasklet.  When <code>yield</code> returns, no 
      event is generated, so the tasklet should <b>not</b> call <a 
      href="kiwi.tasklet.get_event.html">get_event</a>.
    </li>
    <li>
      One, or a sequence of:
      <ul>
        <li>
          <a href="kiwi.tasklet.WaitCondition.html">WaitCondition</a>, 
          meaning to wait for that specific condition
        </li>
        <li>
          <a href="kiwi.tasklet.Tasklet.html">Tasklet</a>, with the same 
          meaning as <a 
          href="kiwi.tasklet.WaitForTasklet.html">WaitForTasklet</a><code>(tasklet)</code>
        </li>
        <li>
          generator, with the same meaning as <a 
          href="kiwi.tasklet.WaitForTasklet.html">WaitForTasklet</a><code>(Tasklet(gen))</code>
        </li>
      </ul>
      <p>In this case, the tasklet is suspended until either one of the 
      indicated events occurs.  The tasklet must call <a 
      href="kiwi.tasklet.get_event.html">get_event</a> in this case.</p>
    </li>
  </ul>
<h1 class="heading">Launching a tasklet</h1>
  <p>To start a tasklet, the <a 
  href="kiwi.tasklet.Tasklet.html">Tasklet</a> constructor must be 
  used:</p>
<pre class="literalblock">
 from kiwi import tasklet

 def my_task(x):
     [...]

 tasklet.Tasklet(my_task(x=0))
</pre>
  <p>Alternatively, <a href="kiwi.tasklet.run.html">kiwi.tasklet.run</a> 
  can be used to the same effect:</p>
<pre class="literalblock">
 from kiwi import tasklet
 tasklet.run(my_task(x=0))
</pre>
  <p>Yet another approach is to use the @tasklet.task decorator:</p>
<pre class="literalblock">
 from kiwi import tasklet

 @tasklet.task
 def my_task(x):
     [...]
     raise StopIteration(&quot;return value&quot;)

 yield my_task(x=0)
 retval = tasklet.get_event().retval
</pre>
<h1 class="heading">Examples</h1>
  <h2 class="heading">Background timeout task</h2>
    <p>This example demonstrates basic tasklet structure and timeout 
    events:</p>
<pre class="literalblock">
 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()
</pre>
  <h2 class="heading">Message passing</h2>
    <p>This example extends the previous one and demonstrates message 
    passing:</p>
<pre class="literalblock">
 import gobject
 from kiwi import tasklet

 mainloop = gobject.MainLoop()

 @tasklet.task
 def printer():
     msgwait = tasklet.WaitForMessages(accept=(&quot;quit&quot;, &quot;print&quot;))
     while True:
         yield msgwait
         msg = tasklet.get_event()
         if msg.name == &quot;quit&quot;:
             return
         assert msg.name == 'print'
         print &quot;&gt;&gt;&gt; &quot;, 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()
</pre>
</div></div><table class="children"><tr class="class"><td>Class</td><td><a href="kiwi.tasklet.task.html">task</a></td><td><div><p>A decorator that modifies a tasklet function to avoid the need</p>
</div></td></tr><tr class="function"><td>Function</td><td><a href="#kiwi.tasklet.get_event">get_event</a></td><td><div><p>Return the last event that caused the current tasklet to regain 
control.</p>
</div></td></tr><tr class="function"><td>Function</td><td><a href="#kiwi.tasklet.run">run</a></td><td><div><p>Start running a generator as a <a 
href="kiwi.tasklet.Tasklet.html">Tasklet</a>.</p>
</div></td></tr><tr class="class"><td>Class</td><td><a href="kiwi.tasklet.WaitCondition.html">WaitCondition</a></td><td><div><p>Base class for all wait-able condition objects.</p>
</div></td></tr><tr class="class"><td>Class</td><td><a href="kiwi.tasklet.WaitForCall.html">WaitForCall</a></td><td><div><p>An object that waits until it is called.</p>
</div></td></tr><tr class="class"><td>Class</td><td><a href="kiwi.tasklet.WaitForIO.html">WaitForIO</a></td><td><div><p>An object that waits for IO conditions on sockets or file</p>
</div></td></tr><tr class="class"><td>Class</td><td><a href="kiwi.tasklet.WaitForTimeout.html">WaitForTimeout</a></td><td><div><p>An object that waits for a specified ammount of time (a timeout)</p>
</div></td></tr><tr class="class"><td>Class</td><td><a href="kiwi.tasklet.WaitForIdle.html">WaitForIdle</a></td><td><div><p>An object that waits for the main loop to become idle</p>
</div></td></tr><tr class="class"><td>Class</td><td><a href="kiwi.tasklet.WaitForTasklet.html">WaitForTasklet</a></td><td><div><p>An object that waits for a tasklet to complete</p>
</div></td></tr><tr class="class"><td>Class</td><td><a href="kiwi.tasklet.WaitForSignal.html">WaitForSignal</a></td><td><div><p>An object that waits for a signal emission</p>
</div></td></tr><tr class="class"><td>Class</td><td><a href="kiwi.tasklet.WaitForProcess.html">WaitForProcess</a></td><td><div><p>An object that waits for a process to end</p>
</div></td></tr><tr class="class"><td>Class</td><td><a href="kiwi.tasklet.Message.html">Message</a></td><td><div><p>A message that can be received by or sent to a tasklet.</p>
</div></td></tr><tr class="function"><td>Function</td><td><a href="#kiwi.tasklet._normalize_list_argument">_normalize_list_argument</a></td><td><div><p>returns a list of strings from an argument that can be either</p>
</div></td></tr><tr class="class"><td>Class</td><td><a href="kiwi.tasklet.WaitForMessages.html">WaitForMessages</a></td><td><div><p>An object that waits for messages to arrive</p>
</div></td></tr><tr class="class"><td>Class</td><td><a href="kiwi.tasklet.Tasklet.html">Tasklet</a></td><td><div><p>An object that launches and manages a tasklet.</p>
</div></td></tr></table>
            <div class="function">
            <div class="functionHeader">def <a name="kiwi.tasklet.get_event">get_event():</a></div>
            <div class="functionBody"><div><p>Return the last event that caused the current tasklet to regain 
control.</p>
</div><div class="metadata"><span class="tag">note</span> <span class="arg">None</span><span class="body">this function should be called exactly once after each yield that includes 
a wait condition.
</span></div></div>
            </div>
            <div class="function">
            <div class="functionHeader">def <a name="kiwi.tasklet.run">run(gen):</a></div>
            <div class="functionBody"><div><p>Start running a generator as a <a 
href="kiwi.tasklet.Tasklet.html">Tasklet</a>.</p>
</div><div class="metadata"><span class="tag">param</span> <span class="arg">gen</span><span class="body">generator object that implements the tasklet body.
</span></div><div class="metadata"><span class="tag">return</span> <span class="arg">None</span><span class="body">a new <a href="kiwi.tasklet.Tasklet.html">Tasklet</a> instance, already 
running.
</span></div><div class="metadata"><span class="tag">note</span> <span class="arg">None</span><span class="body">this is strictly equivalent to calling <code>Tasklet(gen)</code>.
</span></div></div>
            </div>
            <div class="function">
            <div class="functionHeader">def <a name="kiwi.tasklet._normalize_list_argument">_normalize_list_argument(arg, name):</a></div>
            <div class="functionBody"><div><p>returns a list of strings from an argument that can be either list of 
strings, None (returns []), or a single string returns ([arg])</p>
</div></div>
            </div></body>
python-kiwi 1.9.22-2 / usr / share / doc / python-kiwi / api / kiwi.tasklet.html
