class tensorstore.Future

Handle for consuming the result of an asynchronous operation.

This type supports several different patterns for consuming results:

  • Asynchronously with asyncio, using the await keyword:

    >>> future = ts.open({
    ...     'driver': 'array',
    ...     'array': [1, 2, 3],
    ...     'dtype': 'uint32'
    ... })
    >>> await future
    TensorStore({
      'array': [1, 2, 3],
      'context': {'data_copy_concurrency': {}},
      'driver': 'array',
      'dtype': 'uint32',
      'transform': {'input_exclusive_max': [3], 'input_inclusive_min': [0]},
    })
    
  • Synchronously blocking the current thread, by calling result().

    >>> future = ts.open({
    ...     'driver': 'array',
    ...     'array': [1, 2, 3],
    ...     'dtype': 'uint32'
    ... })
    >>> future.result()
    TensorStore({
      'array': [1, 2, 3],
      'context': {'data_copy_concurrency': {}},
      'driver': 'array',
      'dtype': 'uint32',
      'transform': {'input_exclusive_max': [3], 'input_inclusive_min': [0]},
    })
    
  • Asynchronously, by registering a callback using add_done_callback():

    >>> future = ts.open({
    ...     'driver': 'array',
    ...     'array': [1, 2, 3],
    ...     'dtype': 'uint32'
    ... })
    >>> future.add_done_callback(
    ...     lambda f: print(f'Callback: {f.result().domain}'))
    ... future.force()  # ensure the operation is started
    ... # wait for completion (for testing only)
    ... result = future.result()
    Callback: { [0, 3) }
    

If an error occurs, instead of returning a value, result() or await will raise an exception.

This type supports a subset of the interfaces of concurrent.futures.Future and asyncio.Future. Unlike those types, however, Future provides only the consumer interface. The corresponding producer interface is provided by Promise.

See also

Constructors

Future(future: FutureLike, *, ...)

Converts a FutureLike object to a Future.

Callback interface

add_done_callback(callback: Callable[[Future], None]) None

Registers a callback to be invoked upon completion of the asynchronous operation.

remove_done_callback(callback: Callable[[Future], None]) int

Unregisters a previously-registered callback.

Blocking interface

result(timeout: float | None = None, ...) object

Blocks until the asynchronous operation completes, and returns the result.

exception(timeout: float | None = None, ...) object

Blocks until asynchronous operation completes, and returns the error if any.

Accessors

done() bool

Queries whether the asynchronous operation has completed or been cancelled.

cancelled() bool

Queries whether the asynchronous operation has been cancelled.

Public members

force() None

Ensures the asynchronous operation begins executing.

cancel() bool

Requests cancellation of the asynchronous operation.