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.”
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: |
|
---|
kaa.Object
kaa.Signal
└─ kaa.InProgress
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. |
abortable | read/write | True if the asynchronous task this InProgress represents can be aborted by a call to abort(). |
---|---|---|
exception | read-only | A Signal emitted when the asynchronous task this InProgress represents has raised an exception. |
failed | read-only | True if an exception was thrown to the InProgress, False if it was finished without error or if it is not yet finished. |
finished | read-only | True if the InProgress is finished. |
result | read-only | The result the InProgress was finished with. If an exception was thrown to the InProgress, accessing this property will raise that exception. |
abort | Emitted when abort() is called. |
---|
Aborts the asynchronous task this InProgress represents.
Parameters: |
|
---|
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.
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.
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: |
|
---|
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: |
|
---|---|
Returns: | the InProgress object being acted upon (self) |
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: |
|
---|---|
Returns: | This method returns self, which makes it convenient to prime InProgress objects with a finished value. e.g. return InProgress().finish(42) |
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: |
|
---|
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: |
|
---|---|
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()
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: |
|
---|---|
Returns: | the value the InProgress finished with |
Connects to another InProgress object (A) to self (B). When A finishes (or throws), B is finished with the result or exception.
Parameters: |
|
---|
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.
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.
Emitted when abort() is called.
Parameters: |
|
---|
If the task cannot be aborted, the callback can return False, which will cause an exception to be raised by abort().
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.
kaa.Signal
kaa.Object
└─ kaa.InProgress
└─ kaa.InProgressAny
finish() | Invoked when any one of the InProgress objects passed to the constructor have finished. |
---|
abort | Emitted when abort() is called. |
---|
Emitted when abort() is called.
Parameters: |
|
---|
If the task cannot be aborted, the callback can return False, which will cause an exception to be raised by abort().
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.
kaa.Object
kaa.Signal
└─ kaa.InProgress
└─ kaa.InProgressAny
└─ kaa.InProgressAll
finish() |
---|
abort | Emitted when abort() is called. |
---|
Emitted when abort() is called.
Parameters: |
|
---|
If the task cannot be aborted, the callback can return False, which will cause an exception to be raised by abort().
Returns a suitable InProgress for the given object.
Parameters: |
|
---|---|
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.
Returns an InProgress that finishes after the given time in seconds.
Parameters: |
|
---|---|
Returns: |