Struct XetRuntime 

pub struct XetRuntime { /* private fields */ }

XetRuntime is the async execution backend: it either owns a Tokio multi-thread runtime or wraps an external TokioRuntimeHandle (see RuntimeMode).

It exposes Self::bridge_async and Self::bridge_sync to run work on the pool, Self::spawn for fire-and-forget tasks, and Self::perform_sigint_shutdown / Self::in_sigint_shutdown so callers can align with process-wide SIGINT teardown.

Example

use xet_runtime::config::XetConfig;
use xet_runtime::core::XetRuntime;

let pool = XetRuntime::new(&XetConfig::new()).expect("Error initializing runtime.");

let result = pool
    .bridge_sync(async {
        // Your async code here
        42
    })
    .expect("Task Error.");

assert_eq!(result, 42);

Implementations

impl XetRuntime

pub fn new(config: &XetConfig) -> Result<Arc<Self>, RuntimeError>

Creates a new owned tokio thread pool with the given configuration.

pub fn from_external_with_config( rt_handle: TokioRuntimeHandle, config: &XetConfig, ) -> Result<Arc<Self>, RuntimeError>

Wraps an existing tokio handle with a new XetRuntime, using the config for system monitor setup.

pub fn from_external(rt_handle: TokioRuntimeHandle) -> Arc<Self>

Wraps an existing tokio handle without system monitoring.

pub fn current_if_exists() -> Option<Arc<Self>>

Returns the current thread’s active owned XetRuntime, if any.

This is populated on owned runtime worker threads and on spawn_blocking threads created by an owned runtime. External runtimes do not set this.

pub fn handle(&self) -> TokioRuntimeHandle

pub fn num_worker_threads(&self) -> usize

pub fn external_executor_count(&self) -> usize

Gives the number of concurrent sync bridge callers (external_run_async_task and bridge_sync).

pub fn perform_sigint_shutdown(&self)

Cancels and shuts down the runtime. All tasks currently running will be aborted.

A concurrent bridge_sync or in-flight bridge_async may still hold a cloned Arc to the tokio runtime until that call returns, so teardown of the reactor may complete only after those finish.

pub fn discard_runtime(&self)

Discards the runtime without shutdown; to be used after fork-exec or spawn.

pub fn in_sigint_shutdown(&self) -> bool

Returns true if we’re in the middle of a sigint shutdown, and false otherwise.

pub fn external_run_async_task<F>( &self, future: F, ) -> Result<F::Output, RuntimeError>

where F: Future + Send + 'static, F::Output: Send + 'static,

This function should ONLY be used by threads outside of tokio; it should not be called from within a task running on the runtime worker pool. Doing so can lead to deadlocking.

pub fn spawn<F>(&self, future: F) -> JoinHandle<F::Output>

where F: Future + Send + 'static, F::Output: Send + 'static,

Spawn an async task to run in the background on the current pool of worker threads.

pub async fn bridge_async<T, F>( &self, task_name: &'static str, fut: F, ) -> Result<T, RuntimeError>

where F: Future<Output = T> + Send + 'static, T: Send + 'static,

Run a future on the appropriate runtime for this XetRuntime.

• External mode: the future is awaited directly on the caller’s executor.
• Owned mode: the future is spawned onto the owned thread pool and the result is delivered via a oneshot channel (compatible with any executor).

This is the primary async entry point. Session-level async methods should call ctx.runtime.bridge_async(...).

pub fn bridge_sync<F>(&self, future: F) -> Result<F::Output, RuntimeError>

where F: Future + Send + 'static, F::Output: Send + 'static,

Run an async future synchronously, blocking the calling thread until completion.

Only supported on Owned runtimes. Returns RuntimeError::InvalidRuntime when called on an External-mode runtime.

The caller must not be on a tokio worker thread (calling from spawn_blocking threads, OS threads, or the main thread is fine).

This is the primary sync entry point. Session-level _blocking methods should simply call ctx.runtime.bridge_sync(...).

pub fn spawn_blocking<F, R>(self: &Arc<Self>, f: F) -> JoinHandle<R>

where F: FnOnce() -> R + Send + 'static, R: Send + 'static,

Spawn a blocking task on the runtime’s blocking thread pool. Installs a weak thread-local reference to this pool for the duration of f.

pub fn mode(&self) -> RuntimeMode

Returns the runtime mode (Owned or External).

pub fn from_validated_external( rt_handle: TokioRuntimeHandle, config: &XetConfig, ) -> Result<Arc<Self>, RuntimeError>

Wraps a caller-provided tokio handle after validating that it meets requirements.

pub fn handle_meets_requirements(handle: &TokioRuntimeHandle) -> bool

Probe whether a tokio runtime handle meets the requirements for use as an External-mode runtime.

Checks:

1. Multi-threaded flavor.
2. Time driver – required for timeouts, retry backoff, and progress intervals.
3. IO driver – required for all network I/O via reqwest/hyper.

Driver availability is probed by entering the handle’s context and polling a driver-dependent future once inside catch_unwind. Tokio panics synchronously on the first poll when a driver is absent, so the result is immediate.

Fragility note: this probing technique relies on tokio panicking synchronously on the first poll of tokio::time::sleep / tokio::net::TcpListener::bind when the corresponding driver is absent. This is undocumented internal behavior validated against tokio 1.x.

Trait Implementations

impl Debug for XetRuntime

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for XetRuntime

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for XetRuntime

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.