Struct TokioRuntimeHandle 

pub struct TokioRuntimeHandle(pub Handle);

A reference to a tokio::runtime::Handle, allowing you to spawn Tokio tasks inside of ECS systems.

There are times in which you may want to use something like tokio::spawn inside of an ECS system, but you don’t want to bother with message passing or Bevy’s AsyncComputeTaskPool. Bevy doesn’t run systems inside of a Tokio runtime, which results in an error if you try to use tokio::spawn or tokio::task::spawn_local. However, if you have a reference to a Handle, then Tokio will let you use it to spawn new tasks. This Resource exists for that – it simply gives you a handle to a Tokio runtime to do whatever you want with.

fn example(rt: Res<azalea::TokioRuntimeHandle>) {
    rt.spawn(async {
        // ...
    });
}

Tuple Fields

0: Handle

Methods from Deref<Target = Handle>

pub fn enter(&self) -> EnterGuard<'_>

Enters the runtime context. This allows you to construct types that must have an executor available on creation such as Sleep or TcpStream. It will also allow you to call methods such as tokio::spawn and [Handle::current] without panicking.

Panics

When calling Handle::enter multiple times, the returned guards must be dropped in the reverse order that they were acquired. Failure to do so will result in a panic and possible memory leaks.

Examples

use tokio::runtime::Runtime;

let rt = Runtime::new().unwrap();

let _guard = rt.enter();
tokio::spawn(async {
    println!("Hello world!");
});

Do not do the following, this shows a scenario that will result in a panic and possible memory leak.

use tokio::runtime::Runtime;

let rt1 = Runtime::new().unwrap();
let rt2 = Runtime::new().unwrap();

let enter1 = rt1.enter();
let enter2 = rt2.enter();

drop(enter1);
drop(enter2);

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

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

Spawns a future onto the Tokio runtime.

This spawns the given future onto the runtime’s executor, usually a thread pool. The thread pool is then responsible for polling the future until it completes.

The provided future will start running in the background immediately when spawn is called, even if you don’t await the returned JoinHandle (assuming that the runtime is running).

See module level documentation for more details.

Examples

use tokio::runtime::Runtime;

// Create the runtime
let rt = Runtime::new().unwrap();
// Get a handle from this runtime
let handle = rt.handle();

// Spawn a future onto the runtime using the handle
handle.spawn(async {
    println!("now running on a worker thread");
});

pub fn spawn_blocking<F, R>(&self, func: F) -> JoinHandle<R>

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

Runs the provided function on an executor dedicated to blocking operations.

Examples

use tokio::runtime::Runtime;

// Create the runtime
let rt = Runtime::new().unwrap();
// Get a handle from this runtime
let handle = rt.handle();

// Spawn a blocking function onto the runtime using the handle
handle.spawn_blocking(|| {
    println!("now running on a worker thread");
});

pub fn block_on<F>(&self, future: F) -> <F as Future>::Output

where F: Future,

Runs a future to completion on this Handle’s associated Runtime.

This runs the given future on the current thread, blocking until it is complete, and yielding its resolved result. Any tasks or timers which the future spawns internally will be executed on the runtime.

When this is used on a current_thread runtime, only the Runtime::block_on method can drive the IO and timer drivers, but the Handle::block_on method cannot drive them. This means that, when using this method on a current_thread runtime, anything that relies on IO or timers will not work unless there is another thread currently calling Runtime::block_on on the same runtime.

If the runtime has been shut down

If the Handle’s associated Runtime has been shut down (through Runtime::shutdown_background, Runtime::shutdown_timeout, or by dropping it) and Handle::block_on is used it might return an error or panic. Specifically IO resources will return an error and timers will panic. Runtime independent futures will run as normal.

Panics

This function will panic if any of the following conditions are met:

• The provided future panics.
• It is called from within an asynchronous context, such as inside Runtime::block_on, Handle::block_on, or from a function annotated with tokio::main.
• A timer future is executed on a runtime that has been shut down.

Examples

use tokio::runtime::Runtime;

// Create the runtime
let rt  = Runtime::new().unwrap();

// Get a handle from this runtime
let handle = rt.handle();

// Execute the future, blocking the current thread until completion
handle.block_on(async {
    println!("hello");
});

Or using Handle::current:

use tokio::runtime::Handle;

#[tokio::main]
async fn main () {
    let handle = Handle::current();
    std::thread::spawn(move || {
        // Using Handle::block_on to run async code in the new thread.
        handle.block_on(async {
            println!("hello");
        });
    });
}

Handle::block_on may be combined with task::block_in_place to re-enter the async context of a multi-thread scheduler runtime:

use tokio::task;
use tokio::runtime::Handle;

task::block_in_place(move || {
    Handle::current().block_on(async move {
        // do something async
    });
});

pub fn runtime_flavor(&self) -> RuntimeFlavor

Returns the flavor of the current Runtime.

Examples

use tokio::runtime::{Handle, RuntimeFlavor};

#[tokio::main(flavor = "current_thread")]
async fn main() {
  assert_eq!(RuntimeFlavor::CurrentThread, Handle::current().runtime_flavor());
}

use tokio::runtime::{Handle, RuntimeFlavor};

#[tokio::main(flavor = "multi_thread", worker_threads = 4)]
async fn main() {
  assert_eq!(RuntimeFlavor::MultiThread, Handle::current().runtime_flavor());
}

pub fn id(&self) -> Id

Returns the Id of the current Runtime.

Examples

use tokio::runtime::Handle;

#[tokio::main(flavor = "current_thread")]
async fn main() {
  println!("Current runtime id: {}", Handle::current().id());
}

pub fn name(&self) -> Option<&str>

Returns the name of the current Runtime.

Examples

use tokio::runtime::Handle;

#[tokio::main(flavor = "current_thread", name = "my-runtime")]
async fn main() {
  println!("Current runtime name: {}", Handle::current().name().unwrap());
}

pub fn metrics(&self) -> RuntimeMetrics

Returns a view that lets you get information about how the runtime is performing.

Trait Implementations

impl Deref for TokioRuntimeHandle

type Target = Handle

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Resource for TokioRuntimeHandle

where Self: Send + Sync + 'static,