InProgress Objects — kaa.base v0.6.0 documentation

### Navigation

- index
- next |
- previous |
- kaa.base v0.6.0 documentation »
- Asynchronous Programming »

# 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

  `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.

  Signals

  `abort` | Emitted 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

  `abort` | Emitted 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

  `abort` | Emitted 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`

### Navigation

- index
- next |
- previous |
- kaa.base v0.6.0 documentation »
- Asynchronous Programming »