nebius.aio._runtime.AsyncRuntime

class documentation

class AsyncRuntime: (source)

Constructor: AsyncRuntime(event_loop, executor_max_workers, loop_exception_handler)

Run all asynchronous work for one SDK instance.

An owned runtime starts one daemon event-loop thread and an independent daemon executor. A borrowed runtime uses an event loop that the caller supplies. Shutdown does not stop a borrowed loop or manage its default executor. Do not occupy every worker of that executor with synchronous SDK waits. Internal or extension code on the borrowed loop can need the same executor. The SDK cannot reliably identify all executor worker threads.

Method	`__init__`	Initialize an SDK runtime.
Method	`begin_close`	Reject new runtime submissions.
Method	`bridge_awaitable`	Bridge an asyncio future when another loop owns it.
Method	`call_with_context`	Call a function with the SDK runtime context.
Async Method	`cancel_submissions`	Cancel tracked work once and wait for task finalizers.
Method	`in_event_loop`	Return whether the caller runs on this runtime's event loop.
Method	`in_executor_thread`	Return whether the caller runs on any SDK-owned executor.
Method	`mark_current_submission_close_returning`	Mark an internal close caller and limit its continuation.
Method	`mark_current_task_cancelling`	Record cancellation delivered after close protection began.
Method	`protect_current_submission`	Protect the current internal close caller from normal cancellation.
Method	`run_sync`	Run an awaitable and block the calling thread.
Method	`set_borrowed_loop_exception_handler`	Install an exception handler on a running caller-owned loop.
Method	`shutdown`	Stop this runtime and release owned resources.
Method	`shutdown_async`	Start runtime shutdown without blocking the caller.
Method	`submit`	Submit an awaitable to the SDK event loop.
Method	`submit_background`	Submit and track background SDK work.
Property	`event_loop`	Return the event loop that runs SDK work.
Property	`owned`	Return whether this runtime owns its event loop.
Method	`_bridge_foreign_future`	Bridge a future from another event loop.
Method	`_cancel_remaining_tasks`	Cancel and drain tasks before an owned loop closes.
Method	`_cancel_returning_task`	Cancel a close caller only if it yielded after close returned.
Method	`_cancel_task_once`	Request cancellation through one SDK-loop-owned task edge.
Method	`_complete_shutdown`	Publish the retained shutdown result exactly once.
Method	`_discard_background`	Remove completed background work from tracking.
Method	`_discard_protected_task`	Forget protection and captured cancellation state for one task.
Method	`_discard_submission`	Remove a completed submission from runtime tracking.
Method	`_finish_owned_shutdown`	Join the owned loop thread and stop the owned executor.
Method	`_notify_protected_state_change`	Wake SDK-loop shutdown after protected submission state changes.
Async Method	`_prepare_shutdown`	Drain protected close callers and start final shutdown.
Method	`_record_shutdown_failure`	Retain and log the first graceful-shutdown failure.
Method	`_reject_self_submission`	Reject a handle that would indirectly await its own submission.
Async Method	`_run_awaitable`	Run an awaitable with SDK task context and lifecycle tracking.
Method	`_start_borrowed_shutdown_watch`	Finish shutdown if a caller-owned loop stops after dispatch.
Method	`_start_shutdown_preparation_on_loop`	Create graceful-shutdown work after dispatch reaches the loop.
Method	`_start_shutdown_thread`	Start a daemon thread that completes synchronous shutdown.
Method	`_submit_to_loop`	Schedule an awaitable on the SDK event loop.
Method	`_submit_without_disposal`	Admit SDK work without invoking caller cleanup hooks on failure.
Method	`_track_submission`	Track a submission until it is complete.
Instance Variable	`_accepting`	Undocumented
Instance Variable	`_active_tasks`	Undocumented
Instance Variable	`_background`	Undocumented
Instance Variable	`_background_lock`	Undocumented
Instance Variable	`_close_returning_submissions`	Undocumented
Instance Variable	`_executor`	Undocumented
Instance Variable	`_loop`	Undocumented
Instance Variable	`_loop_thread`	Undocumented
Instance Variable	`_owned`	Undocumented
Instance Variable	`_process_id`	Undocumented
Instance Variable	`_protected_cancelling_tasks`	Undocumented
Instance Variable	`_protected_state_changed`	Undocumented
Instance Variable	`_protected_submissions`	Undocumented
Instance Variable	`_protected_tasks`	Undocumented
Instance Variable	`_shutdown`	Undocumented
Instance Variable	`_shutdown_complete`	Undocumented
Instance Variable	`_shutdown_dispatch_abandoned`	Undocumented
Instance Variable	`_shutdown_failure`	Undocumented
Instance Variable	`_shutdown_lock`	Undocumented
Instance Variable	`_shutdown_prepare_lock`	Undocumented
Instance Variable	`_shutdown_preparing`	Undocumented
Instance Variable	`_submissions`	Undocumented
Instance Variable	`_submissions_lock`	Undocumented
Instance Variable	`_task_cancellation_requested`	Undocumented
Instance Variable	`_task_submissions`	Undocumented

def __init__(self, event_loop: asyncio.AbstractEventLoop | None, executor_max_workers: int, loop_exception_handler: LoopExceptionHandler | None = None): (source) ¶

Initialize an SDK runtime.

Parameters
event_loop:`asyncio.AbstractEventLoop \| None`	Running caller-owned loop to use. Use `None` to create an owned loop.
executor_max_workers:`int`	Number of daemon executor workers for an owned loop. A borrowed loop ignores this value.
loop_exception_handler:`LoopExceptionHandler \| None`	Optional asyncio exception handler to install on the SDK event loop. A borrowed loop retains the handler after runtime shutdown because the caller owns that loop.
Raises
`ValueError`	If a supplied loop is not running, or if an owned executor size is not positive.
`TypeError`	If `loop_exception_handler` is not a synchronous callable.
`RuntimeError`	If a borrowed loop stops or does not install the exception handler before the time limit.

def begin_close(self): (source) ¶

Reject new runtime submissions.

def bridge_awaitable(self, awaitable: Awaitable[T]) -> Awaitable[T]: (source) ¶

Bridge an asyncio future when another loop owns it.

Parameters
awaitable:`Awaitable[T]`	Awaitable to examine.
Returns
`Awaitable[T]`	The original awaitable or a cross-loop awaitable.

def call_with_context(self, callable_: Callable[..., T], *args: Any, **kwargs: Any) -> T: (source) ¶

Call a function with the SDK runtime context.

The method temporarily binds the current execution context to this runtime. Code called by callable_ can use the active task scheduler and awaitable bridge without a process-wide runtime variable. A task created during the call receives a copy of these bindings by default.

The context tokens restore any previous bindings after the call. Retained bindings keep this runtime alive until the copied context is released. A raw child task is not automatically tracked for shutdown; the callback must use the active scheduler for tracked SDK work. Creating a bare coroutine does not retain the context. The coroutine uses the context of the task that eventually runs it.

Parameters
callable_:`Callable[..., T]`	Function to call.
*args:`Any`	Positional arguments for `callable_`.
**kwargs:`Any`	Keyword arguments for `callable_`.
Returns
`T`	Result of `callable_`.

async def cancel_submissions(self): (source) ¶

Cancel tracked work once and wait for task finalizers.

This method does not cancel protected internal close callers. It cancels active SDK work through one private task-cancellation edge. Recording every request before tasks resume prevents parent-to-child propagation from injecting a second cancellation into an asynchronous finalizer. Public handles remain pending until their task publishes an outcome, which preserves native RPC results that won the close race.

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

Return whether the caller runs on this runtime's event loop.

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

Return whether the caller runs on any SDK-owned executor.

def mark_current_submission_close_returning(self): (source) ¶

Mark an internal close caller and limit its continuation.

The caller can finish its current task step after close() returns. A callback on the next loop turn cancels it only if it yielded again. This explicit scheduling avoids depending on ready-queue ordering between the caller and runtime shutdown.

def mark_current_task_cancelling(self): (source) ¶

Record cancellation delivered after close protection began.

Python 3.10 does not expose asyncio.Task.cancelling. A task can therefore receive cancellation after protect_current_submission first inspected it without leaving any public cancellation counter. Close catches that cancellation while it is visible and calls this method so shutdown does not interrupt the task's asynchronous finalizer with a second cancellation.

def protect_current_submission(self) -> CrossLoopAwaitable[Any] | None: (source) ¶

Protect the current internal close caller from normal cancellation.

Returns
`CrossLoopAwaitable[Any] \| None`	Current submission, or `None` if the caller is not a runtime submission.

def run_sync(self, awaitable: Awaitable[T], timeout: float | None = None) -> T: (source) ¶

Run an awaitable and block the calling thread.

Parameters
awaitable:`Awaitable[T]`	Work to run.
timeout:`float \| None`	Maximum wait time in seconds. Use `None` to wait without a time limit.
Returns
`T`	Result of `awaitable`.
Raises
`RuntimeError`	If the caller runs on the SDK event loop.
`TimeoutError`	If the time limit expires.

def set_borrowed_loop_exception_handler(self, handler: LoopExceptionHandler): (source) ¶

Install an exception handler on a running caller-owned loop.

The handler is loop-wide. The runtime does not restore an earlier handler during shutdown because the supplied loop remains under caller ownership and another component may replace the handler later.

Parameters
handler:`LoopExceptionHandler`	Asyncio exception handler to install.
Raises
`TypeError`	If `handler` is not a synchronous callable.
`RuntimeError`	If the supplied loop stops or does not install the handler before the time limit.

def shutdown(self): (source) ¶

Stop this runtime and release owned resources.

This method is safe to call more than once. Finalization stops and joins an owned loop thread. A call from that loop starts a daemon finalizer thread and returns before the join completes. The method does not stop a borrowed event loop.

def shutdown_async(self) -> CrossLoopAwaitable[None]: (source) ¶

Start runtime shutdown without blocking the caller.

Each call returns an independent result handle. Cancelling one caller's handle does not cancel the runtime-wide shutdown completion used by later callers.

Returns
`CrossLoopAwaitable[None]`	Cross-loop awaitable that completes after shutdown.

def submit(self, awaitable: Awaitable[T], *, track: bool = True) -> CrossLoopAwaitable[T]: (source) ¶

Submit an awaitable to the SDK event loop.

The returned object can be awaited from any event loop. If awaitable is a future from a different loop, this method creates a completion bridge.

Parameters
awaitable:`Awaitable[T]`	Work to run.
track:`bool`	Track the submission for cancellation during close. Set this value to `False` only for shutdown work that the runtime must protect.
Returns
`CrossLoopAwaitable[T]`	Cross-loop awaitable for the result.
Raises
`RuntimeError`	If runtime close has started.

def submit_background(self, awaitable: Awaitable[T]) -> CrossLoopAwaitable[T]: (source) ¶

Submit and track background SDK work.

Parameters
awaitable:`Awaitable[T]`	Background work to run.
Returns
`CrossLoopAwaitable[T]`	Cross-loop awaitable for the result.

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

Return the event loop that runs SDK work.

@property
owned: bool = (source) ¶

Return whether this runtime owns its event loop.

def _bridge_foreign_future(self, source: asyncio.Future[T], owner_loop: asyncio.AbstractEventLoop) -> CrossLoopAwaitable[T]: (source) ¶

Bridge a future from another event loop.

The bridge copies completion to a concurrent future. Cancellation of the bridge is sent to the source loop. Every source operation, including terminal-state inspection, runs on that owning loop. The owner must therefore remain running even when the source is already complete; otherwise the bridge fails promptly without inspecting it.

Parameters
source:`asyncio.Future[T]`	Future to bridge.
owner_loop:`asyncio.AbstractEventLoop`	Event loop that owns `source`.
Returns
`CrossLoopAwaitable[T]`	Cross-loop awaitable for the source result.

def _cancel_remaining_tasks(self): (source) ¶

Cancel and drain tasks before an owned loop closes.

def _cancel_returning_task(self, task: asyncio.Task[Any]): (source) ¶

Cancel a close caller only if it yielded after close returned.

Parameters
task:`asyncio.Task[Any]`	Protected SDK-loop task that returned from `close()`.

def _cancel_task_once(self, task: asyncio.Task[Any]): (source) ¶

Request cancellation through one SDK-loop-owned task edge.

A public handle cancellation and runtime shutdown can race to cancel the same task. Recording the request on the SDK loop prevents the later edge from injecting another CancelledError while the task is executing an asynchronous finalizer. Runtime shutdown does not cancel the public concurrent future here. A terminal native RPC can still absorb task cancellation and publish its result.

Parameters
task:`asyncio.Task[Any]`	SDK-loop task to cancel.

def _complete_shutdown(self): (source) ¶

Publish the retained shutdown result exactly once.

def _discard_background(self, submitted: CrossLoopAwaitable[Any]): (source) ¶

Remove completed background work from tracking.

Parameters
submitted:`CrossLoopAwaitable[Any]`	Completed background submission.

def _discard_protected_task(self, task: asyncio.Task[Any]): (source) ¶

Forget protection and captured cancellation state for one task.

def _discard_submission(self, submitted: CrossLoopAwaitable[Any]): (source) ¶

Remove a completed submission from runtime tracking.

Parameters
submitted:`CrossLoopAwaitable[Any]`	Completed submission to remove.

def _finish_owned_shutdown(self): (source) ¶

Join the owned loop thread and stop the owned executor.

def _notify_protected_state_change(self): (source) ¶

Wake SDK-loop shutdown after protected submission state changes.

async def _prepare_shutdown(self): (source) ¶

Drain protected close callers and start final shutdown.

A protected caller can run its immediate continuation after nebius.aio.channel.Channel.close returns. The runtime cancels the caller if that continuation waits again. The runtime does not cancel a caller that already received external cancellation.

def _record_shutdown_failure(self, error: BaseException): (source) ¶

Retain and log the first graceful-shutdown failure.

Parameters
error:`BaseException`	Failure raised while draining runtime resources.

def _reject_self_submission(self, awaitable: Awaitable[object]): (source) ¶

Reject a handle that would indirectly await its own submission.

Rejection deliberately does not dispose the handle: it represents the currently running submission rather than new, unowned work.

Parameters
awaitable:`Awaitable[object]`	Candidate SDK work.
Raises
`RuntimeError`	If the current submission resubmits its own pending handle.

async def _run_awaitable(self, awaitable: Awaitable[T], *, protect_task: bool = False) -> T: (source) ¶

Run an awaitable with SDK task context and lifecycle tracking.

The method binds task_scheduler and awaitable_bridge to this runtime before it awaits the submitted work. Context variables retain these bound methods across suspension points. By default, a child asyncio task also receives a copy of the context that exists when code creates the child.

The finally block restores the previous bindings with context tokens. This restoration supports nested runtime calls in the same context. Context isolation prevents one SDK task from replacing another task's bindings.

Context inheritance does not add a raw child task to _active_tasks. On a caller-supplied loop, such a task can outlive SDK close. Final shutdown of an SDK-owned loop cancels remaining tasks, including untracked tasks. SDK code must use the bound scheduler when normal SDK shutdown tracking must include the child task. The bridge can also detect only explicit asyncio.Future loop ownership. It cannot make an arbitrary loop-affine custom awaitable loop-independent.

Parameters
awaitable:`Awaitable[T]`	Work to run.
protect_task:`bool`	Protect the current task from normal submission cancellation.
Returns
`T`	Result of `awaitable`.

def _start_borrowed_shutdown_watch(self): (source) ¶

Finish shutdown if a caller-owned loop stops after dispatch.

A supplied loop remains caller-owned and must stay running until SDK close completes. It can nevertheless stop after accepting the preparation callback. A daemon monitor converts that otherwise permanent pending state into the same synchronous best-effort cleanup used when shutdown begins after the loop has already stopped. The monitor never stops or closes the supplied loop.

def _start_shutdown_preparation_on_loop(self): (source) ¶

Create graceful-shutdown work after dispatch reaches the loop.

Deferring coroutine creation avoids retaining an unawaited coroutine when an accepted callback is left in the ready queue as the loop stops. An owned loop's thread finalizer detects that case and starts synchronous fallback shutdown.

def _start_shutdown_thread(self): (source) ¶

Start a daemon thread that completes synchronous shutdown.

def _submit_to_loop(self, awaitable: Awaitable[T], *, protect_task: bool = False, track: bool = True) -> CrossLoopAwaitable[T]: (source) ¶

Schedule an awaitable on the SDK event loop.

Parameters
awaitable:`Awaitable[T]`	Work to schedule.
protect_task:`bool`	Protect the asyncio task from normal submission cancellation.
track:`bool`	Add the public handle to runtime tracking before the task can start.
Returns
`CrossLoopAwaitable[T]`	Cross-loop awaitable for the result.

def _submit_without_disposal(self, awaitable: Awaitable[T], *, track: bool = True) -> CrossLoopAwaitable[T]: (source) ¶

Admit SDK work without invoking caller cleanup hooks on failure.

Callers use this primitive while they hold a lifecycle admission lock. They must dispose rejected work after releasing that lock. Process and self-submission validation must already be complete.

Parameters
awaitable:`Awaitable[T]`	Work to schedule.
track:`bool`	Track the submission for normal close cancellation.
Returns
`CrossLoopAwaitable[T]`	Cross-loop awaitable for the result.
Raises
`RuntimeError`	If the runtime is closing or its loop stopped.