如何使用它？

此实现目前基本上是基于生成器/协程构建的。此功能于2017年8月29日刚刚落地，并将作为 Rust 的 nightly 通道的一部分。您可以通过以下方式获取 nightly 通道；

rustup update nightly

完成此操作后，您可能需要确保 Cargo 使用 nightly 工具链，如下所示：

cargo +nightly build

接下来，您需要将以下内容添加到您的 Cargo.toml

[dependencies]
futures-await = "0.1"

然后...

#![feature(proc_macro, generators)]

extern crate futures_await as futures;

use futures::prelude::*;

#[async]
fn foo() -> Result<i32, i32> {
    Ok(1 + await!(bar())?)
}

#[async]
fn bar() -> Result<i32, i32> {
    Ok(2)
}

fn main() {
    assert_eq!(foo().wait(), Ok(3));
}

这个crate的目的是“伪装”成futures crate，重新导出其整个层次结构，并仅增加必要的运行时支持、async属性和await!宏。当您导入时，这些导入都包含在futures::prelude::*中。

对于一大堆代码中的许多示例，您还可以查看sccache的async-await分支，该分支正在进行许多位置的异步/await语法的过渡。您通常会发现在此之后代码的可读性要好得多，特别是这些更改

技术细节

如前所述，这个crate在Rust的生成器特性基础上构建。生成器，在本例中通常称为无栈协程，允许编译器为函数生成一个最优的Future实现，将看似同步的代码块转换成可以异步执行的Future。这里的反编译过程从您编写的代码到rustc编译的代码非常简单，您可以浏览futures-async-macro crate的源代码以获取更多详细信息。

此外，这个crate还提供了一些主要的“API”

• #[async] - 这个属性可以应用于方法和函数，表示它是一个异步函数。函数的签名必须返回某种形式的Result（尽管它可以返回结果的typedef）。此外，函数的参数必须全部是拥有值，换句话说，不能包含任何引用。这种限制可能在将来被放宽！

  一些例子如下

  // attribute on a bare function
  #[async]
  fn foo(a: i32) -> Result<u32, String> {
      // ...
  }
  
  // returning a typedef works too!
  #[async]
  fn foo() -> io::Result<u32> {
      // ...
  }
  
  impl Foo {
      // methods also work!
      #[async]
      fn foo(self) -> io::Result<u32> {
          // ...
      }
  }
  
  // For now, however, these do not work, they both have arguments which contain
  // references! This may work one day, but it does not work today.
  //
  // #[async]
  // fn foo(a: &i32) -> io::Result<u32> { /* ... */ }
  //
  // impl Foo {
  //     #[async]
  //     fn foo(&self) -> io::Result<u32> { /* ... */ }
  // }
  

  请注意，一个#[async]函数的行为与其同步版本非常相似。例如，?操作符在内部工作，您可以使用早期的return语句等。

  在底层，一个#[async]函数被编译成一个状态机，该状态机表示该函数的未来，状态机的挂起点将位于await!宏的位置。

• async_block! - 这个宏与 #[async] 类似，因为它都会创建一个未来（future），但与 #[async] 不同的是，它可以在表达式上下文中使用，并且不需要专门的函数。这个宏可以被视为“异步运行此代码块”，其中提供的代码块，就像异步函数一样，返回某种形式的结果。例如

  let server = TcpListener::bind(..);
  let future = async_block! {
      #[async]
      for connection in server.incoming() {
          spawn(handle_connection(connection));
      }
      Ok(())
  };
  core.run(future).unwrap();
  

  或者如果您想在函数中执行一些预计算

  fn hash_file(path: &Path, pool: &CpuPool)
      -> impl Future<Item = u32, Error = io::Error>
  {
      let abs_path = calculate_abs_path(path);
      async_block! {
          let contents = await!(read_file)?;
          Ok(hash(&contents))
      }
  }
  

• await! - 这是一个在 futures-await-macro 库中提供的宏，允许等待一个未来（future）完成。await! 宏只能在 #[async] 函数或 async_block! 中使用，可以将其视为一个类似函数的对象

  fn await!<F: Future>(future: F) -> Result<F::Item, F::Error> {
      // magic
  }
  

  此宏的一些示例

  #[async]
  fn fetch_url(client: hyper::Client, url: String) -> io::Result<Vec<u8>> {
      // note the trailing `?` to propagate errors
      let response = await!(client.get(url))?;
      await!(response.body().concat())
  }
  

• #[async] for 循环 - 能够异步迭代一个 Stream。您可以通过将 #[async] 属性附加到一个 for 循环上，其中正在迭代的对象实现了 Stream 特性来实现这一点。

  流中的错误将自动传播，否则，for 循环将遍历流直到完成，将每个元素绑定到提供的模式上。

  一些例子如下

  #[async]
  fn accept_connections(listener: TcpListener) -> io::Result<()> {
      #[async]
      for connection in server.incoming() {
          // `connection` here has type `TcpStream`
      }
      Ok(())
  }
  

  请注意，与 await! 一样，#[async] for 循环只能在异步函数或异步块中使用。

• #[async_stream(item = ...)] - 定义了一个实现 Stream 而不是 Future 的函数。此函数使用 stream_yield! 宏产生项，并与其他 await! 宏和 #[async] for 循环一起工作。

  声明的函数必须返回一个 Result<(), E>，其中 E 变成了返回的 Stream 的错误。通过从函数返回 Ok(()) 或返回一个错误来终止流。函数内部可以使用 ? 等操作来传播错误。

  示例

  #[async_stream(item = u32)]
  fn accept_connections(listener: TcpListener) -> io::Result<()> {
      #[async]
      for object in fetch_all_objects() {
          let description = await!(fetch_object_description(object));
          stream_yield!(description);
      }
      Ok(())
  }
  

夜间功能

目前这个包需要两个nightly特性才能使用

• #![feature(generators)] - 这是一个实验性的语言特性，尚未稳定，但它是async/await实现的基础。最近实现了这个特性，有关稳定化的进度可以在其跟踪问题上找到。

• #![feature(proc_macro)] - 这也被称作 "宏 2.0"，是此包中定义 #[async] 属性的方式，而不是编译器本身。我们还利用了其他宏 2.0 特性，例如通过 use 导入宏，而不是 #[macro_use]。有关此特性的跟踪问题包括#38356和#35896。

接下来是什么？

这个包仍然相当新，生成器刚刚在Rust的nightly通道上落地。尽管目前没有计划对这个包进行重大更改，但我们仍需看看这一切会如何发展！将生成器尽快实现到语言中的主要动机之一是促进async/await的实现，我们需要您的帮助来评估这一点！

值得注意的是，我们希望对此包中的async/await以及生成器作为语言特性本身收集反馈。我们想确保，如果我们稳定了生成器或过程宏，它们能够提供最佳的async/await体验！

目前建议您在使用此包进行生产时谨慎行事。这个包本身只进行了非常有限的测试，并且到目前为止，语言特性 generators 也只进行了有限的测试。建议您保持警惕，注意查找错误！如果您遇到任何问题或疑问，欢迎创建问题！

注意事项

正如许多nightly特性所预期的那样，当与此项目一起工作时，有一些需要注意的问题。尽管欢迎提交错误报告或经验报告，但了解需要解决的问题总是好的！

借用

当前借用并不十分有效。编译器可能会拒绝许多借用，或者由于生成器特性正在开发中，可能存在一些安全隐患。例如，如果您有一个函数

#[async]
fn foo(s: &str) -> io::Result<()> {
    // ..
}

这可能无法编译！原因是返回的未来通常需要遵守 'static 约束。异步函数在调用时不会执行任何代码，只有在轮询时才会取得进展。这意味着当您调用异步函数时，它会创建一个未来，包装参数，然后将其返回给您。在这种情况下，它必须返回一个 &str，这并不总是符合生存期的要求。

使上述函数编译的一个示例可能是这样做

#[async]
fn foo(s: String) -> io::Result<()> {
    // ...
}

或以其他方式使用所有权的值而不是借用引用。

注意，借用的问题不仅仅是参数。例如，以下代码今天（或者至少不应该）无法编译：

for line in string.lines() {
    await!(process(line));
    println!("processed: {}", line);
}

这里的问题是line是一个在yield点（即对await!的调用）持续存在的借用值。这意味着当future可能返回到栈上时，它是await!过程的一部分，它必须在重新进入future时恢复line变量。这实际上并没有完全实现，并且在今天可能是不安全的。作为目前的经验法则，你只需在调用await!或异步for循环期间，只拥有值（没有借用内部值）即可。

正在投入大量精力来解决这个问题！借用是Rust中许多舒适模式的精髓，我们希望这能够实现！

最后一点，今天“没有借用参数”的一个后果是，函数签名如下：

#[async]
fn foo(&self) -> io::Result<()> {
    // ...
}

很遗憾，将无法工作。你可能需要按值取self，或者推迟到不同的#[async]函数。

特质的Future

假设你有一个这样的特质：

trait MyStuff {
    fn do_async_task(??self) -> Box<Future<...>>;
}

在这里我们暂时忽略self的细节，但本质上我们有一个在特质中返回future的函数。不幸的是，实际上使用它相当困难！目前有几个需要注意的问题：