Task that can be paused and resumed based on event occurences

Tasks maintain a stack of "currently executing procedures". The topmost procedure's next() method is invoked repeatedly to obtain ITaskSwitch instances that determine whether the task will continue, invoke a nested procedure (by pushing it on the stack), or be suspended (by returning from the step() method. When an procedure's iteration is exhausted, it's popped from the stack, and the next-highest procedure is resumed. This simple "virtual machine" allows linear Python code to co-operatively multitask on the basis of arbitrary events.

Procedures used in tasks must call events.resume() immediately after each yield statement (or at the beginning of their next() method, if not a generator), in order to ensure that errors are handled properly. If the event source or generator that was yielded sends a value or event back to the task, that value will be returned by resume().

Procedures may send values back to their calling iterators by yielding values that do not implement ITaskSwitch. If there is no calling iterator, the yielded value is sent to any callbacks that have been added to the task itself. (Tasks are event sources, so they may be yielded on, or have callbacks added to them to receive values yielded by the task's outermost procedure.) Note that when a nested procedure terminates, NOT_GIVEN is returned from events.resume() in the calling procedure.

Finally, note that event sources may send values back to a task by passing them as events to the task's step() callback method.

step ( source=None,  event=NOT_GIVEN )