# tokio::runtime::Handle - Rust
API documentation for the Rust `Handle` struct in crate `tokio`.
Keywords: rust, rustlang, rust-lang, Handle

# Struct tokio::runtime::Handle [−] [src]

    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` [src]

#### `pub fn enter(&self) -> EnterGuard<'_>` [src]

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` [src]

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>` [src]

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>ⓘ

### Notable traits for JoinHandle<T>

`impl<T> Future for JoinHandle<T> type Output = Result<T, JoinError>;`
where
F: Future + Send + 'static,
F::Output: Send + 'static,` [src]

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>ⓘ

### Notable traits for JoinHandle<T>

`impl<T> Future for JoinHandle<T> type Output = Result<T, JoinError>;`
where
F: FnOnce() -> R + Send + 'static,
R: Send + 'static,` [src]

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

#### `pub fn block_on<F: Future>(&self, future: F) -> F::Output` [src]

Run a future to completion on this `Handle`'s associated `Runtime`.

This runs the given future on the runtime, 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 panics if the provided future panics, if called within an asynchronous execution context, or if 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");
            });
        });
    }

## Trait Implementations

### `impl Clone for Handle` [src]

#### `fn clone(&self) -> Handle` [src]

Returns a copy of the value. Read more

#### `pub fn clone_from(&mut self, source: &Self)`1.0.0 [src]

Performs copy-assignment from `source`. Read more

### `impl Debug for Handle` [src]

#### `fn fmt(&self, f: &mut Formatter<'_>) -> Result` [src]

Formats the value using the given formatter. Read more

## Auto Trait Implementations

### `impl !RefUnwindSafe for Handle` [src]

### `impl Send for Handle` [src]

### `impl Sync for Handle` [src]

### `impl Unpin for Handle` [src]

### `impl !UnwindSafe for Handle` [src]

## Blanket Implementations

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `pub fn type_id(&self) -> TypeId` [src]

Gets the `TypeId` of `self`. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow(&self) -> &Tⓘ

### Notable traits for &'_ mut F

`impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;`
` [src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow_mut(&mut self) -> &mut Tⓘ

### Notable traits for &'_ mut F

`impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;`
` [src]

Mutably borrows from an owned value. Read more

### `impl<T> From<T> for T` [src]

#### `pub fn from(t: T) -> T` [src]

Performs the conversion.

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `pub fn into(self) -> U` [src]

Performs the conversion.

### `impl<T> ToOwned for T where
T: Clone,` [src]

#### `type Owned = T`

The resulting type after obtaining ownership.

#### `pub fn to_owned(&self) -> T` [src]

Creates owned data from borrowed data, usually by cloning. Read more

#### `pub fn clone_into(&self, target: &mut T)` [src]

🔬 This is a nightly-only experimental API. (`toowned_clone_into`)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>` [src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>` [src]

Performs the conversion.