Skip to main content

AsyncRuntime

orb

Trait AsyncRuntime 

Source 
pub trait AsyncRuntime:
    AsyncIO
    + AsyncTime
    + 'static
    + Send
    + Sync {
    type Exec: AsyncExec;

    // Required methods
    fn current() -> Self::Exec;
    fn one() -> Self::Exec;
    fn multi(num: usize) -> Self::Exec;
    fn spawn<F, R>(f: F) -> <Self::Exec as AsyncExec>::AsyncJoiner<R>
       where F: Future<Output = R> + Send + 'static,
             R: Send + 'static;
    fn spawn_detach<F, R>(f: F)
       where F: Future<Output = R> + Send + 'static,
             R: Send + 'static;
    fn spawn_blocking<F, R>(f: F) -> <Self::Exec as AsyncExec>::ThreadJoiner<R>
       where F: FnOnce() -> R + Send + 'static,
             R: Send + 'static;
}
Expand description

A marker trait that combines all the core async runtime capabilities, including AsyncIO, and AsyncTime. It serves as a convenient way to specify that a type provides all the core async runtime functionality.

You can write your own trait by inheriting AsyncRuntime or any other trait, to provide extra functions along with the runtime object. There’s an blanket trait to auto impl AsyncRuntime on anything that is Deref<Target> to an AsyncRuntime.

Required Associated Types§

Source

type Exec: AsyncExec

Required Methods§

Source

fn current() -> Self::Exec

Initiate executor using current thread.

§Safety

You should run AsyncExec::block_on() with this executor.

If spawn without a block_on() running, it’s possible the runtime just init future without scheduling.

Source

fn one() -> Self::Exec

Initiate executor with one background thread.

§NOTE

AsyncExec::block_on() is optional, you can directly call AsyncExec::spawn with it.

Source

fn multi(num: usize) -> Self::Exec

Initiate executor with multiple background threads.

§NOTE

When num == 0, start threads that match cpu number.

AsyncExec::block_on() is optional, you can directly call AsyncExec::spawn with it.

Source

fn spawn<F, R>(f: F) -> <Self::Exec as AsyncExec>::AsyncJoiner<R>
where F: Future<Output = R> + Send + 'static, R: Send + 'static,

Spawn a task with Self::Exec in the thread context, returning a handle to await its result.

This method creates a new task that runs concurrently with the current task. The returned handle can be used to wait for the task’s completion and retrieve its result.

§NOTE:

The return AsyncJoiner adopts the behavior of tokio.

The behavior of panic varies for runtimes:

  • tokio will capture handle to task result,
  • async-executor (smol) will not capture panic, the program will exit
§Type Parameters
  • F - The future type to spawn
  • R - The return type of the future
§Parameters
  • f - The future to spawn
§Returns

A handle that implements AsyncJoiner and can be used to await the task’s result.

§Panic

Panic when not called in the runtime worker context.

Source

fn spawn_detach<F, R>(f: F)
where F: Future<Output = R> + Send + 'static, R: Send + 'static,

Spawn a task with Self::Exec in the thread context, and detach it (no handle returned).

This method creates a new task that runs in the background without providing a way to wait for its completion. The task will continue running until it completes or the program exits.

§NOTE:

The behavior of panic varies for runtimes:

  • tokio will ignore other tasks panic after detached,
  • async-executor (smol) will not capture panic by default, the program will exit. There’s a feature switch in orb-smol to change this behavior.
§Type Parameters
  • F - The future type to spawn
  • R - The return type of the future
§Parameters
  • f - The future to spawn
§Panic

Panic when not called in the runtime worker context.

Source

fn spawn_blocking<F, R>(f: F) -> <Self::Exec as AsyncExec>::ThreadJoiner<R>
where F: FnOnce() -> R + Send + 'static, R: Send + 'static,

Run blocking code with the thread context in blocking thread pool, and return an async join handle

§NOTE:

This method spawn with threal pool provide by runtime in current context, globally. In order for ResolveAddr job which does not have a AsyncExec handle, so this method is static.

§Type Parameters
  • F - The future type to spawn
  • R - The return type of the future
§Parameters
  • f - The future to spawn
§Returns

A handle that implements ThreadJoiner and can be used to await the call result.

§Panic

Panic when not called in the runtime worker context.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§