Struct Handle

pub struct Handle { /* private fields */ }

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<F, R>(&self, f: F) -> R

where F: FnOnce() -> R,

Enter the runtime context.

pub fn current() -> Handle

Returns a Handle view over the currently running Runtime

Panic

This will panic if called outside the context of a Tokio runtime.

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

pub fn try_current() -> Result<Handle, 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

impl Handle

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.

See module level documentation for more details.

Examples

use tokio::runtime::Runtime;

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

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

Panics

This function panics if the spawn fails. Failure occurs if the executor is currently at capacity and is unable to spawn a new future.

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<(), Error>

Formats the value using the given formatter.