::with_locals

Rust中的CPS糖，用于返回指向局部变量的值。

让我们从一个基本示例开始：返回 / 产生一个 format_args 局部变量。

use ::core::fmt::Display;
use ::with_locals::with;

#[with('local)]
fn hex (n: u32) -> &'local dyn Display
{
    &format_args!("{:#x}", n)
}

上面的代码变为

use ::core::fmt::Display;

fn with_hex <R, F> (n: u32, f: F) -> R
where           F : FnOnce(&'_     dyn Display) -> R,
 // for<'local> F : FnOnce(&'local dyn Display) -> R,
{
    f(&format_args!("{:#x}", n))
}

f: F，在这里被称为延续：而不是让函数返回 / 产生某个元素 / 对象，函数反而接收调用者希望对该元素（一旦它接收它）执行的操作的“逻辑”，因此是调用者而不是被调用者来处理该对象。

通过这样转移逻辑，被调用者而不是调用者运行那个逻辑，这样就在被调用者返回之前，在被调用者清理局部变量并使引用它的东西悬挂之前发生。

这就是整个策略的全部意义！

现在，要调用 / 使用上面的函数，不能再使用 let 绑定将函数的“结果”绑定到变量，因为该机制是为实际返回和调用者栈上实际运行的代码保留的。

相反，可以使用闭包 / 回调语法调用 / 使用 with_hex 函数

with_hex(66, |s| {
    println!("{}", s);
})

这非常强大，但每次创建这样的绑定时都会产生向右漂移

with_hex(1, |one| {
    with_hex(2, |two| {
        with_hex(3, |three| {
            // ughhh ..
        })
    })
})

相反，如果编译器 / 语言提供了一种方式，让 let 绑定神奇地执行这种转换，那就太好了

let one = hex(1);
let two = hex(2);
let three = hex(3);

以这种方式操作称为延续传递风格，但在Rust中不能隐式执行。但这并不意味着不能为它提供糖。

这就是 #[with] 的由来！

#[with] let one = hex(1);
#[with] let two = hex(2);
#[with] let three = hex(3);

• 这也可以写成

  // in the scope of a `#[with('special)]`-annotated function.
  let one: &'special _ = hex(1);
  let two: &'special _ = hex(2);
  let three: &'special _ = hex(3);
  

  也就是说，具有“特殊生命周期”的 let 绑定。

当应用于一个函数时，它将所有被这样注释的 let 绑定转换成嵌套闭包调用，其中绑定之后（在同一个作用域内）的所有语句都被移动到延续中。

以下是一个例子

# use ::with_locals::with; #[with('local)] fn hex (n: u32) -> &'local dyn ::core::fmt::Display { &format_args!("{:#x}", n) }
#
#[with]
fn hex_example ()
{
    let s: String = {
        println!("Hello, World!");
        #[with]
        let s_hex = hex(66);
        println!("s_hex = {}", s_hex); // Outputs `s_hex = 0x42`
        let s = s_hex.to_string();
        assert_eq!(s, "0x42");
        s
    };
    assert_eq!(s, "0x42");
}

上面的代码变为

# use ::with_locals::with; #[with('local)] fn hex (n: u32) -> &'local dyn ::core::fmt::Display { &format_args!("{:#x}", n) }
#
fn hex_example ()
{
    let s: String = {
        println!("Hello, World!");
        with_hex(66, |s_hex| {
            println!("s_hex = {}", s_hex); // Outputs `s_hex = 0x42`
            let s = s_hex.to_string();
            assert_eq!(s, "0x42");
            s
        })
    };
    assert_eq!(s, "0x42");
}

特质方法

特质也可以有 #[with] 注解的方法。

# use ::with_locals::with;
#
trait ToStr {
    #[with('local)]
    fn to_str (self: &'_ Self) -> &'local str
    ;
}

实现者的例子

# use ::with_locals::with; trait ToStr { #[with('local)] fn to_str (self: &'_ Self) -> &'local str ; }
#
impl ToStr for u32 {
    #[with('local)]
    fn to_str (self: &'_ u32) -> &'local str
    {
        let mut x = *self;
        if x == 0 {
            // By default, the macro tries to be quite smart and replaces
            // both implicitly returned and explicitly returned values, with
            // what the actual return of the actual `with_...` function must
            // be: `return f("0");`.
            return "0";
        }
        let mut buf = [b' '; 1 + 3 + 3 + 3]; // u32::MAX ~ 4_000_000_000
        let mut cursor = buf.len();
        while x > 0 {
            cursor -= 1;
            buf[cursor] = b'0' + (x % 10) as u8;
            x /= 10;
        }
        // return f(
        ::core::str::from_utf8(&buf[cursor ..]) // refers to a local!
            .unwrap()
        // );
    }
}
# #[with('special)]
# fn main ()
# {
#     let s: &'special str = 42.to_str();
#     assert_eq!(s, "42");
# }

特质的使用者（≠实现者）的例子。

# use ::with_locals::with; trait ToStr { #[with('local)] fn to_str (self: &'_ Self) -> &'local str ; }
#
impl<T : ToStr> ::core::fmt::Display for __<T> {
    #[with('special)] // you can #[with]-annotate classic function,
                      // in order to get the `let` assignment magic :)
    fn fmt (self: &'_ Self, fmt: &'_ mut ::core::fmt::Formatter<'_>)
      -> ::core::fmt::Result
    {
        //      You can specify the
        //      special lifetime instead of applying `[with]`
        //      vvvvvvvv
        let s: &'special str = self.0.to_str();
        fmt.write_str(s)
    }
}
// (Using a newtype to avoid coherence issues)
struct __<T : ToStr>(T);

有关更多详细示例，请参阅可运行的文件中的 examples/main.rs。

用法和“特殊生命周期”。

关于 #[with] 的操作，有一个重要的理解点：有时它必须执行转换（例如，将一个 foo() 调用转换成一个 with_foo(...) 调用），有时则不必；这取决于程序员想要编写的语义（也就是说，并非所有的函数调用都依赖于CPS！）。

use ::core::fmt::Display;
use ::with_locals::with;

#[with('local, continuation_name = return_)]
fn display_addr (addr: usize) -> &'local dyn Display
{
    if addr == 0 {
        return_!( &"NULL" );
    }
    with_hex(addr, |hex| {
        return_(&format_args!("0x{}", hex))
    })
}
// where
#[with('local)]
fn hex (n: usize) -> &'local dyn Display
{
    &format_args!("{:x}", n)
}

use ::core::fmt::Display;
use ::with_locals::with;

#[with('local)]
fn hex (n: u32) -> &'local dyn Display
{
    &format_args!("{:#x}", n)
}

fn main ()
{
    for n in 0 .. { // <- `break` cannot refer to this:
        with_hex(n, |s| { // === closure boundary ===
            println!("{}", s);     // ^ Error!
            if n >= 5 {            // |
                break; // ------------+
            }
        })
    }
}

use ::core::fmt::Display;
use ::with_locals::with;

#[with('local)]
fn hex (n: u32) -> &'local dyn Display
{
    &format_args!("{:#x}", n)
}

#[with]
fn main ()
{
    for n in 0 .. {
        #[with]
        let s = hex(n);
        println!("{}", s);
        if n >= 5 {
            break;
        }
    };
}

[dependencies]
# ...
with_locals = { version = "...", features = ["expand-macros"] }