结构体 LocalRuntime

Source

pub struct LocalRuntime { /* private fields */ }

展开描述

一个本地 Tokio 运行时。

此运行时能够驱动那些不是 Send + Sync 的任务，无需使用 LocalSet，因此支持 spawn_local 而不需要 LocalSet 上下文。

此运行时不能在不同的线程之间移动，也不能由不同的线程驱动。

此运行时与 LocalSet 不兼容。你不应尝试在 LocalRuntime 内驱动 LocalSet。

目前，此运行时支持一种类型风格，其内部与 current_thread 相同，除了上述与 spawn_local 相关的差异。

有关如何使用运行时的更多常规信息，请参阅模块文档。

实现§

Source §

impl LocalRuntime

Source

pub fn new() -> Result<LocalRuntime>

使用默认配置值创建一个新的本地运行时实例。

这将初始化调度器、I/O driver 和 time driver。

当需要更复杂的配置时，可以使用运行时 builder。

更多详细信息请参见模块级文档。

§示例

使用默认配置值创建一个新的 LocalRuntime。

use tokio::runtime::LocalRuntime;

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

// Use the runtime...

Source

pub fn handle(&self) -> &Handle

返回运行时 spawner 的句柄。

返回的句柄可用于派生在此运行时上运行的任务，并且可以克隆，以便将 Handle 移动到其他线程。

由于句柄可以发送到其他线程，它只能用于派生 Send 的任务。

在 LocalRuntime 的句柄上调用 Handle::block_on 是容易出错的。更多细节请参考 Handle::block_on 的文档。

§示例

use tokio::runtime::LocalRuntime;

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

let handle = rt.handle();

// Use the handle...

Source

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

在运行时上派生一个任务。

此方法类似于标准 Runtime 上的 spawn 方法，但即使任务不是线程安全的也可以工作。

§示例

use tokio::runtime::LocalRuntime;

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

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

Source

pub fn spawn_blocking<F, R>(&self, func: F) -> JoinHandle<R> ⓘ
where F: FnOnce() -> R + Send + 'static, R: Send + 'static,

在专用阻塞线程池中的某个线程上运行提供的函数。

此函数将在另一个线程上运行。

更多信息请参阅非本地运行时中的文档。

§示例

use tokio::runtime::LocalRuntime;

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

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

Source

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

在 Tokio 运行时上运行一个 future 直到完成。这是运行时的入口点。

更多信息请参阅 Runtime 上的等价方法的文档。

§示例

use tokio::runtime::LocalRuntime;

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

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

Source

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

进入运行时上下文。

这允许你构造创建时必须有可用执行器的类型，例如 Sleep 或 TcpStream。它还允许你调用 tokio::spawn 等方法。

如果这是 LocalRuntime 的句柄，并且此函数是从创建该运行时的同一线程上调用的，你还可以调用 tokio::task::spawn_local。

§Example

use tokio::runtime::LocalRuntime;
use tokio::task::JoinHandle;

fn function_that_spawns(msg: String) -> JoinHandle<()> {
    // Had we not used `rt.enter` below, this would panic.
    tokio::spawn(async move {
        println!("{}", msg);
    })
}

fn main() {
    let rt = LocalRuntime::new().unwrap();

    let s = "Hello World!".to_string();

    // By entering the context, we tie `tokio::spawn` to this executor.
    let _guard = rt.enter();
    let handle = function_that_spawns(s);

    // Wait for the task before we end the test.
    rt.block_on(handle).unwrap();
}

Source

pub fn shutdown_timeout(self, duration: Duration)

关闭运行时，最多等待 duration 时间让所有已派生的工作停止。

请注意，如果超时到期，则 spawn_blocking 任务（且只有 spawn_blocking 任务）可能会被遗留。

更多详细信息请参见结构体级文档。

§示例

use tokio::runtime::LocalRuntime;
use tokio::task;

use std::thread;
use std::time::Duration;

fn main() {
   let runtime = LocalRuntime::new().unwrap();

   runtime.block_on(async move {
       task::spawn_blocking(move || {
           thread::sleep(Duration::from_secs(10_000));
       });
   });

   runtime.shutdown_timeout(Duration::from_millis(100));
}

Source

pub fn shutdown_background(self)

关闭运行时，不等待任何已派生的工作停止。

如果你希望从另一个运行时内部 drop 一个运行时，这非常有用。通常情况下，drop 一个运行时会无限期阻塞，直到已派生的阻塞任务完成，这在异步上下文中通常是不允许的。调用 shutdown_background() 可以从此类上下文中 drop 该运行时。

但请注意，由于我们不会等待任何阻塞任务完成，这可能导致资源泄漏（任何阻塞任务仍在运行，直到它们返回。不会有其他任务泄漏。

更多详细信息请参见结构体级文档。

此函数等效于调用 shutdown_timeout(Duration::from_nanos(0))。

use tokio::runtime::LocalRuntime;

fn main() {
   let runtime = LocalRuntime::new().unwrap();

   runtime.block_on(async move {
       let inner_runtime = LocalRuntime::new().unwrap();
       // ...
       inner_runtime.shutdown_background();
   });
}

Source