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
}
},
}