Rust 宏實戰：函式重複呼叫與 LazyStatic 延遲初始化

Rust 宏系統允許開發者編寫產生程式碼的程式碼，大幅提升程式碼的表達力和可維護性。本文將聚焦於兩個實際應用案例：設計一個重複呼叫函式的宏，以及剖析 lazy_static 宏的運作機制，藉此展現 Rust 宏的威力。首先，我們將建立一個名為 three! 的宏，它可以將指定的函式呼叫重複三次。接著，我們將深入研究 lazy_static! 宏，理解它如何實作靜態變數的延遲初始化，以及如何確保執行緒安全。過程中，我們將運用 syn 函式庫解析程式碼結構，並使用 quote 函式庫生成目標程式碼，完整展現 procedural macro 的開發流程。最後，我們將探討宣告式宏和程式式宏的差異，並提供選擇策略，協助讀者根據實際需求選擇合適的宏型別。

宏定義

首先，建立一個新的Cargo專案，然後在專案中建立一個函式庫用於定義宏。修改函式庫的Cargo.toml檔案，新增proc-macro屬性和所需的依賴項。

# fnmacros/Cargo.toml

[lib]
proc-macro = true

[dependencies]
quote = "1.0.21"
syn = {version = "1.0.103", features = ["full", "extra-traits"]}

接著，在函式庫的src/lib.rs檔案中定義宏。這個宏名為three!(), 它接受一個呼叫表示式作為引數，並將其展開為三次呼叫。

// fnmacros/src/lib.rs

extern crate proc_macro;
use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, Expr};

#[proc_macro]
pub fn three(input: TokenStream) -> TokenStream {
    let expr: Expr = parse_macro_input!(input as Expr);
    let expanded = quote! {
        #expr;
        #expr;
        #expr;
    };
    TokenStream::from(expanded)
}

宏使用

現在，可以在主專案中使用這個宏了。首先，需要在主專案的Cargo.toml檔案中新增對宏函式庫的依賴。

# fnmacros_demos/Cargo.toml

[dependencies]
fnmacros = {path = "fnmacros"}

然後，在主專案的原始檔中引入宏並使用它。

// fnmacros_demos/src/main.rs

fn hello() {
    println!("Hello");
}

fn main() {
    three!(hello());
}

當執行主專案時，宏three!()會將hello()呼叫展開為三次呼叫。

圖表翻譯：

  flowchart TD
    A[三次呼叫宏three!()] --> B[解析呼叫表示式]
    B --> C[展開為三次呼叫]
    C --> D[傳回展開的TokenStream]
    D --> E[在main()中使用宏]
    E --> F[執行主專案]
    F --> G[列印三次"Hello"]

內容解密：

上述程式碼中，宏three!()的實作涉及到Rust的語法解析和程式碼生成。使用syn函式庫解析呼叫表示式，然後使用quote函式庫生成展開的程式碼。最終，宏傳回展開的TokenStream，這樣就可以在主專案中使用這個宏了。

這個宏的實作展示了Rust中 процед式宏的強大能力，可以用於生成複雜的程式碼結構，提高開發效率。同時，也需要注意宏的使用需要謹慎，避免過度複雜的程式碼生成。

Rust 宏的應用：重複呼叫函式

在 Rust 中，宏（macro）是一種強大的工具，允許我們在編譯時生成程式碼。這篇文章將介紹如何使用 Rust 宏來重複呼叫一個函式。

宏的定義

首先，我們需要定義一個宏，名為 three。這個宏將接受一個函式呼叫作為引數，並傳回一個新的 TokenStream，包含三次函式呼叫。

#[proc_macro]
pub fn three(call: TokenStream) -> TokenStream {
    // ...
}

解析函式呼叫

我們使用 parse_macro_input! 宏來解析函式呼叫，將其轉換為 Expr 型別的值。

let parsed_call = parse_macro_input!(call as Expr);

處理函式呼叫

我們使用 match 陳述式來處理函式呼叫。如果函式呼叫不是 Expr::Call 型別，我們就會 panic。

let call = match parsed_call {
    Expr::Call(c) => c,
    other => panic!("Expression type {:?} is not allowed", other),
};

建立函式呼叫向量

我們建立一個空的向量 invokes 來儲存三次函式呼叫。

let mut invokes = Vec::new();

重複呼叫函式

我們使用 for 迴圈來重複呼叫函式三次，並將每次呼叫推入 invokes 向量中。

for _ in 0..3 {
    invokes.push(quote! { #call; });
}

建立 TokenStream

我們使用 quote! 宏來建立一個新的 TokenStream，包含三次函式呼叫。

let tokens = quote! {
    #(#invokes)*
};

傳回 TokenStream

最後，我們傳回建立的 TokenStream。

TokenStream::from(tokens)

測試

我們可以在 src/main.rs 中測試我們的宏。

use fnmacros::three;

fn hello() {
    println!("Hello");
}

fn main() {
    three!(hello());
}

執行 cargo run 後，將會輸出三次 “Hello”。

圖表翻譯：

  graph LR
    A[three 宏] --> B[解析函式呼叫]
    B --> C[處理函式呼叫]
    C --> D[建立函式呼叫向量]
    D --> E[重複呼叫函式]
    E --> F[建立 TokenStream]
    F --> G[傳回 TokenStream]

這個圖表展示了我們的宏的執行流程。首先，我們解析函式呼叫，然後處理函式呼叫。如果函式呼叫不是 Expr::Call 型別，我們就會 panic。接下來，我們建立一個空的向量 invokes 來儲存三次函式呼叫。然後，我們使用 for 迴圈來重複呼叫函式三次，並將每次呼叫推入 invokes 向量中。最後，我們建立一個新的 TokenStream，包含三次函式呼叫，並傳回它。

Rust 宏：LazyStatic 的實作

Rust 的宏系統允許我們擴充套件語言本身，建立自定義的 DSL（Domain-Specific Language）。在這個例子中，我們將實作一個名為 LazyStatic 的宏，該宏可以用來定義懶惰初始化的靜態變數。

LazyStatic 的結構

首先，我們需要定義 LazyStatic 的結構。這個結構將包含四個欄位：visibility、name、ty 和 init。

struct LazyStatic {
    visibility: Visibility,
    name: Ident,
    ty: Type,
    init: Expr,
}

實作 Parse 特徵

接下來，我們需要實作 Parse 特徵，以便可以將 TokenStream 解析為 LazyStatic。

impl Parse for LazyStatic {
    fn parse(input: ParseStream) -> Result<Self> {
        let visibility = input.parse()?;
        input.parse::<Token![static]>()?;
        input.parse::<Token![ref]>()?;
        let name: Ident = input.parse()?;
        input.parse::<Token![:]>()?;
        let ty: Type = input.parse()?;
        input.parse::<Token![=]>()?;
        let init: Expr = input.parse()?;
        input.parse::<Token![;]>()?;
        Ok(LazyStatic {
            visibility,
            name,
            ty,
            init,
        })
    }
}

使用 parse_macro_input!

現在，我們可以使用 parse_macro_input! 宏來解析 TokenStream 為 LazyStatic。

let lazy_static = parse_macro_input!(input as LazyStatic);

生成程式碼

最後，我們需要生成程式碼，以便建立懶惰初始化的靜態變數。

let expanded = quote! {
    #lazy_static.visibility static ref #lazy_static.name: #lazy_static.ty = #lazy_static.init;
};

完整程式碼

以下是完整的程式碼：

use proc_macro::TokenStream;
use quote::{quote, quote_spanned};
use syn::{parse_macro_input, Ident, Type, Visibility, Expr, parse::{Parse, ParseStream, Result}};

struct LazyStatic {
    visibility: Visibility,
    name: Ident,
    ty: Type,
    init: Expr,
}

impl Parse for LazyStatic {
    fn parse(input: ParseStream) -> Result<Self> {
        let visibility = input.parse()?;
        input.parse::<Token![static]>()?;
        input.parse::<Token![ref]>()?;
        let name: Ident = input.parse()?;
        input.parse::<Token![:]>()?;
        let ty: Type = input.parse()?;
        input.parse::<Token![=]>()?;
        let init: Expr = input.parse()?;
        input.parse::<Token![;]>()?;
        Ok(LazyStatic {
            visibility,
            name,
            ty,
            init,
        })
    }
}

#[proc_macro]
pub fn lazy_static(input: TokenStream) -> TokenStream {
    let lazy_static = parse_macro_input!(input as LazyStatic);
    let expanded = quote! {
        #lazy_static.visibility static ref #lazy_static.name: #lazy_static.ty = #lazy_static.init;
    };
    TokenStream::from(expanded)
}

使用

現在，你可以使用 lazy_static 宏來定義懶惰初始化的靜態變數。

lazy_static! {
    pub static ref NAME: std::sync::Mutex<Vec<i32>> = std::sync::Mutex::new(Vec::new());
}

實作 Lazy Static 的 Procedural Macro

要實作 LazyStatic 的 procedural macro，我們需要先定義 LazyStatic 的結構體，然後實作 Parse trait 來解析輸入的 TokenStream。接下來，我們可以開始實作 procedural macro lazy_static。

定義 `LazyStatic` 結構體

struct LazyStatic {
    visibility: Visibility,
    name: Ident,
    ty: Type,
    init: Expr,
}

實作 `Parse` trait

impl Parse for LazyStatic {
    fn parse(input: ParseStream) -> Result<Self> {
        // ...
    }
}

實作 Procedural Macro `lazy_static`

#[proc_macro]
pub fn lazy_static(input: TokenStream) -> TokenStream {
    let LazyStatic {
        visibility,
        name,
        ty,
        init,
    } = parse_macro_input!(input as LazyStatic);

    // 處理警告和錯誤
    let generic_names = ["FOO", "BAR", "BAZ"];
    for n in generic_names {
        if name == n {
            name.span().unwrap().warning("Name too generic").emit();
        }
    }

    // 檢查初始化表示式是否為空 tuple
    if let Expr::Tuple(ref init) = init {
        if init.elems.is_empty() {
            init.span().unwrap().error("Cannot initialize static values using ()").emit();
            return TokenStream::new();
        }
    }

    // 檢查型別是否實作 Sync 和 Sized trait
    let assert_sync = quote_spanned! { ty.span() =>
        struct _AssertSync where #ty: ::std::marker::Sync;
    };
    let assert_sized = quote_spanned! { ty.span() =>
        struct _AssertSized where #ty: ::std::marker::Sized;
    };

    // ...
}

在上面的程式碼中，我們首先定義了 LazyStatic 結構體，然後實作了 Parse trait 來解析輸入的 TokenStream。接下來，我們實作了 procedural macro lazy_static，它會解析輸入的 TokenStream，然後進行一系列的檢查和處理，包括警告、錯誤和型別檢查。

圖表翻譯

以下是程式碼的流程圖：

  flowchart TD
    A[開始] --> B[解析輸入的 TokenStream]
    B --> C[檢查警告和錯誤]
    C --> D[檢查初始化表示式是否為空 tuple]
    D --> E[檢查型別是否實作 Sync 和 Sized trait]
    E --> F[生成程式碼]
    F --> G[傳回生成的 TokenStream]

這個流程圖展示了 procedural macro lazy_static 的執行流程，從解析輸入的 TokenStream 到生成程式碼和傳回生成的 TokenStream。

內容解密

在這個範例中，我們實作了 procedural macro lazy_static，它可以解析輸入的 TokenStream，然後進行一系列的檢查和處理。這個 macro 可以用來生成 lazy static 變數的程式碼。透過這個範例，我們可以學習到如何實作 procedural macro 和如何使用 quote_spanned! macro 來生成程式碼。

Rust 中的 lazy_static 宏實作

在 Rust 中，lazy_static 宏是一種常用的工具，用於延遲初始化靜態變數。以下是對這個宏的實作進行的分析和重構。

基本原理

lazy_static 宏的基本原理是使用 std::sync::Once 來確保靜態變數只被初始化一次。它使用了一個 Box 來儲存初始化表示式的結果，並使用 Box::into_raw 將其轉換為一個原始指標。

實作細節

以下是 lazy_static 宏的實作細節：

let init_ptr = quote_spanned!{ init.span() =>
    Box::into_raw(Box::new(#init))
};

let expanded = quote!{
    #visibility struct #name;

    impl ::std::ops::Deref for #name {
        type Target = #ty;

        fn deref(&self) -> &#ty {
            #assert_sync
            #assert_sized

            static ONCE: ::std::sync::Once = ::std::sync::Once::new();
            static mut VALUE: *mut #ty = 0 as *mut #ty;

            unsafe {
                ONCE.call_once(|| VALUE = #init_ptr);
                &*VALUE
            }
        }
    }
};

在這個實作中，init_ptr 是一個 TokenStream，它包含了初始化表示式的結果，並使用 Box::into_raw 將其轉換為一個原始指標。

expanded 是另一個 TokenStream，它包含了 lazy_static 宏的實作。它定義了一個空的結構體 #name，並實作了 Deref 特徵。Deref 特徵的 deref 方法傳回一個參照，指向靜態變數的值。

使用示例

以下是使用 lazy_static 宏的示例：

use fnmacros::{three, lazy_static};

lazy_static!{
    static ref FOO: String = String::new();
}

lazy_static!{
    static ref NO: *mut u8 = 0 as *mut u8;
}

lazy_static!{
    static ref VOID: () = ();
}

fn hello(){
    println!("Hello")
}

fn main() {
    three!(hello());
}

在這個示例中，lazy_static 宏被用來定義三個靜態變數：FOO、NO 和 VOID。每個靜態變數都被初始化為一個特定的值。

錯誤和警告

如果我們嘗試編譯這個程式，會出現以下錯誤和警告：

$ cargo build
warning: Name too generic

--> src\main.rs:4:16
|

這個警告是因為 NO 靜態變數的名稱太過於通用。這個警告可以被忽略。

Rust 靜態變數與執行緒安全性

在 Rust 中，靜態變數（static variables）是一種全域性變數，它們的生命週期與程式執行期間相同。然而，當處理靜態變數時，需要注意執行緒安全性（thread safety）的問題。

靜態變數初始化

Rust 不允許使用函式呼叫來初始化靜態變數。這是因為靜態變數需要在編譯時就被初始化，而函式呼叫則是在執行時才會被評估。因此，以下程式碼會產生錯誤：

static ref FOO: String = String::new();

錯誤訊息指出不能使用 () 來初始化靜態值。這是因為 String::new() 是一個函式呼叫，而不是一個常數表示式。

解決方法

如果需要初始化一個靜態的 String，可以使用字面值（literal）：

static FOO: &str = "Hello, World!";

或者，如果需要一個可變的靜態變數，可以使用 lazy_static 宏：

use lazy_static::lazy_static;

lazy_static! {
    static ref FOO: String = String::new();
}

執行緒安全性

Rust 的靜態變數需要滿足執行緒安全性的要求。這意味著靜態變數不能包含任何非執行緒安全的型別，例如 *mut u8。

以下程式碼會產生錯誤：

static ref NO: *mut u8 = 0 as *mut u8;

錯誤訊息指出 *mut u8 不能線上程之間分享。這是因為 *mut u8 是一個可變的指標，它可能會被多個執行緒存取和修改，從而導致資料競爭（data race）。

解決方法

如果需要分享資料在多個執行緒之間，可以使用執行緒安全的型別，例如 std::sync::Arc 或 std::sync::Mutex。

use std::sync::{Arc, Mutex};

static ref NO: Arc<Mutex<u8>> = Arc::new(Mutex::new(0));

內容解密：

靜態變數需要在編譯時被初始化。
函式呼叫不能用來初始化靜態變數。
可以使用 lazy_static 宏來初始化可變的靜態變數。
靜態變數需要滿足執行緒安全性的要求。
可以使用執行緒安全的型別，例如 std::sync::Arc 或 std::sync::Mutex，來分享資料在多個執行緒之間。

圖表翻譯：

  graph LR
    A[靜態變數] -->|初始化|> B[編譯時]
    B -->|限制|> C[不能使用函式呼叫]
    C -->|解決方法|> D[使用字面值或 lazy_static 宏]
    D -->|執行緒安全性|> E[使用 std::sync::Arc 或 std::sync::Mutex]
    E -->|分享資料|> F[多個執行緒]

此圖表展示了 Rust 中靜態變數的初始化、限制、解決方法、執行緒安全性和分享資料的過程。

Rust 宏的世界：宣告式與程式式宏

在 Rust 中，宏是一種強大的工具，允許我們進行超程式設計。超程式設計是指編寫程式碼的程式碼，讓我們可以在編譯時動態生成程式碼。Rust 提供了兩種型別的宏：宣告式宏（declarative macros）和程式式宏（procedural macros）。

宣告式宏

宣告式宏使用 macro_rules! 宏來定義。它們允許我們使用模式匹配來定義宏的行為。宣告式宏的優點是它們易於使用和理解，但是它們的功能有限。

macro_rules! say_hello {
    () => {
        println!("Hello!");
    };
}

fn main() {
    say_hello!();
}

程式式宏

程式式宏使用 proc-macro 屬性來定義。它們允許我們使用 Rust 的語法來定義宏的行為。程式式宏的優點是它們功能強大，但是它們的複雜度也更高。

use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, DeriveInput};

#[proc_macro_derive(MyDerive)]
pub fn my_derive(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    let name = input.ident;
    let expanded = quote! {
        impl #name {
            fn my_method(&self) {
                println!("Hello, {}!", #name);
            }
        }
    };
    TokenStream::from(expanded)
}

宏的選擇

在選擇使用宏時，需要考慮以下幾點：

如果可以使用函式來完成同樣的任務，則應該使用函式來減少編譯時間。
在建立程式式宏時，應該參考 syn 函式函式庫的檔案來瞭解它提供的功能。
應該考慮宏的展開形式，以確定需要什麼和如何傳回最終結果。

Rust 宏：深度探索與最佳實務

從函式重複呼叫、lazy_static 實作到宣告式與程式式宏的比較，本文深入探討了 Rust 宏的應用與原理。透過剖析程式碼範例和流程圖，我們揭示了宏在編譯時期程式碼生成的強大能力。

從技術架構視角來看，Rust 宏系統允許開發者介入編譯過程，藉由模式匹配或 Rust 語法操縱程式碼結構。lazy_static 宏的實作展現瞭如何利用 std::sync::Once 和原始指標巧妙地實作執行緒安全的延遲初始化。然而，靜態變數的初始化限制以及執行緒安全性的考量，需要開發者謹慎處理，例如避免使用非執行緒安全的型別如 *mut u8，並善用 std::sync::Arc 或 std::sync::Mutex 等執行緒安全工具。

效能最佳化方面，雖然宏能生成複雜程式碼，但過度使用可能增加編譯時間。因此，若能以函式實作相同功能，應優先考慮函式。程式式宏的彈性與複雜度更高，適合處理複雜的程式碼轉換，但需要開發者熟悉 syn 和 quote 等函式函式庫。宣告式宏則相對簡潔易懂，適用於較簡單的程式碼生成場景。

展望未來，隨著 Rust 語言的發展，宏系統的功能也將持續增強。預期將出現更多功能更強大、更易於使用的宏函式函式庫，進一步提升 Rust 的開發效率和程式碼表現力。對於 Rust 開發者而言，深入理解宏的運作機制和最佳實務至關重要。建議開發者在設計宏時，仔細考量宏的展開形式、錯誤處理以及與現有程式碼的整合性，並參考社群最佳實務，以確保程式碼的正確性、效率和可維護性。玄貓認為，Rust 宏是強大的程式碼生成工具，但應謹慎使用，並在必要時才發揮其威力，才能在提升開發效率的同時，維持程式碼的簡潔和可讀性。

玄貓

技術愛好者，專注於分享程式開發、雲端技術與 AI 應用的心得體會。

Rust 宏實戰：函式重複呼叫與 LazyStatic 延遲初始化

宏定義

宏使用

圖表翻譯：

內容解密：

Rust 宏的應用：重複呼叫函式

宏的定義

解析函式呼叫

處理函式呼叫

建立函式呼叫向量

重複呼叫函式

建立 TokenStream

傳回 TokenStream

測試

圖表翻譯：

Rust 宏：LazyStatic 的實作

LazyStatic 的結構

實作 Parse 特徵

使用 parse_macro_input!

生成程式碼

完整程式碼

使用

實作 Lazy Static 的 Procedural Macro

定義 LazyStatic 結構體

實作 Parse trait

實作 Procedural Macro lazy_static

圖表翻譯

內容解密

Rust 中的 lazy_static 宏實作

基本原理

實作細節

使用示例

錯誤和警告

Rust 靜態變數與執行緒安全性

靜態變數初始化

解決方法

執行緒安全性

解決方法

內容解密：

圖表翻譯：

Rust 宏的世界：宣告式與程式式宏

宣告式宏

程式式宏

宏的選擇

Rust 宏：深度探索與最佳實務

玄貓

定義 `LazyStatic` 結構體

實作 `Parse` trait

實作 Procedural Macro `lazy_static`