tensorstore.Future - TensorStore

class tensorstore.Future[T]

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)
... ])

Constructors¶

Future(future: FutureLike, *, ...): Converts a FutureLike object to a Future.

Callback interface¶

add_done_callback(callback: Callable[[Future[T]], None]) → None: Registers a callback to be invoked upon completion of the asynchronous operation.

remove_done_callback(callback: Callable[[Future[T]], None]) → int: Unregisters a previously-registered callback.

Blocking interface¶

result(timeout: float | None = None, ...) → T: 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.

Operations¶

force() → None: Ensures the asynchronous operation begins executing.

cancel() → bool: Requests cancellation of the asynchronous operation.