nebius.aio.CrossLoopAwaitable

class documentation

class CrossLoopAwaitable(Generic[T]): (source)

Constructor: CrossLoopAwaitable(future, event_loop)

Provide loop-independent access to a concurrent future.

Callers can await the same instance from the SDK loop and from multiple external loops. Synchronous callers can use result. An SDK-owned executor worker cannot wait for a pending handle because the submitted work can need that finite executor. A submission also cannot await its own handle.

All waiters share one concurrent future. Cancellation by one direct awaiter cancels that future and therefore affects every waiter. Use asyncio.shield when cancellation of one waiter must not cancel the shared submission. The concurrent future reports cancellation as soon as it accepts the request. The SDK coroutine can still be running its asynchronous finally block; SDK close drains that finalization.

This object is awaitable. It is not an asyncio.Future or asyncio.Task. Functions such as asyncio.gather accept it. Before you give it to asyncio.wait, wrap it with asyncio.ensure_future. It does not have task-only naming, coroutine-inspection, or callback-removal methods.

A public completion callback uses the running event loop that registers it. The loop must stay running until delivery. The SDK does not move the callback to its completion thread if the registration loop stops or closes. Dispatch is best effort: a loop that stops after accepting the callback can retain it until that loop is closed or run again.

Method	`__await__`	Return an iterator that waits for the submitted work.
Method	`__init__`	Initialize a cross-loop awaitable.
Method	`add_done_callback`	Add a function to call when the submitted work is complete.
Method	`cancel`	Request cancellation of the submitted work.
Method	`cancelled`	Return whether the submission accepted cancellation.
Method	`done`	Return whether the cross-loop result has reached a terminal state.
Method	`exception`	Wait for and return the submitted work exception.
Method	`result`	Wait for and return the submitted work result.
Property	`event_loop`	Return the event loop for the associated SDK runtime.
Class Method	`_for_runtime`	Create a handle associated with an SDK event loop.
Method	`_add_internal_done_callback`	Run a lifecycle callback synchronously on future completion.
Method	`_cancel_unstarted_threadsafe`	Cancel this thread-safe handle for an unstarted wrapper.
Method	`_check_process`	Reject a handle inherited by a child process before locking.
Method	`_reject_blocking_async_wait`	Reject a pending synchronous wait from an active event loop.
Method	`_reject_executor_wait`	Reject a pending wait from a worker in any SDK finite pool.
Method	`_result`	Return the result for a compatibility path that permits blocking.
Async Method	`_wait`	Wait for the concurrent future from the current event loop.
Async Method	`_wait_shielded`	Wait without letting one asyncio waiter cancel shared work.
Instance Variable	`_event_loop`	Undocumented
Instance Variable	`_future`	Undocumented
Instance Variable	`_process_id`	Undocumented
Instance Variable	`_waiters`	Undocumented
Instance Variable	`_waiters_lock`	Undocumented

def __await__(self) -> Generator[Any, None, T]: (source) ¶

Return an iterator that waits for the submitted work.

def __init__(self, future: Future[T], event_loop: asyncio.AbstractEventLoop): (source) ¶

Initialize a cross-loop awaitable.

Applications normally receive this type from SDK methods instead of constructing it directly.

Parameters
future:`Future[T]`	Concurrent future that stores the result.
event_loop:`asyncio.AbstractEventLoop`	Event loop for the associated SDK runtime. A bridged foreign future can still be owned by another loop.

def add_done_callback(self, callback: Callable[[CrossLoopAwaitable[T]], object], *, context: Context | None = None): (source) ¶

Add a function to call when the submitted work is complete.

Like asyncio.Task, this method schedules the callback instead of calling it inline. It uses the event loop active at registration, or the associated SDK loop when no loop is active. The registration context is retained unless context is supplied explicitly. The registration loop must stay running until callback delivery. The SDK logs and drops a callback if the loop has already stopped or rejects dispatch. A loop that stops after accepting dispatch can retain the queued callback until it is closed or run again.

Parameters
callback:`Callable[[CrossLoopAwaitable[T]], object]`	Function that receives this awaitable.
context:`Context \| None`	Optional context in which to run `callback`.
Raises
`RuntimeError`	If the callback loop is not running.

def cancel(self, msg: object | None = None) -> bool: (source) ¶

Request cancellation of the submitted work.

msg is accepted for asyncio.Task call compatibility. A concurrent future cannot carry that message, so it is ignored.

Parameters
msg:`object \| None`	Optional cancellation message, retained only for call compatibility.
Returns
`bool`	`True` if the future accepted the cancellation request.

def cancelled(self) -> bool: (source) ¶

Return whether the submission accepted cancellation.

The SDK coroutine can still be completing an asynchronous finalizer.

def done(self) -> bool: (source) ¶

Return whether the cross-loop result has reached a terminal state.

A cancelled result can become terminal before the SDK coroutine has completed its asynchronous finalizer.

def exception(self, timeout: float | None = None) -> BaseException | None: (source) ¶

Wait for and return the submitted work exception.

A pending exception cannot be synchronously read from an active asyncio loop because doing so would block that loop. Await this object instead.

Parameters
timeout:`float \| None`	Maximum wait time in seconds. Use `None` to wait without a time limit.
Returns
`BaseException \| None`	Exception from the submitted work, or `None` if it completed successfully.
Raises
`concurrent.futures.TimeoutError`	If the time limit expires.
`RuntimeError`	If a pending exception is requested from an active asyncio loop or an SDK-owned executor worker.
`concurrent.futures.CancelledError`	If the submitted work was cancelled. This is the concurrent-future exception, not `asyncio.CancelledError`.

def result(self, timeout: float | None = None) -> T: (source) ¶

Wait for and return the submitted work result.

A pending result cannot be synchronously read from an active asyncio loop because doing so would block that loop. Await this object instead.

Parameters
timeout:`float \| None`	Maximum wait time in seconds. Use `None` to wait without a time limit.
Returns
`T`	Result of the submitted work.
Raises
`concurrent.futures.TimeoutError`	If the time limit expires.
`RuntimeError`	If a pending result is requested from an active asyncio loop or an SDK-owned executor worker.
`concurrent.futures.CancelledError`	If the submitted work was cancelled. This is the concurrent-future exception, not `asyncio.CancelledError`.

@property
event_loop: asyncio.AbstractEventLoop = (source) ¶

Return the event loop for the associated SDK runtime.

@classmethod
def _for_runtime(cls, future: Future[T], event_loop: asyncio.AbstractEventLoop) -> CrossLoopAwaitable[T]: (source) ¶

Create a handle associated with an SDK event loop.

def _add_internal_done_callback(self, callback: Callable[[CrossLoopAwaitable[T]], object]): (source) ¶

Run a lifecycle callback synchronously on future completion.

Internal cleanup must not depend on a caller-owned callback loop that can stop or close independently of the SDK.

Parameters
callback:`Callable[[CrossLoopAwaitable[T]], object]`	Runtime callback that receives this awaitable.

def _cancel_unstarted_threadsafe(self) -> bool: (source) ¶

Cancel this thread-safe handle for an unstarted wrapper.

def _check_process(self): (source) ¶

Reject a handle inherited by a child process before locking.

def _reject_blocking_async_wait(self): (source) ¶

Reject a pending synchronous wait from an active event loop.

def _reject_executor_wait(self): (source) ¶

Reject a pending wait from a worker in any SDK finite pool.

def _result(self, timeout: float | None = None) -> T: (source) ¶

Return the result for a compatibility path that permits blocking.

Internal synchronous SDK adapters use this method after applying their own loop and deadlock rules.

Parameters
timeout:`float \| None`	Maximum wait time in seconds.
Returns
`T`	Submitted work result.

async def _wait(self) -> T: (source) ¶

Wait for the concurrent future from the current event loop.

async def _wait_shielded(self) -> T: (source) ¶

Wait without letting one asyncio waiter cancel shared work.

A private relay copies completion onto the current loop without chaining cancellation back to the shared concurrent future. This is deliberately not implemented with asyncio.shield: newer asyncio versions report a late inner exception when a shielded waiter has already been cancelled. The relay observes that abandoned result while independent waits retain the same shared outcome.

Returns
`T`	Submitted work result.

_event_loop = (source) ¶

Undocumented

_future = (source) ¶

Undocumented

_process_id = (source) ¶

Undocumented

_waiters: dict[object, tuple[weakref.ReferenceType[asyncio.AbstractEventLoop], weakref.ReferenceType[asyncio.Future[T]]]] = (source) ¶

Undocumented

_waiters_lock = (source) ¶

Undocumented