Function block_in_place

pub fn block_in_place<F, R>(f: F) -> R
where
    F: FnOnce() -> R,

Runs the provided blocking function on the current thread without blocking the executor.

In general, issuing a blocking call or performing a lot of compute in a future without yielding is problematic, as it may prevent the executor from driving other tasks forward. Calling this function informs the executor that the currently executing task is about to block the thread, so the executor is able to hand off any other tasks it has to a new worker thread before that happens. See the CPU-bound tasks and blocking code section for more information.

Be aware that although this function avoids starving other independently spawned tasks, any other code running concurrently in the same task will be suspended during the call to block_in_place. This can happen e.g. when using the join! macro. To avoid this issue, use spawn_blocking instead of block_in_place.

Note that this function cannot be used within a current_thread runtime because in this case there are no other worker threads to hand off tasks to. On the other hand, calling the function outside a runtime is allowed. In this case, block_in_place just calls the provided closure normally.

Code running behind block_in_place cannot be cancelled. When you shut down the executor, it will wait indefinitely for all blocking operations to finish. You can use shutdown_timeout to stop waiting for them after a certain timeout. Be aware that this will still not cancel the tasks — they are simply allowed to keep running after the method returns.

Examples

use tokio::task;

task::block_in_place(move || {
    // do some compute-heavy work or call synchronous code
});

Code running inside block_in_place may use block_on to reenter the async context.

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

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

Panics

This function panics if called from a current_thread runtime.