Struct tokio::runtime::Handle

pub struct Handle { /* fields omitted */ }

Handle to the runtime.

The handle is internally reference-counted and can be freely cloned. A handle can be obtained using the Runtime::handle method.

Implementations

impl Handle

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

Enter 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.

pub fn current() -> Self

Returns a Handle view over the currently running Runtime

Panic

This will panic if called outside the context of a Tokio runtime. That means that you must call this on one of the threads being run by the runtime. Calling this from within a thread created by std::thread::spawn (for example) will cause a panic.

Examples

This can be used to obtain the handle of the surrounding runtime from an async block or function running on that runtime.

use tokio::runtime::Handle;

// Inside an async block or function.
let handle = Handle::current();
handle.spawn(async {
    println!("now running in the existing Runtime");
});

thread::spawn(move || {
    // Notice that the handle is created outside of this thread and then moved in
    handle.spawn(async { /* ... */ })
    // This next line would cause a panic
    // let handle2 = Handle::current();
});

pub fn try_current() -> Result<Self, TryCurrentError>

Returns a Handle view over the currently running Runtime

Returns an error if no Runtime has been started

Contrary to current, this never panics

pub fn spawn<F>(&self, future: F) -> JoinHandle<F::Output> where
    F: Future + Send + 'static,
    F::Output: Send + 'static, 

Spawn 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.

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, 

Run 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");
});

Trait Implementations

impl Clone for Handle

fn clone(&self) -> Handle

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Handle

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

Formats the value using the given formatter.