1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
//! Rustc 用于手写 MIR 的内部工具。
//!
//! 如果由于某些原因您没有编写 rustc 测试,并且发现自己正在考虑使用此特性,那么请返回。这是*非常*不稳定的。
//! 除了 rustc 测试套件恰好需要的那些东西之外,根本没有尝试使任何东西工作。
//! 如果您打错字,您可能会 ICE。
//! 真的,这不是解决您问题的方法。
//! 考虑改为支持 [稳定的 MIR 项目组](https://github.com/rust-lang/project-stable-mir)。
//!
//! 此模块的文档描述了如何使用此特性。
//! 如果您有兴趣破解实现,大部分文档都位于 `rustc_mir_build/src/build/custom/mod.rs`。
//!
//! 典型用法如下所示:
//!
//! ```rust
//! #![feature(core_intrinsics, custom_mir)]
//!
//! use core::intrinsics::mir::*;
//!
//! #[custom_mir(dialect = "built")]
//! pub fn simple(x: i32) -> i32 {
//!     mir!(
//!         let temp2: i32;
//!
//!         {
//!             let temp1 = x;
//!             Goto(my_second_block)
//!         }
//!
//!         my_second_block = {
//!             temp2 = Move(temp1);
//!             RET = temp2;
//!             Return()
//!         }
//!     )
//! }
//! ```
//!
//! `custom_mir` 属性告诉编译器将函数视为自定义 MIR。
//! 此属性仅适用于函数 - 无法将自定义 MIR 插入另一个函数的中间。
//! `dialect` 和 `phase` 参数指示您要在此处插入哪个 [version of MIR][dialect docs]。
//! 一般来说,如果您希望您的 MIR 被完整的 MIR 管道修改,您将希望使用 `#![custom_mir(dialect = "built")]`,如果您不希望使用 `#![custom_mir(dialect = "runtime", phase = "optimized")]`。
//!
//!
//! [dialect docs]:
//!     https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/enum.MirPhase.html
//!
//! [`mir!`] 宏的输入是:
//!
//!  - `type RET = ...;` 形式的可选返回类注解。如果编译器无法推断 RET 的类型,则可能需要这样做。
//!  - 一个可能为空的本地声明列表。局部变量也可以通过 `let` 声明为内联赋值。类型推断通常有效。阴影没有。
//!  - 基本块列表。其中第一个是开始块,是执行开始的地方。
//!    除了起始块之外的所有块都需要命名,以便以后可以引用它们。
//!     - 每个块都是一个以分号结尾的语句列表,后跟一个终止符。
//!     各种语言句法和终止符的语法被设计为与原生 Rust 中类似概念的语法尽可能相似。
//!     请参见下面的列表。
//!
//! # Examples
//!
//! ```rust
//! #![feature(core_intrinsics, custom_mir)]
//!
//! use core::intrinsics::mir::*;
//!
//! #[custom_mir(dialect = "built")]
//! pub fn choose_load(a: &i32, b: &i32, c: bool) -> i32 {
//!     mir!(
//!         {
//!             match c {
//!                 true => t,
//!                 _ => f,
//!             }
//!         }
//!
//!         t = {
//!             let temp = a;
//!             Goto(load_and_exit)
//!         }
//!
//!         f = {
//!             temp = b;
//!             Goto(load_and_exit)
//!         }
//!
//!         load_and_exit = {
//!             RET = *temp;
//!             Return()
//!         }
//!     )
//! }
//!
//! #[custom_mir(dialect = "built")]
//! fn unwrap_unchecked<T>(opt: Option<T>) -> T {
//!     mir!({
//!         RET = Move(Field(Variant(opt, 1), 0));
//!         Return()
//!     })
//! }
//!
//! #[custom_mir(dialect = "runtime", phase = "optimized")]
//! fn push_and_pop<T>(v: &mut Vec<T>, value: T) {
//!     mir!(
//!         let unused;
//!         let popped;
//!
//!         {
//!             Call(unused, pop, Vec::push(v, value))
//!         }
//!
//!         pop = {
//!             Call(popped, drop, Vec::pop(v))
//!         }
//!
//!         drop = {
//!             Drop(popped, ret)
//!         }
//!
//!         ret = {
//!             Return()
//!         }
//!     )
//! }
//!
//! #[custom_mir(dialect = "runtime", phase = "optimized")]
//! fn annotated_return_type() -> (i32, bool) {
//!     mir!(
//!         type RET = (i32, bool);
//!         {
//!             RET.0 = 1;
//!             RET.1 = true;
//!             Return()
//!         }
//!     )
//! }
//! ```
//!
//! 我们还可以触发在编译器足够晚的阶段发生的编译失败:
//!
//! ```rust,compile_fail
//! #![feature(core_intrinsics, custom_mir)]
//!
//! extern crate core;
//! use core::intrinsics::mir::*;
//!
//! #[custom_mir(dialect = "built")]
//! fn borrow_error(should_init: bool) -> i32 {
//!     mir!(
//!         let temp: i32;
//!
//!         {
//!             match should_init {
//!                 true => init,
//!                 _ => use_temp,
//!             }
//!         }
//!
//!         init = {
//!             temp = 0;
//!             Goto(use_temp)
//!         }
//!
//!         use_temp = {
//!             RET = temp;
//!             Return()
//!         }
//!     )
//! }
//! ```
//!
//! ```text
//! error[E0381]: used binding is possibly-uninitialized
//!   --> test.rs:24:13
//!    |
//! 8  | /     mir!(
//! 9  | |         let temp: i32;
//! 10 | |
//! 11 | |         {
//! ...  |
//! 19 | |             temp = 0;
//!    | |             -------- binding initialized here in some conditions
//! ...  |
//! 24 | |             RET = temp;
//!    | |             ^^^^^^^^^^ value used here but it is possibly-uninitialized
//! 25 | |             Return()
//! 26 | |         }
//! 27 | |     )
//!    | |_____- binding declared here but left uninitialized
//!
//! error: aborting due to previous error
//!
//! For more information about this error, try `rustc --explain E0381`.
//! ```
//!
//! # Syntax
//!
//! 下面的列表详尽地描述了如何创建各种 MIR 构造。
//! 列表中遗漏的任何内容都应假定为不受支持,欢迎 PR。
//!
//! #### Locals
//!
//!  - `_0` 返回本地始终可以通过 `RET` 访问。
//!  - 参数可以通过他们的常规名称访问。
//!  - 所有其他局部变量都需要在某处用 `let` 声明,然后才能通过名称访问。
//!
//! #### Places
//!  - 本地人隐式转换为地点。
//!  - 字段访问、解引用和索引工作正常。
//!  - 变体中的字段可以通过 [`Variant`] 和 [`Field`] 关联函数访问,请参见它们的文档以获取详细信息。
//!
//! #### Operands
//!  - 地方隐式转换为 `Copy` 操作数。
//!  - `Move` 操作数可以通过 [`Move`] 创建。
//!  - Const 块、字面量、命名常量和 const 参数都可以正常工作。
//!  - [`Static`] 和 [`StaticMut`] 可用于创建 `&T` 和 `*mut T` 到静态。这些是 MIR 中的常量,也是访问静态的唯一方法。
//!
//! #### Statements
//!  - 通过正常的 Rust 分配分配语言句子工作。
//!  - [`Retag`], [`StorageLive`], [`StorageDead`], [`Deinit`] 语句有一个关联函数。
//!
//! #### Rvalues
//!
//!  - 操作数隐式转换为 `Use` 右值。
//!  - `&`、`&mut`、`addr_of!` 和 `addr_of_mut!` 都用于创建其关联的右值。
//!  - [`Discriminant`]、[`Len`]、[`CopyForDeref`] 具有关联的函数。
//!  - 一元和二元运算使用其正常的 Rust 语法 --`a * b`、`!c` 等。
//!  - 二元运算 `Offset` 可以通过 [`Offset`] 创建。
//!  - 已检查的二进制操作通过将关联的 binop 包装在 [`Checked`] 中来表示。
//!  - 数组重复语法 (`[foo; 10]`) 创建关联的右值。
//!
//! #### Terminators
//!
//! 自定义 MIR 当前不支持清理块或非平凡展开路径。
//! 因此,没有恢复和中止终结符,并且,可能展开的终结符没有任何方式指示展开块。
//!
//!  - [`Goto`]、[`Return`]、[`Unreachable`]、[`Drop`](Drop()) 有关联函数。
//!  - `match some_int_operand` 变成 `SwitchInt`。每个 arm 应该是 `literal => basic_block`
//!     - 例外的是最后一个 arm,它必须是 `_ => basic_block`,并且对应于 otherwise 分支。
//!  - [`Call`] 也有一个关联函数。该函数的第三个参数是一个普通的函数调用表达式,例如 `my_other_function(a, 5)`。
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!

#![unstable(
    feature = "custom_mir",
    reason = "MIR is an implementation detail and extremely unstable",
    issue = "none"
)]
#![allow(unused_variables, non_snake_case, missing_debug_implementations)]

/// 表示基本块的类型。
///
/// 所有终止符都将此类型作为返回类型。它有助于实现某种类型的安全性。
pub struct BasicBlock;

macro_rules! define {
    ($name:literal, $( #[ $meta:meta ] )* fn $($sig:tt)*) => {
        #[rustc_diagnostic_item = $name]
        #[inline]
        $( #[ $meta ] )*
        pub fn $($sig)* { panic!() }
    }
}

define!("mir_return", fn Return() -> BasicBlock);
define!("mir_goto", fn Goto(destination: BasicBlock) -> BasicBlock);
define!("mir_unreachable", fn Unreachable() -> BasicBlock);
define!("mir_drop", fn Drop<T>(place: T, goto: BasicBlock));
define!("mir_call", fn Call<T>(place: T, goto: BasicBlock, call: T));
define!("mir_storage_live", fn StorageLive<T>(local: T));
define!("mir_storage_dead", fn StorageDead<T>(local: T));
define!("mir_deinit", fn Deinit<T>(place: T));
define!("mir_checked", fn Checked<T>(binop: T) -> (T, bool));
define!("mir_len", fn Len<T>(place: T) -> usize);
define!("mir_copy_for_deref", fn CopyForDeref<T>(place: T) -> T);
define!("mir_retag", fn Retag<T>(place: T));
define!("mir_move", fn Move<T>(place: T) -> T);
define!("mir_static", fn Static<T>(s: T) -> &'static T);
define!("mir_static_mut", fn StaticMut<T>(s: T) -> *mut T);
define!(
    "mir_discriminant",
    /// 获取一个地方的判别式。
    fn Discriminant<T>(place: T) -> <T as ::core::marker::DiscriminantKind>::Discriminant
);
define!("mir_set_discriminant", fn SetDiscriminant<T>(place: T, index: u32));
define!("mir_offset", fn Offset<T, U>(ptr: T, count: U) -> T);
define!(
    "mir_field",
    /// 访问具有某个地方的给定索引的字段。
    ///
    /// 这只有与 [`Variant`] 结合使用才有意义。
    /// 如果您要访问的字段的类型没有变体,您可以使用普通字段投影语法。
    ///
    /// 在 Rust 中没有对变体进行位置投影的正确方法,因此这两个函数是一种解决方法。
    /// 您可以通过 `Field(Variant(place, var_idx), field_idx)` 访问变体的字段,其中 `var_idx` 和 `field_idx` 是合适的字面量。
    /// 一些警告:
    ///
    ///  - `Variant` 的返回类型始终为 `()`。不用担心,仍然会生成正确的 MIR。
    ///  - 在某些情况下,无法推断 `Field` 的返回类型。在这些情况下,您可能需要在函数上注解。
    ///  - 由于 `Field` 是一个函数调用,它不是一个位置表达式,因此在表达式的左侧使用它会被编译器拒绝。
    ///
    ///  [`place!`] 是为解决该问题而提供的宏。
    ///  将赋值的左侧包裹在宏中,以说服编译器它没问题。
    ///
    /// # Examples
    ///
    /// ```rust
    /// #![feature(custom_mir, core_intrinsics)]
    ///
    /// use core::intrinsics::mir::*;
    ///
    /// #[custom_mir(dialect = "built")]
    /// fn unwrap_deref(opt: Option<&i32>) -> i32 {
    ///     mir!({
    ///         RET = *Field::<&i32>(Variant(opt, 1), 0);
    ///         Return()
    ///     })
    /// }
    ///
    /// #[custom_mir(dialect = "built")]
    /// fn set(opt: &mut Option<i32>) {
    ///     mir!({
    ///         place!(Field(Variant(*opt, 1), 0)) = 5;
    ///         Return()
    ///     })
    /// }
    /// ```
    ///
    ///
    ///
    fn Field<F>(place: (), field: u32) -> F
);
define!(
    "mir_variant",
    /// 将具有给定索引的变体投影添加到该位置。
    ///
    /// 有关文档,请参见 [`Field`]。
    fn Variant<T>(place: T, index: u32) -> ()
);
define!(
    "mir_cast_transmute",
    /// 触发一个 `CastKind::Transmute` cast。
    ///
    /// `sizeof(T) != sizeof(U)` 时需要测试 UB,普通 `mem::transmute` 无法生成。
    ///
    fn CastTransmute<T, U>(operand: T) -> U
);
define!(
    "mir_make_place",
    #[doc(hidden)]
    fn __internal_make_place<T>(place: T) -> *mut T
);

/// 用于生成自定义 MIR。
///
/// 有关语法详细信息,请参见模块文档。
/// 这个宏并不神奇 -- 它只是将您的 MIR 转换成更容易在编译器中解析的东西。
#[rustc_macro_transparency = "transparent"]
pub macro mir {
    (
        $(type RET = $ret_ty:ty ;)?
        $(let $local_decl:ident $(: $local_decl_ty:ty)? ;)*

        {
            $($entry:tt)*
        }

        $(
            $block_name:ident = {
                $($block:tt)*
            }
        )*
    ) => {{
        // 首先,我们声明所有基本块。
        $(
            let $block_name: ::core::intrinsics::mir::BasicBlock;
        )*

        {
            // 现在都是局部的
            #[allow(non_snake_case)]
            let RET $(: $ret_ty)?;
            $(
                let $local_decl $(: $local_decl_ty)? ;
            )*

            ::core::intrinsics::mir::__internal_extract_let!($($entry)*);
            $(
                ::core::intrinsics::mir::__internal_extract_let!($($block)*);
            )*

            {
                // 最后是基本块的内容
                ::core::intrinsics::mir::__internal_remove_let!({
                    {}
                    { $($entry)* }
                });
                $(
                    ::core::intrinsics::mir::__internal_remove_let!({
                        {}
                        { $($block)* }
                    });
                )*

                RET
            }
        }
    }}
}

/// Helper 宏允许您将值表达式视为位置表达式。
///
/// 请参见 [`Variant`] 上的文档了解为什么这是必要的以及如何使用它。
pub macro place($e:expr) {
    (*::core::intrinsics::mir::__internal_make_place($e))
}

/// 从一堆语言中提取 `let` 声明的助手宏。
///
/// 这个宏是用 "statement muncher" 策略写的。
/// 每次调用都会从输入中解析出第一条语句,对其执行适当的操作,然后对输入的其余部分递归调用相同的宏。
///
#[doc(hidden)]
pub macro __internal_extract_let {
    // 如果是类似 `let` 的语句,则保留 `let`
    (
        let $var:ident $(: $ty:ty)? = $expr:expr; $($rest:tt)*
    ) => {
        let $var $(: $ty)?;
        ::core::intrinsics::mir::__internal_extract_let!($($rest)*);
    },
    // 由于 #86730,我们必须单独处理 const 块
    (
        let $var:ident $(: $ty:ty)? = const $block:block; $($rest:tt)*
    ) => {
        let $var $(: $ty)?;
        ::core::intrinsics::mir::__internal_extract_let!($($rest)*);
    },
    // 否则什么都不输出
    (
        $stmt:stmt; $($rest:tt)*
    ) => {
        ::core::intrinsics::mir::__internal_extract_let!($($rest)*);
    },
    (
        $expr:expr
    ) => {}
}

/// 从一堆语言中删除 `let` 声明的助手宏。
/// 因为表达式位置宏不能展开成语句 + 表达式,这里需要稍微有点创意。一般的策略也是像上面一样的语句咀嚼,但是在随后的宏调用中宏的输出是 "stored"。通过示例最容易理解:
///
/// ```text
/// invoke!(
///     {
///         {
///             x = 5;
///         }
///         {
///             let d = e;
///             Call()
///         }
///     }
/// )
/// ```
///
/// becomes
///
/// ```text
/// invoke!(
///     {
///         {
///             x = 5;
///             d = e;
///         }
///         {
///             Call()
///         }
///     }
/// )
/// ```
#[doc(hidden)]
pub macro __internal_remove_let {
    // 如果是类似 `let` 的语句,去掉 `let`
    (
        {
            {
                $($already_parsed:tt)*
            }
            {
                let $var:ident $(: $ty:ty)? = $expr:expr;
                $($rest:tt)*
            }
        }
    ) => { ::core::intrinsics::mir::__internal_remove_let!(
        {
            {
                $($already_parsed)*
                $var = $expr;
            }
            {
                $($rest)*
            }
        }
    )},
    // 由于 #86730,我们必须单独处理 const 块
    (
        {
            {
                $($already_parsed:tt)*
            }
            {
                let $var:ident $(: $ty:ty)? = const $block:block;
                $($rest:tt)*
            }
        }
    ) => { ::core::intrinsics::mir::__internal_remove_let!(
        {
            {
                $($already_parsed)*
                $var = const $block;
            }
            {
                $($rest)*
            }
        }
    )},
    // 否则,继续
    (
        {
            {
                $($already_parsed:tt)*
            }
            {
                $stmt:stmt;
                $($rest:tt)*
            }
        }
    ) => { ::core::intrinsics::mir::__internal_remove_let!(
        {
            {
                $($already_parsed)*
                $stmt;
            }
            {
                $($rest)*
            }
        }
    )},
    (
        {
            {
                $($already_parsed:tt)*
            }
            {
                $expr:expr
            }
        }
    ) => {
        {
            $($already_parsed)*
            $expr
        }
    },
}