InProgress Objects

Throughout Kaa, when a function executes asynchronously (which is generally the case for any function that may otherwise block on some resource), it returns an InProgress object. The InProgress object is a Signal that callbacks can be connected to in order to handle its return value or any exception raised during the asynchronous execution. When the InProgress object is emitted, we say that it is “finished” (and the finished property is True).

InProgress objects are emitted (they are Signal objects, remember) when finished, so handlers can retrieve the return value of the asynchronous task. There is also an exception member, which is itself a Signal, and is emitted when the asynchronous task raises an exception. Exception handlers must accept three arguments: exception class, exception instance, and traceback object. (These three arguments correspond to sys.exc_info())

The following example demonstrates how one might connect callbacks to an InProgress in order to handle success result and exceptions:

import kaa

def handle_connect(result):
    print 'Connected to remote site successfully'

def handle_exception(tp, exc, tb):
    print 'Connect failed:', exc

sock = kaa.Socket()
inprogress = sock.connect('www.freevo.org:80')
inprogress.connect(handle_connect)
inprogress.exception.connect(handle_exception)
# Or a convenience function exists to replace the above 2 lines:
# inprogress.connect_both(handle_connect, handle_exception)
kaa.main.run()

Connecting callbacks to signals in this way is fairly standard and this approach is used in many other frameworks. For example, readers familiar with the Twisted framework may find similarities with Twisted’s Deferreds.

However, InProgress objects can be used with coroutines (covered in more detail later), a more interesting and powerful approach which allows you to handle the result of InProgress objects without the use of callbacks. The above example could be rewritten as:

import kaa

@kaa.coroutine()
def connect(site):
    sock = kaa.Socket()
    try:
        yield sock.connect(site)
    except Exception, exc:
        print 'Connect failed:', exc
    else:
        print 'Connected to remote site successfully'

connect('www.freevo.org:80')
kaa.main.run()

As seen in the above snippet, with coroutines, InProgress objects are used implicitly, where they function as a mechanism for message passing between asynchronous tasks and the coroutine machinery built into the notifier.

If an InProgress finishes with an exception (in which case the failed property is True) but it is not handled by one of the above methods (either by connecting a callback to the exception attribute, or by catching the exception raised by a yield in a coroutine), the exception will be logged to stdout with the heading “Unhandled asynchronous exception.”

class kaa.InProgress(abortable=False, frame=0)

InProgress objects are returned from functions that require more time to complete (because they are either blocked on some resource, are executing in a thread, or perhaps simply because they yielded control back to the main loop as a form of cooperative time slicing).

InProgress subclasses Signal, which means InProgress objects are themselves signals. Callbacks connected to an InProgress receive a single argument containing the result of the asynchronously executed task.

If the asynchronous task raises an exception, the exception member, which is a separate signal, is emitted instead.

Parameters:
  • abortable (bool) – see the abortable property. (Default: False)

Synopsis

Class Hierarchy

kaa.Object
kaa.Signal
└─ kaa.InProgress

Methods
abort()Aborts the asynchronous task this InProgress represents.
connect()Connects a callback to be invoked when the InProgress has returned normally (no exception raised).
connect_both()Convenience function that connects a callback (or callbacks) to both the InProgress (for successful result) and exception signals.
execute()Execute the given function and finish the InProgress object with the result or exception.
finish()This method should be called when the owner (creator) of the InProgress is finished successfully (with no exception).
throw()This method should be called when the owner (creator) of the InProgress is finished because it raised an exception.
timeout()Create a new InProgress object linked to this one that will throw a TimeoutException if this object is not finished by the given timeout.
wait()Blocks until the InProgress is finished.
waitfor()Connects to another InProgress object (A) to self (B). When A finishes (or throws), B is finished with the result or exception.
Properties
abortableread/writeTrue if the asynchronous task this InProgress represents can be aborted by a call to abort().
exceptionread-onlyA Signal emitted when the asynchronous task this InProgress represents has raised an exception.
failedread-onlyTrue if an exception was thrown to the InProgress, False if it was finished without error or if it is not yet finished.
finishedread-onlyTrue if the InProgress is finished.
resultread-onlyThe result the InProgress was finished with. If an exception was thrown to the InProgress, accessing this property will raise that exception.
Signals
abortEmitted when abort() is called.

Methods

abort(exc=None)

Aborts the asynchronous task this InProgress represents.

Parameters:
  • exc (InProgressAborted) – optional exception object with which to abort the InProgress; if None is given, a general InProgressAborted exception will be used.

Not all such tasks can be aborted. If aborting is not supported, or if the InProgress is already finished, a RuntimeError exception is raised.

If a coroutine is aborted, the CoroutineInProgress object returned by the coroutine will be finished with InProgressAborted, while the underlying generator used by the coroutine will have the standard GeneratorExit raised inside it.

connect(callback, *args, **kwargs)

Connects a callback to be invoked when the InProgress has returned normally (no exception raised).

If the asynchronous task raises an exception, the InProgress finishes with that exception and the exception signal is emitted.

connect_both(finished, exception=None)

Convenience function that connects a callback (or callbacks) to both the InProgress (for successful result) and exception signals.

This function does not accept additional args/kwargs to be passed to the callbacks. If you need that, use connect() and exception.connect().

If exception is not given, the given callable will be used for both success and exception results, and therefore must be able to handle variable arguments (as described for each callback below).

Parameters:
  • finished – callback to be invoked upon successful completion; the callback is passed a single argument, the result returned by the asynchronous task.
  • exception – (optional) callback to be invoked when the asynchronous task raises an exception; the callback is passed three arguments representing the exception: exception class, exception instance, and traceback.
execute(func, *args, **kwargs)

Execute the given function and finish the InProgress object with the result or exception.

If the function raises SystemExit or KeyboardInterrupt, those are re-raised to allow them to be properly handled by the main loop.

Parameters:
  • func (callable) – the function to be invoked
  • args – the arguments to be passed to the function
  • kwargs – the keyword arguments to be passed to the function
Returns:

the InProgress object being acted upon (self)

finish(result)

This method should be called when the owner (creator) of the InProgress is finished successfully (with no exception).

Any callbacks connected to the InProgress will then be emitted with the result passed to this method.

If result is an unfinished InProgress, then instead of finishing, we wait for the result to finish.

Parameters:
  • result – the result of the completed asynchronous task. (This can be thought of as the return value of the task if it had been executed synchronously.)
Returns:

This method returns self, which makes it convenient to prime InProgress objects with a finished value. e.g. return InProgress().finish(42)

throw(type, value, tb, aborted=False)

This method should be called when the owner (creator) of the InProgress is finished because it raised an exception.

Any callbacks connected to the exception signal will then be emitted with the arguments passed to this method.

The parameters correspond to sys.exc_info().

Parameters:
  • type – the class of the exception
  • value – the instance of the exception
  • tb – the traceback object representing where the exception took place
timeout(timeout, callback=None, abort=False)

Create a new InProgress object linked to this one that will throw a TimeoutException if this object is not finished by the given timeout.

Parameters:
  • callback – called (with no additional arguments) just prior to TimeoutException
Returns:

a new InProgress object that is subject to the timeout

If the original InProgress finishes before the timeout, the new InProgress (returned by this method) is finished with the result of the original.

If a timeout does occur, the original InProgress object is not affected: it is not finished with the TimeoutException, nor is it aborted. If you want to abort the original task you must do it explicitly:

@kaa.coroutine()
def read_from_socket(sock):
    try:
        data = yield sock.read().timeout(3)
    except TimeoutException, (msg, inprogress):
        print 'Error:', msg
        inprogress.abort()
wait(timeout=None)

Blocks until the InProgress is finished.

The main loop is kept alive if waiting in the main thread, otherwise the thread is blocked until another thread finishes the InProgress.

If the InProgress finishes due to an exception, that exception is raised.

Parameters:
  • timeout – if not None, wait() blocks for at most timeout seconds (which may be fractional). If wait times out, a TimeoutException is raised.
Returns:

the value the InProgress finished with

waitfor(inprogress)

Connects to another InProgress object (A) to self (B). When A finishes (or throws), B is finished with the result or exception.

Parameters:
  • inprogress (InProgress) – the other InProgress object to link to.

Properties

abortable

True if the asynchronous task this InProgress represents can be aborted by a call to abort().

Normally abort() will fail if there are no callbacks attached to the abort signal. This property may be explicitly set to True, in which case abort() will succeed regardless. An InProgress is therefore abortable if the abortable property has been explicitly set to True, if if there are callbacks connected to the abort signal.

This is useful when constructing an InProgress object that corresponds to an asynchronous task that can be safely aborted with no explicit action.

exception

A Signal emitted when the asynchronous task this InProgress represents has raised an exception.

Callbacks connected to this signal receive three arguments: exception class, exception instance, traceback.

failed
True if an exception was thrown to the InProgress, False if it was finished without error or if it is not yet finished.
finished
True if the InProgress is finished.
result
The result the InProgress was finished with. If an exception was thrown to the InProgress, accessing this property will raise that exception.

Signals

abort

Emitted when abort() is called.

def callback(exc)
Parameters:
  • exc (InProgressAborted) – an exception object the InProgress was aborted with.

If the task cannot be aborted, the callback can return False, which will cause an exception to be raised by abort().

InProgress Collections

class kaa.InProgressAny(*objects, **kwargs)

InProgress object that finishes when ANY of the supplied InProgress objects (in constructor) finish. This functionality is useful when building state machines using coroutines.

The initializer can take two optional kwargs: pass_index and filter.

If pass_index is True, the InProgressAny object then finishes with a 2-tuple, whose first element is the index (offset from 0) of the InProgress that finished, and the second element is the result the InProgress was finished with.

If pass_index is False, the InProgressAny is finished with just the result and not the index.

If filter is specified, it is a callable that receives two arguments, the index and finished result (as described above). If the callable returns True AND if there are other underlying InProgress objects that could yet be finished, then this InProgressAny is _not_ finished.

Synopsis

Class Hierarchy

kaa.Signal
kaa.Object
└─ kaa.InProgress
     └─ kaa.InProgressAny

Methods
finish()Invoked when any one of the InProgress objects passed to the constructor have finished.
Signals
abortEmitted when abort() is called.

Methods

finish(is_exception, index, *result)
Invoked when any one of the InProgress objects passed to the constructor have finished.

Signals

abort

Emitted when abort() is called.

def callback(exc)
Parameters:
  • exc (InProgressAborted) – an exception object the InProgress was aborted with.

If the task cannot be aborted, the callback can return False, which will cause an exception to be raised by abort().

class kaa.InProgressAll(*objects)

InProgress object that finishes only when ALL of the supplied InProgress objects (in constructor) finish. This functionality is useful when building state machines using coroutines.

The InProgressAll object then finishes with itself (which is really only useful when using the Python 2.5 feature of yield return values). The finished InProgressAll is useful to fetch the results of the individual InProgress objects. It can be treated as an iterator, and can be indexed.

Synopsis

Class Hierarchy

kaa.Object
kaa.Signal
└─ kaa.InProgress
     └─ kaa.InProgressAny
          └─ kaa.InProgressAll

Methods
finish()
Signals
abortEmitted when abort() is called.

Methods

finish(is_exception, *result)

Signals

abort

Emitted when abort() is called.

def callback(exc)
Parameters:
  • exc (InProgressAborted) – an exception object the InProgress was aborted with.

If the task cannot be aborted, the callback can return False, which will cause an exception to be raised by abort().

Functions

kaa.inprogress(obj)

Returns a suitable InProgress for the given object.

Parameters:
  • obj – object to represent as an InProgress.
Returns:

an InProgress representing obj

The precise behaviour of an object represented as an InProgress should be defined in the documentation for the class. For example, the InProgress for a Process object will be finished when the process is terminated.

This function simply calls __inprogress__() of the given obj if one exists, and if not will raise an exception. In this sense, it behaves quite similar to len() and __len__().

It is safe to call this function on InProgress objects. (The InProgress object given will simply be returned.)

A practical demonstration of this protocol is in the Signal object, which implements the __inprogress__ method. The returned InProgress in that case is finished with the signal is next emitted. Any object implementing the __inprogress__ protocol can be passed directly to the constructor of InProgressAny or InProgressAll.

kaa.delay(seconds)

Returns an InProgress that finishes after the given time in seconds.

Parameters:
  • obj – object to represent as an InProgress.
Returns:

InProgress