Futures

Futures are advanced primitives for durable waits. They suspend job execution when a value is not ready and resume when the condition becomes true.

Symbol	Import path	Purpose	Stability
`FutureResult`	`statek.future`	Base future-like value	Advanced
`FutureElement`	`statek.future`	Element proxy for tuple-return futures	Advanced
`CombinedFutureResult`	`statek.future`	Aggregates multiple futures	Advanced
`temporal`	`statek.future`	Decorates temporal functions	Advanced
`get_any_future`	`statek.future`	Resolve when any future is ready	Advanced
`get_all_future`	`statek.future`	Resolve when all futures are ready	Advanced

`FutureResult`

@db0.memo
@dataclass
class FutureResult:
    deps: Any | set[Any] | tuple[Any, ...]
    state_num: int

Represents a pending result with dependency tracking, a value complement, and a readiness condition.

Member	Returns	Description
`set_complement_functions(complement, condition)`	`None`	Binds value and readiness functions.
`bind_error_handler(error_handler, job)`	`None`	Defers registration of an error handler until the value resolves.
`value`	`Any`	Calls the complement and returns the resolved value.
`check_condition()`	`bool`	Calls the readiness condition.
`__iter__()`	`Iterator[FutureElement]`	Enables unpacking tuple-return futures.

Raises

value can raise FutureError from the complement. Iteration raises FutureError when the return type cannot be unpacked as a tuple.

`@temporal`

def temporal(
    complement: Callable[[FutureResult], Any] = None,
    condition: Callable[[FutureResult], bool] = None,
    extends: Callable = None,
)

Decorates a sync or async function that returns a FutureResult or a ready value.

Parameters

Name	Description
`complement`	Function that fetches the resolved value. Required unless `extends` is used.
`condition`	Function that checks readiness. Required unless `extends` is used.
`extends`	Existing temporal function whose complement and condition should be reused.

Raises

Raises ValueError if extends is combined with explicit complement/condition, if extends is not temporal, or if neither a valid extends nor both complement and condition are supplied.

from statek.future import FutureResult, temporal
 
def get_result(future):
    return future.deps.value
 
def is_ready(future):
    return future.deps.ready
 
@temporal(complement=get_result, condition=is_ready)
def wait_for_record(record):
    return FutureResult(deps=record, state_num=0)

Combined futures

def get_any_future(*args: FutureResult) -> CombinedFutureResult
def get_all_future(*args: FutureResult) -> CombinedFutureResult

get_any_future(...) resolves to the first ready future value. get_all_future(...) resolves to a tuple of all future values in order.

Raises: both functions raise TypeError when called without arguments. Accessing .value raises FutureError if the combined future is not ready.

from statek import get_any
 
winner = get_any(wait_for_user(user), wait_for_timeout(timer))
print(winner.value)

Related APIs: Temporal Tools, Subtasks, Tools.

Subtasks Providers