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.

Warning

While this class is designed to interoperate with asyncio, it cannot be used with functions such as asyncio.wait that require an asyncio.Future, because add_done_callback does not guarantee that the callback is invoked from the current event loop. To convert to a real asyncio.Future, use asyncio.ensure_future:

>>> dataset = await ts.open({
...     'driver': 'zarr',
...     'kvstore': 'memory://'
... },
...                         dtype=ts.uint32,
...                         shape=[70, 80],
...                         create=True)
>>> await asyncio.wait([
...     asyncio.ensure_future(dataset[i * 5].write(i))
...     for i in range(10)
... ])

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.