Ice.Future

class Ice.Future

Bases: Awaitable[_T]

A Future object representing the result of an asynchronous operation.

StateCancelled = 'cancelled'
StateDone = 'done'
StateRunning = 'running'
add_done_callback(fn: Callable) → None

Attach a callback to be executed when the future completes.

The callback fn is called with the future as its only argument once the future completes or is cancelled. Registered callbacks are executed in the order they were added.

If the future is already complete, fn is called immediately from the calling thread.

Parameters:

fn (callable) – The function to execute upon completion. Takes the future as its argument.

Return type:

None

cancel()

Attempt to cancel the operation.

If the operation is already running or has completed, it cannot be cancelled, and the method returns False. Otherwise, the operation is cancelled, and the method returns True.

Returns:

True if the operation was cancelled, False otherwise.

Return type:

bool

cancelled()

Check if the future has been cancelled.

Returns:

True if the future was cancelled using cancel(), otherwise False.

Return type:

bool

static completed(result: _T) → Future[_T]
Parameters:

result (_T)

Return type:

Future[_T]

done()

Check if the future has completed or been cancelled.

Returns:

True if the operation has completed (successfully or with an exception) or has been cancelled, otherwise False.

Return type:

bool

exception(timeout: int | float | None = None) → BaseException | None

Retrieve the exception raised by the operation.

If the operation has not completed, this method waits up to timeout seconds for it to finish. If the timeout is reached, a TimeoutException is raised.

If the future was cancelled before completing, an InvocationCanceledException is raised.

If the operation completed successfully without raising an exception, None is returned.

Parameters:

timeout (int | float, optional) – Maximum time (in seconds) to wait for the exception. If None, the method waits indefinitely until the operation completes.

Returns:

The exception raised by the operation, or None if the operation completed successfully.

Return type:

BaseException or None

Raises:
result(timeout: int | float | None = None) → _T

Retrieve the result of the future.

If the operation has not completed, this method waits up to timeout seconds for it to finish. If the timeout is reached, a TimeoutException is raised.

If the future was cancelled before completing, an InvocationCanceledException is raised.

If the operation raised an exception, this method raises the same exception.

Parameters:

timeout (int | float, optional) – Maximum time (in seconds) to wait for the result. If None, the method waits indefinitely until the operation completes.

Returns:

The result of the operation.

Return type:

object

Raises:
running()

Check if the future is still running.

Returns:

True if the operation is currently executing and cannot be cancelled, otherwise False.

Return type:

bool

set_exception(ex: BaseException)

Set an exception for the future and mark it as completed.

This method stores the provided exception ex and transitions the future’s state to “done”. Any registered callbacks are executed after the state update.

If the future is not in a running state, this method has no effect.

Parameters:

ex (BaseException) – The exception to store in the future.

set_result(result: _T)

Set the result of the future and mark it as completed.

This method stores the provided result and transitions the future’s state to “done”. Any registered callbacks are executed after the state update.

If the future is not in a running state, this method has no effect.

Parameters:

result (object) – The result value to store in the future.