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()
Class task A decorator that modifies a tasklet function to avoid the need to call C{tasklet.run(func())} or C{tasklet.Tasklet(func())}.
Function get_event Return the last event that caused the current tasklet to regain control.
Function run Start running a generator as a L{Tasklet}.
Class WaitCondition Base class for all wait-able condition objects.
Class WaitForCall An object that waits until it is called.
Class WaitForIO An object that waits for IO conditions on sockets or file descriptors.
Class WaitForTimeout An object that waits for a specified ammount of time (a timeout)
Class WaitForIdle An object that waits for the main loop to become idle
Class WaitForTasklet An object that waits for a tasklet to complete
Class WaitForSignal An object that waits for a signal emission
Class WaitForProcess An object that waits for a process to end
Class Message A message that can be received by or sent to a tasklet.
Class WaitForMessages An object that waits for messages to arrive
Class Tasklet An object that launches and manages a tasklet.
Function _normalize_list_argument returns a list of strings from an argument that can be either list of strings, None (returns []), or a single string returns ([arg])
def get_event():
Return the last event that caused the current tasklet to regain control.

@note: this function should be called exactly once after each
yield that includes a wait condition.
def run(gen):
Start running a generator as a L{Tasklet}.

@param gen: generator object that implements the tasklet body.
@return: a new L{Tasklet} instance, already running.

@note: this is strictly equivalent to calling C{Tasklet(gen)}.
def _normalize_list_argument(arg, name):
returns a list of strings from an argument that can be either
list of strings, None (returns []), or a single string returns
([arg])
API Documentation for Kiwi, generated by pydoctor at 2019-08-08 02:24:42.