Struct XetRuntime 

pub struct XetRuntime { /* private fields */ }

This module provides a simple wrapper around Tokio’s runtime to create a thread pool with some default settings. It is intended to be used as a singleton thread pool for the entire application.

The ThreadPool struct encapsulates a Tokio runtime and provides methods to run futures to completion, spawn new tasks, and get a handle to the runtime.

Example

use xet_runtime::core::XetRuntime;

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

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

assert_eq!(result, 42);

Panics

The new_threadpool function will intentionally panic if the Tokio runtime cannot be created. This is because the application should not continue running without a functioning thread pool.

Settings

The thread pool is configured with the following settings:

• 4 worker threads
• Thread names prefixed with “hf-xet-”
• 8MB stack size per thread (default is 2MB)
• Maximum of 100 blocking threads
• All Tokio features enabled (IO, Timer, Signal, Reactor)

Structs

• ThreadPool: The main struct that encapsulates the Tokio runtime.

Implementations

impl XetRuntime

pub fn current() -> Arc<Self>

Return the current threadpool that the current worker thread uses. Will fail if
called from a thread that is not spawned from the current runtime.

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

pub fn new() -> Result<Arc<Self>, RuntimeError>

Creates a new runtime with the default configuration.

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

Creates a new runtime with the given configuration.

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

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

Errors

• RuntimeError::InvalidRuntime — the handle lacks multi-thread flavor, time driver, or IO driver.
• RuntimeError::ExternalAlreadyAttached — a live XetRuntime is already registered for this handle (checked inside from_external_with_config).

Not available on WASM targets.

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

Wrap an existing tokio TokioRuntimeHandle with a XetRuntime using the provided XetConfig. No new thread pool is created; spawn() calls will schedule work on the runtime that owns rt_handle.

The resulting XetRuntime is registered in EXTERNAL_RUNTIME_REGISTRY so that XetRuntime::current() called from tasks running on rt_handle’s threads will return this instance (with the correct config and shared XetCommon) rather than a default throwaway. The entry is removed when the last Arc<XetRuntime> is dropped.

Errors

• RuntimeError::ExternalAlreadyAttached — a live XetRuntime is already registered for rt_handle’s tokio runtime ID (i.e. the same handle was wrapped twice while the first is still alive). Drop the existing XetRuntime first, or use a different handle.

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

Wrap an existing tokio TokioRuntimeHandle with a XetRuntime using a default XetConfig. Prefer from_external_with_config when you have a config available.

Unlike from_external_with_config, this function does not register the runtime in EXTERNAL_RUNTIME_REGISTRY and therefore performs no duplicate-handle check. It is intended for lightweight, short-lived wrapping where registry lookup via XetRuntime::current() is not required.

pub fn handle(&self) -> TokioRuntimeHandle

pub fn common(&self) -> &XetCommon

Returns a reference to the shared XetCommon state.

pub fn get_or_create_reqwest_client<F>(tag: String, f: F) -> Result<Client>

where F: FnOnce() -> Result<Client, Error>,

Gets or creates a reqwest client, using a tag to identify the client type.

Arguments

• tag - A string identifier for the client (e.g., “tcp” for regular, socket path for UDS)
• f - A function that creates the client if needed

Returns

Returns a clone of the cached client if the tag matches and we’re in a runtime, or creates a new client otherwise. This allows creating high-level clients outside a runtime, like in tests.

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 self.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 self.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. The task runs with this runtime stored in thread-local storage so XetRuntime::current() works inside f.

The receiver must be an Arc<XetRuntime> so the runtime can be installed in the blocking thread (e.g. rt.spawn_blocking(|| { ... }) where rt: Arc<XetRuntime>).

pub fn config(&self) -> &Arc<XetConfig>

Returns a reference to the primary configuration struct.

pub fn mode(&self) -> RuntimeMode

Returns the runtime mode (Owned or External).

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

Not available on WASM targets (WASM always uses current_thread).

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.