tokio

# 使用 full feature
tokio = { version = "1", features = ["full"] }

# 或单独启用各个 feature
tokio = { version = "1", features = ["rt", "net"] }

[build]
rustflags = ["--cfg", "tokio_unstable"]

// Multi-threaded runtime
#[tokio::main(flavor = "multi_thread", worker_threads = 10)]
#[tokio::main(worker_threads = 2)]

// Current thread runtime
#[tokio::main(flavor = "current_thread")]
#[tokio::main(flavor = "current_thread", start_paused = true)]

// 示例
#[tokio::main]
async fn main() {
    println!("Hello world");
}

// 等效为
fn main() {
    tokio::runtime::Builder::new_multi_thread()
        .enable_all()
        .build()
        .unwrap()
        .block_on(async {
            println!("Hello world");
        })
}

async fn do_stuff_async() {}
async fn more_async_work() {}

#[tokio::main]
async fn main() {
    let (first, second) = tokio::join!(
        do_stuff_async(),
        more_async_work());
}

use tokio::{pin, select};
use tokio_stream::{self as stream, StreamExt};

async fn my_async_fn() {}

#[tokio::main]
async fn main() {
    let mut stream = stream::iter(vec![1, 2, 3, 4]); // 从可迭代对象创建一个 async stream。

    let future = my_async_fn();
    pin!(future);

    // select! 宏在执行某个 branch 时会 cancel/drop 其它 branch 的 Future 对象，为了能在 loop 中使
    // 用 select!, 需要传入 &mut future 而非 future 对象本身（防止被 drop）。
    loop {
        select! {
            _ = &mut future => {
                break;
            }

            Some(val) = stream.next() => { // drop 的是 next() 返回的 future 对象而非 stream
                println!("got value = {}", val);
            }
        }
    }
}

// 同时创建多一个 Future 的 Pin 类型
#[tokio::main]
async fn main() {
    pin! {
        let future1 = my_async_fn();
        let future2 = my_async_fn();
    }

    select! {
        _ = &mut future1 => {}
        _ = &mut future2 => {}
    }
}

<pattern> = <async expression> (, if <precondition>)? => <handler>,

async fn do_stuff_async() { }
async fn more_async_work() {}

#[tokio::main]
async fn main() {
    tokio::select! {
        _ = do_stuff_async() => {
            println!("do_stuff_async() completed first")
        }

        _ = more_async_work() => {
            println!("more_async_work() completed first")
        }
    };
}

tokio::task_local! {
    pub static ONE: u32;
    static TWO: f32;
}

tokio::task_local! {
    static NUMBER: u32;
}

NUMBER.scope(1, async move {
    assert_eq!(NUMBER.get(), 1);
}).await;

NUMBER.scope(2, async move {
    assert_eq!(NUMBER.get(), 2);

    NUMBER.scope(3, async move {
        assert_eq!(NUMBER.get(), 3);
    }).await;
}).await;

#[tokio::main]
async fn main() {
    println!("Hello world");
}
// 等效为
fn main() {
    tokio::runtime::Builder::new_multi_thread()
        .enable_all() // 启用所有 resource driver（IO/timer）
        .build()
        .unwrap()
        .block_on(async {
            println!("Hello world");
        })
}

// 另一个例子，手动创建 Runtime
use tokio::net::TcpListener;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::runtime::Runtime;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建一个 multi thread 和 enable all 的 Runtime
    let rt  = Runtime::new()?;
    rt.block_on(async {
        let listener = TcpListener::bind("127.0.0.1:8080").await?;
        loop {
            let (mut socket, _) = listener.accept().await?;
            tokio::spawn(async move {
                let mut buf = [0; 1024];
                loop {
                    let n = match socket.read(&mut buf).await {
                        // socket closed
                        Ok(n) if n == 0 => return,
                        Ok(n) => n,
                        Err(e) => {
                            println!("failed to read from socket; err = {:?}", e);
                            return;
                        }
                    };
                    if let Err(e) = socket.write_all(&buf[0..n]).await {
                        println!("failed to write to socket; err = {:?}", e);
                        return;
                    }
                }
            });
        }
    })
}

impl Runtime

// 创建一个多线程的调度器 Runtime，启用所有默认 resource driver，一般使用 #[tokio::main] 来自动调用。
pub fn new() -> Result<Runtime>

// 返回一个实现了引用计数的 Handle 对象，可以 spawn() 任务，将 Runtime 在多个 thread 间共享。
pub fn handle(&self) -> &Handle

// 在 worker thread pool 中立即运行 async task，而不管是否 await 返回的 JoinHandle
pub fn spawn<F>(&self, future: F) -> JoinHandle<F::Output>
where
    F: Future + Send + 'static, // 对线程 Runtime 要求传入的 feture 必须是 Send + 'static
    F::Output: Send + 'static

// 提交同步任务
pub fn spawn_blocking<F, R>(&self, func: F) -> JoinHandle<R>
where
    F: FnOnce() -> R + Send + 'static,
    R: Send + 'static

// 执行 future，直到结束。对于多线程 Runtime，当 block_on 返回时，spawn() 的 task 可能还在运行，如
// 果要确保这些task 完成，可以进行 .await.
pub fn block_on<F: Future>(&self, future: F) -> F::Output

// 设置 thread local Runtime，后续可以使用 tokio::spawn() 等函数(它们感知 EnterGuard)
pub fn enter(&self) -> EnterGuard<'_>

// 关闭 Runtime，不能再提交任务和 IO/Timer
pub fn shutdown_timeout(self, duration: Duration)
pub fn shutdown_background(self)

impl Runtime
// Available on tokio_unstable only.
pub fn metrics(&self) -> RuntimeMetrics

use tokio::runtime::Runtime;
use tokio::task::JoinHandle;

fn function_that_spawns(msg: String) -> JoinHandle<()> {
    // tokio::spawn 感知所在线程的 EnterGuard 对象
    tokio::spawn(async move {
        println!("{}", msg);
    })
}

fn main() {
    // 手动创建 Runtime
    let rt = Runtime::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);

    rt.block_on(handle).unwrap();
}

use tokio::runtime::Runtime;
use tokio::task;

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

fn main() {
    let runtime = Runtime::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));
}

use tokio::runtime::Handle;

#[tokio::main]
async fn main () {
    let handle = Handle::current();

    // 创建一个 std 线程
    std::thread::spawn(move || {
        // Using Handle::block_on to run async code in the new thread.
        handle.block_on(async {
            println!("hello");
        });
    });
}

use tokio::runtime::Builder;

fn main() {
    let runtime = Builder::new_multi_thread()
        .worker_threads(4)
        .thread_name("my-custom-name")
        .thread_stack_size(3 * 1024 * 1024)
        .build()
        .unwrap();
    // use runtime ...
}

impl Builder
pub fn new_current_thread() -> Builder
pub fn new_multi_thread() -> Builder
pub fn new_multi_thread_alt() -> Builder

// 启用所有 resource driver，如 io/net/timer 等
pub fn enable_all(&mut self) -> &mut Self
// 默认为 CPU Core 数量，会覆盖环境变量 TOKIO_WORKER_THREADS 值。一次性创建。
pub fn worker_threads(&mut self, val: usize) -> &mut Self

// blocking 线程池中线程数量，按需创建，idle 超过一定时间后被回收
pub fn max_blocking_threads(&mut self, val: usize) -> &mut Self
// blocking 线程池中线程空闲时间，默认 10s
pub fn thread_keep_alive(&mut self, duration: Duration) -> &mut Self

pub fn thread_name(&mut self, val: impl Into<String>) -> &mut Self
pub fn thread_name_fn<F>(&mut self, f: F) -> &mut Self where F: Fn() -> String + Send + Sync + 'static
pub fn thread_stack_size(&mut self, val: usize) -> &mut Self

pub fn on_thread_start<F>(&mut self, f: F) -> &mut Self where F: Fn() + Send + Sync + 'static
pub fn on_thread_stop<F>(&mut self, f: F) -> &mut Self where F: Fn() + Send + Sync + 'static
pub fn on_thread_park<F>(&mut self, f: F) -> &mut Self where F: Fn() + Send + Sync + 'static
pub fn on_thread_unpark<F>(&mut self, f: F) -> &mut Self where F: Fn() + Send + Sync + 'static

// 构建生成 Runtime
pub fn build(&mut self) -> Result<Runtime>

// 检查 global queue event 的 scheduler ticks
pub fn global_queue_interval(&mut self, val: u32) -> &mut Self
// 检查 event 的 scheduler ticks
pub fn event_interval(&mut self, val: u32) -> &mut Self

// Available on tokio_unstable only.
pub fn unhandled_panic(&mut self, behavior: UnhandledPanic) -> &mut Self
// Available on tokio_unstable only.
pub fn disable_lifo_slot(&mut self) -> &mut Self
// Available on tokio_unstable only.
pub fn rng_seed(&mut self, seed: RngSeed) -> &mut Self
// Available on tokio_unstable only.
pub fn enable_metrics_poll_count_histogram(&mut self) -> &mut Self
pub fn metrics_poll_count_histogram_scale( &mut self, histogram_scale: HistogramScale ) -> &mut Self
pub fn metrics_poll_count_histogram_resolution( &mut self, resolution: Duration) -> &mut Self
pub fn metrics_poll_count_histogram_buckets( &mut self, buckets: usize ) -> &mut Self

impl Builder
// Available on crate feature net, or Unix and crate feature process, or Unix and crate feature
// signal only.
pub fn enable_io(&mut self) -> &mut Self
// Available on crate feature net, or Unix and crate feature process, or Unix and crate feature
// signal only.
pub fn max_io_events_per_tick(&mut self, capacity: usize) -> &mut Self

// Available on crate feature time only.
pub fn enable_time(&mut self) -> &mut Self

impl Builder
pub fn start_paused(&mut self, start_paused: bool) -> &mut Self

// async 辅助函数，拥有传入参数值的所有权
async fn cheapo_owning_request(host: String, port: u16, path: String) -> std::io::Result<String> {
    cheapo_request(&host, port, &path).await
}

for (host, port, path) in requests {
    handles.push(task::spawn_local(cheapo_owning_request(host, port, path)));
}

// 在单线程中并发发起多个 request
let requests = vec![
    ("example.com".to_string(), 80, "/".to_string()),
    ("www.red-bean.com".to_string(), 80, "/".to_string()),
    ("en.wikipedia.org".to_string(), 80, "/".to_string()),
];

// block_on() 是同步函数，返回传入的 async task 的返回值。
let results = async_std::task::block_on(many_requests(requests));
for result in results {
    match result {
        Ok(response) => println!("{}", response),
        Err(err) => eprintln!("error: {}", err),
    }
}

use async_std::task;
let mut handles = vec![];
for (host, port, path) in requests {
    handles.push(task::spawn(
        async move { // block 捕获了上下问文对象所有权，所以返回的是 'static Future 对象
            cheapo_request(&host, port, &path).await
        }
    ));
}

use async_std::task;
use std::rc::Rc;
// 错误：reluctant() 返回的 Future 没有实现 Send。
async fn reluctant() -> String {
    let string = Rc::new("ref-counted string".to_string());
    some_asynchronous_thing().await; // Rc 跨 await
    format!("Your splendid string: {}", string)
}
task::spawn(reluctant());

// 解决办法：将不支持 Send 的变量隔离在单独的 await 所在的 block。
async fn reluctant() -> String {
    let return_value = {
        let string = Rc::new("ref-counted string".to_string());
        format!("Your splendid string: {}", string)
    };
    some_asynchronous_thing().await; // await 没有跨 Rc
    return_value
}

type GenericError = Box<dyn std::error::Error>;
type GenericResult<T> = Result<T, GenericError>;

fn some_fallible_thing() -> GenericResult<i32> {
    //...
}

// 该函数的 Future 没有实现 Send
async fn unfortunate() {
    // ... 因为这个函数返回值的原因
    match some_fallible_thing() {
        Err(error) => {
            report_error(error);
        }
        Ok(output) => {
            // 返回值跨越了这个 .await
            use_output(output).await;
        }
    } }

// 报错
async_std::task::spawn(unfortunate());

type GenericError = Box<dyn std::error::Error + Send + Sync + 'static>;
type GenericResult<T> = Result<T, GenericError>;

async fn verify_password(password: &str, hash: &str, key: &str) -> Result<bool, argonautica::Error>
{
    let password = password.to_string();
    let hash = hash.to_string();
    let key = key.to_string();

    async_std::task::spawn_blocking(
        // 参数是一个同步闭包函数，而非前面的 async task
        move || {
            argonautica::Verifier::default()
                .with_hash(hash)
                .with_password(password)
                .with_secret_key(key)
                .verify()
        }).await }

// 对于长时间运行的任务，可以主动 yield
while computation_not_done() {
    async_std::task::yield_now().await;
}

// https://tokio.rs/tokio/tutorial/shared-state
use std::sync::{Mutex, MutexGuard};

async fn increment_and_do_stuff(mutex: &Mutex<i32>) {
    let mut lock: MutexGuard<i32> = mutex.lock().unwrap();
    *lock += 1;
    do_something_async().await;
} // lock goes out of scope here

error: future cannot be sent between threads safely
   --> src/lib.rs:13:5
    |
13  |     tokio::spawn(async move {
    |     ^^^^^^^^^^^^ future created by async block is not `Send`
    |
   ::: /playground/.cargo/registry/src/github.com-1ecc6299db9ec823/tokio-0.2.21/src/task/spawn.rs:127:21
    |
127 |         T: Future + Send + 'static,
    |                     ---- required by this bound in `tokio::task::spawn::spawn`
    |
    = help: within `impl std::future::Future`, the trait `std::marker::Send` is not implemented for `std::sync::MutexGuard<'_, i32>`
note: future is not `Send` as this value is used across an await
   --> src/lib.rs:7:5
    |
4   |     let mut lock: MutexGuard<i32> = mutex.lock().unwrap();
    |         -------- has type `std::sync::MutexGuard<'_, i32>` which is not `Send`
...
7   |     do_something_async().await;
    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^ await occurs here, with `mut lock` maybe used later
8   | }
    | - `mut lock` is later dropped here

async fn increment_and_do_stuff(mutex: &Mutex<i32>) {
    {
        let mut lock: MutexGuard<i32> = mutex.lock().unwrap();
        *lock += 1;
    } // lock goes out of scope here

    do_something_async().await;
}

use async_std::sync::Mutex;

pub struct Outbound(Mutex<TcpStream>);

impl Outbound {
    pub fn new(to_client: TcpStream) -> Outbound {
        Outbound(Mutex::new(to_client))
    }
    pub async fn send(&self, packet: FromServer) -> ChatResult<()> {
        let mut guard = self.0.lock().await;
        utils::send_as_json(&mut *guard, &packet).await?;
        guard.flush().await?;
        Ok(())
    } }

use tokio::task;

// 需要位于 Runtime Context，spawn 的 task 立即在后台执行，而不管是否 .await
let join = task::spawn(async {
    // ...
    "hello world!"
});

// ...

// Await the result of the spawned task.
let result = join.await?;
assert_eq!(result, "hello world!");

// 如果 task panic，则 .await 返回 JoinErr
use tokio::task;
let join = task::spawn(async {
    panic!("something bad happened!")
});
// The returned result indicates that the task failed.
assert!(join.await.is_err());

// 错误
use tokio::task;
#[tokio::main]
async fn main() {
    let v = vec![1, 2, 3];
    task::spawn(async {
        println!("Here's a vec: {:?}", v); // 错误
    });
}
// error[E0373]: async block may outlive the current function, but
//               it borrows `v`, which is owned by the current function
//  --> src/main.rs:7:23
//   |
// 7 |       task::spawn(async {
//   |  _______________________^
// 8 | |         println!("Here's a vec: {:?}", v);
//   | |                                        - `v` is borrowed here
// 9 | |     });
//   | |_____^ may outlive borrowed value `v`
//   |
// note: function requires argument type to outlive `'static`
//  --> src/main.rs:7:17
//   |
// 7 |       task::spawn(async {
//   |  _________________^
// 8 | |         println!("Here's a vector: {:?}", v);
// 9 | |     });
//   | |_____^
// help: to force the async block to take ownership of `v` (and any other
//       referenced variables), use the `move` keyword
//   |
// 7 |     task::spawn(async move {
// 8 |         println!("Here's a vec: {:?}", v);
// 9 |     });
//   |

// OK
use tokio::task::yield_now;
use std::rc::Rc;

#[tokio::main]
async fn main() {
    tokio::spawn(async {
        // The scope forces `rc` to drop before `.await`.
        {
            let rc = Rc::new("hello");
            println!("{}", rc);
        }

        // `rc` is no longer used. It is **not** persisted when the task yields to the scheduler
        yield_now().await; // yield_now() 返回 Future，必须 await 才会实际 yield
    });
}

// Error
use tokio::task::yield_now;
use std::rc::Rc;

#[tokio::main]
async fn main() {
    tokio::spawn(async {
        let rc = Rc::new("hello");
        // `rc` is used after `.await`. It must be persisted to the task's state.
        yield_now().await;
        println!("{}", rc);
    });
}

error: future cannot be sent between threads safely
--> src/main.rs:6:5
	|
	6   |     tokio::spawn(async {
	|     ^^^^^^^^^^^^ future created by async block is not `Send`
	|
	::: [..]spawn.rs:127:21
	|
	127 |         T: Future + Send + 'static,
    |                     ---- required by this bound in
    |                          `tokio::task::spawn::spawn`
    |
    = help: within `impl std::future::Future`, the trait
    |       `std::marker::Send` is not  implemented for
    |       `std::rc::Rc<&str>`
note: future is not `Send` as this value is used across an await
   --> src/main.rs:10:9
    |
7   |         let rc = Rc::new("hello");
    |             -- has type `std::rc::Rc<&str>` which is not `Send`
...
10  |         yield_now().await;
    |         ^^^^^^^^^^^^^^^^^ await occurs here, with `rc` maybe
    |                           used later
11  |         println!("{}", rc);
12  |     });
    |     - `rc` is later dropped here

pub fn block_in_place<F, R>(f: F) -> R  // F 是同步函数
where
    F: FnOnce() -> R


pub fn spawn_local<F>(&self, future: F) -> JoinHandle<F::Output>  // F 是不需要 Send 的异步函数
where
    F: Future + 'static,
    F::Output: 'static,

let local = task::LocalSet::new();
local.spawn_local(async {
    // ...
});

impl<T> JoinHandle<T>
// Abort the task associated with the handle.
pub fn abort(&self)
// Checks if the task associated with this JoinHandle has finished.
pub fn is_finished(&self) -> bool
// Returns a new AbortHandle that can be used to remotely abort this task.
pub fn abort_handle(&self) -> AbortHandle

use tokio::{time, task};

let mut handles = Vec::new();
handles.push(tokio::spawn(async {
   time::sleep(time::Duration::from_secs(10)).await;
   true
}));
handles.push(tokio::spawn(async {
   time::sleep(time::Duration::from_secs(10)).await;
   false
}));

let abort_handles: Vec<task::AbortHandle> = handles.iter().map(|h| h.abort_handle()).collect();

for handle in abort_handles {
    handle.abort();
}
for handle in handles {
    assert!(handle.await.unwrap_err().is_cancelled());
}

impl JoinError
pub fn is_cancelled(&self) -> bool
pub fn is_panic(&self) -> bool
pub fn into_panic(self) -> Box<dyn Any + Send + 'static>
pub fn try_into_panic(self) -> Result<Box<dyn Any + Send + 'static>, JoinError>
pub fn id(&self) -> Id

use std::panic;
#[tokio::main]
async fn main() {
    let err = tokio::spawn(async {
        panic!("boom");
    }).await.unwrap_err();
    assert!(err.is_panic());
}

// async context 中，在单独的线程中运行可能会阻塞 tokio 的代码
let join = task::spawn_blocking(|| {
    // do some compute-heavy work or call synchronous code
    "blocking completed"
});
let result = join.await?;
assert_eq!(result, "blocking completed");

use tokio::task;

let result = task::block_in_place(|| {
    // do some compute-heavy work or call synchronous code
    "blocking completed"
});
assert_eq!(result, "blocking completed");

use tokio::task;

async {
    task::spawn(async {
        // ...
        println!("spawned task done!")
    });

    // Yield, allowing the newly-spawned task to execute first.
    task::yield_now().await; // 必须 .await
    println!("main task done!");
}

use tokio::{task, sync::mpsc};

let fut = async {
    let (tx, mut rx) = mpsc::unbounded_channel();
    for i in 0..1000 {
        let _ = tx.send(());
        // This will always be ready. If coop was in effect, this code would be forced to yield
        // periodically. However, if left unconstrained, then this code will never yield.
        rx.recv().await;
    }
};

task::unconstrained(fut).await;

use tokio::task::JoinSet;

#[tokio::main]
async fn main() {
    let mut set = JoinSet::new();

    for i in 0..10 {
        set.spawn(async move { i });
    }

    let mut seen = [false; 10];
    // join_next() 返回下一个返回的 task 结果
    while let Some(res) = set.join_next().await {
        let idx = res.unwrap();
        seen[idx] = true;
    }

    for i in 0..10 {
        assert!(seen[i]);
    }
}

impl<T> JoinSet<T>
pub fn new() -> Self
// 返回 JoinSet 中 task 数量
pub fn len(&self) -> usize
pub fn is_empty(&self) -> bool

impl<T: 'static> JoinSet<T>
// 使用 Builder 来构造一个 task：只能设置 name 然后再 spawn
pub fn build_task(&mut self) -> Builder<'_, T>

use tokio::task::JoinSet;
#[tokio::main]
async fn main() -> std::io::Result<()> {
    let mut set = JoinSet::new();
    // Use the builder to configure a task's name before spawning it.
    set.build_task()
        .name("my_task")
        .spawn(async { /* ... */ })?;
    Ok(())
}

// 在 JoinSet 中 spawn 一个 task，该 task 会立即运行
pub fn spawn<F>(&mut self, task: F) -> AbortHandle where F: Future<Output = T> + Send + 'static, T: Send

// 在指定的 Handler 对应的 Runtime 上 spawn task
pub fn spawn_on<F>(&mut self, task: F, handle: &Handle) -> AbortHandle
where
    F: Future<Output = T> + Send + 'static,
    T: Send
pub fn spawn_local<F>(&mut self, task: F) -> AbortHandle where F: Future<Output = T> + 'static
pub fn spawn_local_on<F>( &mut self, task: F, local_set: &LocalSet ) -> AbortHandle where F: Future<Output = T> + 'static

pub fn spawn_blocking<F>(&mut self, f: F) -> AbortHandle where F: FnOnce() -> T + Send + 'static, T: Send
use tokio::task::JoinSet;
#[tokio::main]
async fn main() {
    let mut set = JoinSet::new();
    for i in 0..10 {
        set.spawn_blocking(move || { i });
    }
    let mut seen = [false; 10];
    while let Some(res) = set.join_next().await {
        let idx = res.unwrap();
        seen[idx] = true;
    }
    for i in 0..10 {
        assert!(seen[i]);
    }
}

pub fn spawn_blocking_on<F>(&mut self, f: F, handle: &Handle) -> AbortHandle
where
    F: FnOnce() -> T + Send + 'static,
    T: Send

// 等待直到其中一个 task 完成，返回它的 output，注意是异步函数。
// 当 JoinSet 为空时，返回 None，可用于 while let 中。
pub async fn join_next(&mut self) -> Option<Result<T, JoinError>>
pub async fn join_next_with_id(&mut self) -> Option<Result<(Id, T), JoinError>>
pub fn try_join_next(&mut self) -> Option<Result<T, JoinError>>
pub fn try_join_next_with_id(&mut self) -> Option<Result<(Id, T), JoinError>>

// Aborts all tasks and waits for them to finish shutting down. Calling this method is equivalent
// to calling abort_all and then calling join_next in a loop until it returns None.
pub async fn shutdown(&mut self)

// Aborts all tasks on this JoinSet. This does not remove the tasks from the JoinSet. To wait for
// the tasks to complete cancellation, you should call join_next in a loop until the JoinSet is
// empty.
pub fn abort_all(&mut self)

// Removes all tasks from this JoinSet without aborting them. The tasks removed by this call will
// continue to run in the background even if the JoinSet is dropped.
pub fn detach_all(&mut self)

impl AbortHandle
// 终止 task。JoinHandle 可能返回 JoinError 错误（也可能正常结束）
pub fn abort(&self)
// abort/canceld task 是否完成
pub fn is_finished(&self) -> bool

pub fn id(&self) -> Id

use std::rc::Rc;
use tokio::task;

#[tokio::main]
async fn main() {
    let nonsend_data = Rc::new("my nonsend data...");
    let local = task::LocalSet::new();

    local.run_until(async move { // 自动调用 local.enter(), Future 位于该 LocalSet context 中
        let nonsend_data = nonsend_data.clone();

        // 在 run_until() 内部，可以多次使用 task::spawn_local() 提交任务, 都在 block_on() 所在的
        // 单线程上执行。
        task::spawn_local(async move {
            println!("{}", nonsend_data);
            // ...
        }).await.unwrap();
    }).await; // .await 在所有 spawn_local() 提交的 task 结束时返回
}

// 另一个例子
use tokio::{task, time};
use std::rc::Rc;

#[tokio::main]
async fn main() {
    let nonsend_data = Rc::new("world");
    let local = task::LocalSet::new();

    let nonsend_data2 = nonsend_data.clone();

    // 使用 LocalSet.spawn_local() 提交任务
    local.spawn_local(async move {
        // ...
        println!("hello {}", nonsend_data2)
    });

    local.spawn_local(async move {
        time::sleep(time::Duration::from_millis(100)).await;
        println!("goodbye {}", nonsend_data)
    });

    // ...

    local.await;
}

source
impl LocalSet
pub fn new() -> LocalSet

// 进入 LocalSet 的 context，这样后续使用 tokio::task::spawn_local() 提交 !Send task;
pub fn enter(&self) -> LocalEnterGuard

// 提交一个 !Send task， 返回可以 .await 的 JoinHandle
pub fn spawn_local<F>(&self, future: F) -> JoinHandle<F::Output> where F: Future + 'static, F::Output: 'static

// 在指定的 Runtime 中同步执行 future，直到返回。
// 内部调用 Runtime::block_on() 函数，所以需要在同步上下文中调用。
pub fn block_on<F>(&self, rt: &Runtime, future: F) -> F::Output where F: Future

// 执行一个 Future, 内部可以使用 tokio::task::spawn_local() 提交 !Send task, 运行直到这些 task 结束；
pub async fn run_until<F>(&self, future: F) -> F::Output where F: Future

pub fn unhandled_panic(&mut self, behavior: UnhandledPanic) -> &mut Self
pub fn id(&self) -> Id