core/
process.rs

1//! A module for working with processes.
2//!
3//! Most process-related functionality requires std, but [`abort_immediate`]
4//! is available on all targets.
5
6/// Terminates the process in a violent fashion.
7///
8/// The function will never return and will immediately terminate the current
9/// process in a platform specific "abnormal" manner. As a consequence,
10/// no destructors on the current stack or any other thread's stack
11/// will be run, Rust IO buffers (eg, from `BufWriter`) will not be flushed,
12/// and C stdio buffers will not be flushed.
13///
14/// Unlike [`abort`](../../std/process/fn.abort.html), `abort_immediate` does
15/// not attempt to match C `abort()` or otherwise perform a "clean" abort.
16/// Instead, it emits code that will crash the process with as little overhead
17/// as possible, such as a "halt and catch fire" style instruction. You should
18/// generally prefer using `abort` instead except where the absolute minimum
19/// overhead is required.
20///
21/// # Platform-specific behavior
22///
23/// `abort_immediate` lowers to a trap instruction on *most* architectures; on
24/// some architectures it simply lowers to call the unmangled `abort` function.
25/// The exact behavior is architecture- and system-dependent.
26///
27/// On bare-metal (no OS) systems the trap instruction usually causes a
28/// *hardware* exception to be raised in a *synchronous* fashion; hardware
29/// exceptions have nothing to do with C++ exceptions and are closer in
30/// semantics to POSIX signals.
31///
32/// On hosted applications (applications running under an OS), the trap
33/// instruction *usually* terminates the whole process with an exit code that
34/// corresponds to `SIGILL` or equivalent, *unless* this signal is handled.
35/// Other signals such as `SIGABRT`, `SIGTRAP`, `SIGSEGV`, and `SIGBUS` may be
36/// produced instead, depending on specifics. This is not an exhaustive list.
37///
38/// # Examples
39///
40/// ```no_run
41/// #![feature(abort_immediate)]
42///
43/// use core::process;
44///
45/// fn main() {
46///     println!("aborting");
47///
48///     process::abort_immediate();
49///
50///     // execution never gets here
51/// }
52/// ```
53///
54/// The `abort_immediate` function terminates the process, so the destructor
55/// will not get run on the example below:
56///
57/// ```no_run
58/// #![feature(abort_immediate)]
59///
60/// use core::process;
61///
62/// struct HasDrop;
63///
64/// impl Drop for HasDrop {
65///     fn drop(&mut self) {
66///         println!("This will never be printed!");
67///     }
68/// }
69///
70/// fn main() {
71///     let _x = HasDrop;
72///     process::abort_immediate();
73///     // the destructor implemented for HasDrop will never get run
74/// }
75/// ```
76///
77#[unstable(feature = "abort_immediate", issue = "154601")]
78#[rustc_const_unstable(feature = "abort_immediate", issue = "154601")]
79#[cold]
80#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
81#[doc(alias = "halt")]
82#[doc(alias = "trap")]
83pub const fn abort_immediate() -> ! {
84    crate::intrinsics::abort_immediate()
85}
86
87/// Triggers a debugger breakpoint, pausing execution if possible.
88///
89/// This signals the environment to pause execution if a debugger is attached, and pass control to
90/// the debugger. Execution may then be aborted or continued by the user controlling the debugger.
91///
92/// If possible, this will produce an instruction sequence that allows a debugger to resume *after*
93/// the breakpoint, rather than resuming *at* the breakpoint; however, the exact behavior is
94/// target-specific and debugger-specific, and not guaranteed.
95///
96/// If no debugger is attached, this will typically abort the process but may also continue
97/// execution.
98// NOTE: this is meant to discuss alternatives to `arch::breakpoint`. We may or may not
99// actually want to stabilize both of them.
100#[unstable(feature = "breakpoint", issue = "133724")]
101#[inline(always)]
102pub fn resumable_breakpoint() {
103    crate::intrinsics::breakpoint();
104}
core/process.rs

core/
process.rs
