From d710f8ba1f2ef8b35d3603875b454955d2d2585c Mon Sep 17 00:00:00 2001 From: Vadim Chugunov Date: Wed, 21 Oct 2015 09:59:24 -0700 Subject: Moar comments. --- src/libstd/lib.rs | 9 -------- src/libstd/rt.rs | 5 +++++ src/libstd/sys/common/unwind/gcc.rs | 5 +++++ src/libstd/sys/common/unwind/mod.rs | 41 ++++++++++++++++++++++--------------- 4 files changed, 34 insertions(+), 26 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs index f318cde71bd..a624b352126 100644 --- a/src/libstd/lib.rs +++ b/src/libstd/lib.rs @@ -400,15 +400,6 @@ pub mod __rand { pub use rand::{thread_rng, ThreadRng, Rng}; } -// Rust runtime's startup objects depend on these symbols, so they must be public. -// Since sys_common isn't public, we have to re-export them here explicitly. -#[doc(hidden)] -#[unstable(feature = "eh_frame_registry", issue = "0")] -#[cfg(all(target_os="windows", target_arch = "x86", target_env="gnu"))] -pub mod __frame_registry { - pub use sys_common::unwind::imp::eh_frame_registry::*; -} - // Include a number of private modules that exist solely to provide // the rustdoc documentation for primitive types. Using `include!` // because rustdoc only looks for these modules at the crate level. diff --git a/src/libstd/rt.rs b/src/libstd/rt.rs index 8be0c6f3b3d..44961611b7b 100644 --- a/src/libstd/rt.rs +++ b/src/libstd/rt.rs @@ -32,6 +32,11 @@ use thread::{self, Thread}; // Reexport some of our utilities which are expected by other crates. pub use sys_common::unwind::{begin_unwind, begin_unwind_fmt}; +// Rust runtime's startup objects depend on these symbols, so they must be public. +// Since sys_common isn't public, we have to re-export them here. +#[cfg(all(target_os="windows", target_arch = "x86", target_env="gnu"))] +pub use sys_common::unwind::imp::eh_frame_registry::*; + #[cfg(not(test))] #[lang = "start"] fn lang_start(main: *const u8, argc: isize, argv: *const *const u8) -> isize { diff --git a/src/libstd/sys/common/unwind/gcc.rs b/src/libstd/sys/common/unwind/gcc.rs index 6d82eb7dfb1..0a598b55951 100644 --- a/src/libstd/sys/common/unwind/gcc.rs +++ b/src/libstd/sys/common/unwind/gcc.rs @@ -232,6 +232,7 @@ pub mod eabi { } } +// See docs in the `unwind` module. #[cfg(all(target_os="windows", target_arch = "x86", target_env="gnu", not(test)))] #[lang = "eh_unwind_resume"] #[unwind] @@ -241,6 +242,10 @@ unsafe extern fn rust_eh_unwind_resume(panic_ctx: *mut u8) -> ! { #[cfg(all(target_os="windows", target_arch = "x86", target_env="gnu"))] pub mod eh_frame_registry { + // The implementation of stack unwinding is (for now) deferred to libgcc_eh, however Rust + // crates use these Rust-specific entry points to avoid potential clashes with GCC runtime. + // See also: rtbegin.rs, `unwind` module. + #[link(name = "gcc_eh")] extern { fn __register_frame_info(eh_frame_begin: *const u8, object: *mut u8); diff --git a/src/libstd/sys/common/unwind/mod.rs b/src/libstd/sys/common/unwind/mod.rs index 3978aeb39bc..e42a4694070 100644 --- a/src/libstd/sys/common/unwind/mod.rs +++ b/src/libstd/sys/common/unwind/mod.rs @@ -34,28 +34,35 @@ //! object being thrown, and to decide whether it should be caught at that stack //! frame. Once the handler frame has been identified, cleanup phase begins. //! -//! In the cleanup phase, personality routines invoke cleanup code associated -//! with their stack frames (i.e. destructors). Once stack has been unwound down -//! to the handler frame level, unwinding stops and the last personality routine -//! transfers control to its catch block. +//! In the cleanup phase, the unwinder invokes each personality routine again. +//! This time it decides which (if any) cleanup code needs to be run for +//! the current stack frame. If so, the control is transferred to a special branch +//! in the function body, the "landing pad", which invokes destructors, frees memory, +//! etc. At the end of the landing pad, control is transferred back to the unwinder +//! and unwinding resumes. //! -//! ## Frame unwind info registration +//! Once stack has been unwound down to the handler frame level, unwinding stops +//! and the last personality routine transfers control to the catch block. //! -//! Each module has its own frame unwind info section (usually ".eh_frame"), and -//! unwinder needs to know about all of them in order for unwinding to be able to -//! cross module boundaries. +//! ## `eh_personality` and `eh_unwind_resume` //! -//! On some platforms, like Linux, this is achieved by dynamically enumerating -//! currently loaded modules via the dl_iterate_phdr() API and finding all -//! .eh_frame sections. +//! These language items are used by the compiler when generating unwind info. +//! The first one is the personality routine described above. The second one +//! allows compilation target to customize the process of resuming unwind at the +//! end of the landing pads. `eh_unwind_resume` is used only if `custom_unwind_resume` +//! flag in the target options is set. //! -//! Others, like Windows, require modules to actively register their unwind info -//! sections by calling __register_frame_info() API at startup. In the latter -//! case it is essential that there is only one copy of the unwinder runtime in -//! the process. This is usually achieved by linking to the dynamic version of -//! the unwind runtime. +//! ## Frame unwind info registration //! -//! Currently Rust uses unwind runtime provided by libgcc. +//! Each module's image contains a frame unwind info section (usually ".eh_frame"). +//! When a module is loaded/unloaded into the process, the unwinder must be informed +//! about the location of this section in memory. The methods of achieving that vary +//! by the platform. +//! On some (e.g. Linux), the unwinder can discover unwind info sections on its own +//! (by dynamically enumerating currently loaded modules via the dl_iterate_phdr() API +//! and finding their ".eh_frame" sections); +//! Others, like Windows, require modules to actively register their unwind info +//! sections via unwinder API (see `rust_eh_register_frames`/`rust_eh_unregister_frames`). #![allow(dead_code)] #![allow(unused_imports)] -- cgit 1.4.1-3-g733a5