深入Rust：async/await语法糖的底层展开原理与实战指南

trait Future {
    // 异步任务完成后返回的结果类型
    type Output;

    // 核心方法：尝试推进异步任务的执行
    // - 返回Poll::Pending：任务还在等待，需要后续再次调用poll
    // - 返回Poll::Ready(val)：任务完成，val是结果
    // - waker：用于“唤醒”任务——当等待的事件发生时（如IO完成），通过waker通知executor再次调用poll
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>;
}

// Poll枚举：表示Future的执行状态
enum Poll<T> {
    Pending,
    Ready(T),
}

use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};
use std::time::{Instant, Duration};
use tokio::time::Sleep; // 依赖tokio的Sleep Future（简化定时器逻辑）

// 自定义DelayFuture：包装tokio的Sleep，完成后返回字符串
struct DelayFuture {
    sleep: Sleep,       // 内部依赖的Sleep Future（负责计时）
    message: String,    // 完成后返回的消息
}

impl DelayFuture {
    // 构造函数：创建一个延迟duration后返回message的Future
    fn new(duration: Duration, message: String) -> Self {
        Self {
            sleep: tokio::time::sleep(duration),
            message,
        }
    }
}

// 为DelayFuture实现Future trait
impl Future for DelayFuture {
    type Output = String; // 完成后返回String

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        // 1. 尝试推进内部的Sleep Future：调用Sleep的poll方法
        match Pin::new(&mut self.sleep).poll(cx) {
            // 2. 如果Sleep还在等待（Pending），当前Future也返回Pending
            Poll::Pending => Poll::Pending,
            // 3. 如果Sleep完成（Ready），当前Future返回预设的message
            Poll::Ready(()) => Poll::Ready(self.message.clone()),
        }
    }
}

// 测试：用tokio运行这个Future
#[tokio::main]
async fn main() {
    let start = Instant::now();
    // 创建DelayFuture：延迟1秒，返回"Delay done!"
    let future = DelayFuture::new(Duration::from_secs(1), "Delay done!".into());
    // 等待Future完成（这里用await，后续会讲它的展开）
    let result = future.await;
    
    println!("结果：{}，耗时：{:?}", result, start.elapsed());
    // 输出：结果：Delay done!，耗时：1.002s
}

use std::time::Duration;
use tokio::time::sleep;

// 异步函数：延迟1秒，打印消息，返回42
async fn async_example() -> i32 {
    // 局部变量：执行到await时需要保存的状态
    let message = "Async function is running".to_string();
    
    // 暂停点：等待sleep完成
    sleep(Duration::from_secs(1)).await;
    
    // 等待完成后，继续执行
    println!("{}", message);
    42 // 函数返回值：最终作为Future::Output
}

// 调用这个async函数
#[tokio::main]
async fn main() {
    let result = async_example().await;
    println!("Async result: {}", result);
}

// 编译器为async_example生成的匿名结构体（简化版）
struct AsyncExampleFuture {
    // 状态标记：记录当前执行到哪一步（0=未开始，1=已执行sleep.await，2=已完成）
    state: u8,
    // 局部变量：message需要在await暂停时保存
    message: Option<String>,
    // 被await的Future：sleep(Duration::from_secs(1))的实例
    sleep_future: Option<tokio::time::Sleep>,
}

// 为AsyncExampleFuture实现构造函数（对应async_example()的调用）
impl AsyncExampleFuture {
    fn new() -> Self {
        Self {
            state: 0,          // 初始状态：未开始执行
            message: None,     // 初始无值，执行到第一步时初始化
            sleep_future: None,// 初始无值，执行到第一步时创建
        }
    }
}

use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};

// 编译器为AsyncExampleFuture实现的Future trait（简化版）
impl Future for AsyncExampleFuture {
    type Output = i32; // 对应async_example的返回值类型

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        // 匹配当前状态，从对应阶段继续执行
        loop {
            match self.state {
                // 状态0：未开始执行，执行函数的前半部分（到await前）
                0 => {
                    // 1. 执行async_example中的局部变量初始化
                    let message = "Async function is running".to_string();
                    // 2. 创建被await的sleep Future
                    let sleep_future = tokio::time::sleep(Duration::from_secs(1));
                    
                    // 3. 保存状态：将message和sleep_future存入结构体
                    self.message = Some(message);
                    self.sleep_future = Some(sleep_future);
                    
                    // 4. 更新状态为1：标记下一步要执行sleep.await
                    self.state = 1;
                }

                // 状态1：执行sleep.await，推进sleep_future的执行
                1 => {
                    // 1. 取出之前保存的sleep_future（unwrap是安全的，因为state=1时已初始化）
                    let sleep_future = self.sleep_future.as_mut().unwrap();
                    
                    // 2. 尝试推进sleep_future：调用它的poll方法
                    match Pin::new(sleep_future).poll(cx) {
                        // 2.1 如果sleep还在等待（Pending），当前Future也返回Pending
                        Poll::Pending => return Poll::Pending,
                        // 2.2 如果sleep完成（Ready），继续执行后续逻辑
                        Poll::Ready(()) => {
                            // 3. 执行await后的代码：打印message
                            let message = self.message.take().unwrap();
                            println!("{}", message);
                            
                            // 4. 更新状态为2：标记任务即将完成
                            self.state = 2;
                        }
                    }
                }

                // 状态2：任务完成，返回结果42
                2 => {
                    return Poll::Ready(42);
                }

                // 无效状态：理论上不会出现，返回错误（编译器生成的代码会处理得更严谨）
                _ => panic!("Invalid state"),
            }
        }
    }
}

// X.await的展开逻辑（伪代码）
loop {
    // 步骤1：尝试推进被await的Future X的执行
    match X.poll(cx) {
        // 步骤2：如果X未完成（Pending），当前Future也返回Pending，等待被唤醒
        Poll::Pending => return Poll::Pending,
        // 步骤3：如果X完成（Ready(result)），返回X的结果，当前Future继续执行
        Poll::Ready(result) => break result,
    }
}

use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};
use std::time::Duration;
use tokio::time::Sleep;

// 手动实现的多步骤Future
struct MultiStepFuture {
    state: u8,          // 0: 未开始, 1: 等待step1, 2: 等待step2, 3: 完成
    step1_result: Option<String>, // 保存step1的结果
    step1_sleep: Option<Sleep>,   // step1的sleep Future
    step2_sleep: Option<Sleep>,   // step2的sleep Future
}

impl MultiStepFuture {
    fn new() -> Self {
        Self {
            state: 0,
            step1_result: None,
            step1_sleep: None,
            step2_sleep: None,
        }
    }
}

impl Future for MultiStepFuture {
    type Output = String;

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        loop {
            match self.state {
                0 => {
                    // 步骤1：初始化step1的sleep Future
                    let sleep = tokio::time::sleep(Duration::from_secs(1));
                    self.step1_sleep = Some(sleep);
                    self.state = 1;
                }
                1 => {
                    // 步骤2：推进step1的sleep
                    let sleep = self.step1_sleep.as_mut().unwrap();
                    match Pin::new(sleep).poll(cx) {
                        Poll::Pending => return Poll::Pending,
                        Poll::Ready(()) => {
                            // step1完成，保存结果，初始化step2的sleep
                            self.step1_result = Some("step1 done".into());
                            let sleep = tokio::time::sleep(Duration::from_millis(500));
                            self.step2_sleep = Some(sleep);
                            self.state = 2;
                        }
                    }
                }
                2 => {
                    // 步骤3：推进step2的sleep
                    let sleep = self.step2_sleep.as_mut().unwrap();
                    match Pin::new(sleep).poll(cx) {
                        Poll::Pending => return Poll::Pending,
                        Poll::Ready(()) => {
                            // step2完成，拼接结果，进入完成状态
                            let step1 = self.step1_result.take().unwrap();
                            let result = format!("{} → step2 done", step1);
                            self.state = 3;
                            return Poll::Ready(result);
                        }
                    }
                }
                3 => panic!("Task already completed"),
                _ => panic!("Invalid state"),
            }
        }
    }
}

// 运行手动实现的Future
#[tokio::main]
async fn main() {
    let future = MultiStepFuture::new();
    let result = future.await;
    println!("Multi-step result: {}", result);
    // 输出：Multi-step result: step1 done → step2 done（耗时≈1.5秒）
}

use std::time::Duration;
use tokio::time::sleep;

// 用async/await实现多步骤异步任务
async fn multi_step_async() -> String {
    // 步骤1：延迟1秒，获取step1结果
    sleep(Duration::from_secs(1)).await;
    let step1 = "step1 done".to_string();
    
    // 步骤2：延迟0.5秒，拼接结果
    sleep(Duration::from_millis(500)).await;
    format!("{} → step2 done", step1)
}

// 运行async函数
#[tokio::main]
async fn main() {
    let result = multi_step_async().await;
    println!("Multi-step result: {}", result);
    // 输出相同，代码量减少70%+
}

// 错误：async fn返回的Future是匿名类型，无法在函数签名中显式指定
fn get_future() -> impl Future<Output = i32> {
    async {
        sleep(Duration::from_secs(1)).await;
        42
    }
}

// 但如果函数有分支，impl Future无法覆盖多个不同的匿名类型：
fn get_future(flag: bool) -> impl Future<Output = i32> {
    if flag {
        async { 1 }.await // 匿名类型A
    } else {
        async { 2 }.await // 匿名类型B
    }
    // 错误：impl Future只能对应一种类型，A和B是不同类型
}

use std::future::Future;
use std::boxed::Box;

fn get_future(flag: bool) -> Box<dyn Future<Output = i32> + Send> {
    if flag {
        // 将匿名Future包装成Box<dyn Future>
        Box::new(async {
            sleep(Duration::from_secs(1)).await;
            1
        })
    } else {
        Box::new(async {
            sleep(Duration::from_millis(500)).await;
            2
        })
    }
}

// 调用时正常await
#[tokio::main]
async fn main() {
    let future = get_future(true);
    let result = future.await;
    println!("Result: {}", result);
}

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

async fn bad_async() {
    // 错误：std::thread::sleep是阻塞操作，会卡住executor
    thread::sleep(Duration::from_secs(1));
    println!("This will block the executor");
}

#[tokio::main]
async fn main() {
    // 同时启动两个异步任务
    tokio::spawn(bad_async());
    tokio::spawn(async {
        println!("This task will be blocked for 1 second");
    });
}

use std::thread;
use std::time::Duration;
use tokio::task::spawn_blocking;

async fn good_async() {
    // 用spawn_blocking执行阻塞操作，不阻塞异步线程
    let result = spawn_blocking(|| {
        thread::sleep(Duration::from_secs(1));
        "Block operation done"
    }).await.unwrap();
    
    println!("{}", result);
}

#[tokio::main]
async fn main() {
    tokio::spawn(good_async());
    tokio::spawn(async {
        println!("This task will not be blocked");
    });
}

// 错误：返回的Future包含对s的引用，s的生命周期可能不够长
async fn async_with_ref(s: &str) -> &str {
    sleep(Duration::from_secs(1)).await;
    s
}

#[tokio::main]
async fn main() {
    let result = {
        let s = "hello".to_string();
        // 错误：s的生命周期在这个块结束后就结束，而Future可能还在等待
        async_with_ref(&s).await
    };
}

// 改进：返回String（所有权），无生命周期问题
async fn async_with_owned(s: String) -> String {
    sleep(Duration::from_secs(1)).await;
    s
}

#[tokio::main]
async fn main() {
    let result = {
        let s = "hello".to_string();
        // s的所有权转移到async函数中，无生命周期问题
        async_with_owned(s).await
    };
    println!("Result: {}", result);
}