runtime.md

r[runtime]

The Rust runtime

This section documents features that define some aspects of the Rust runtime.

r[runtime.panic_handler]

The panic_handler attribute

r[runtime.panic_handler.allowed-positions] The panic_handler attribute can only be applied to a function with signature fn(&PanicInfo) -> !.

r[runtime.panic_handler.intro] The function marked with this attribute defines the behavior of panics.

r[runtime.panic_handler.panic-info] The PanicInfo struct contains information about the location of the panic.

r[runtime.panic_handler.unique] There must be a single panic_handler function in the dependency graph of a binary, dylib or cdylib crate.

Below is shown a panic_handler function that logs the panic message and then halts the thread.

#![no_std]

use core::fmt::{self, Write};
use core::panic::PanicInfo;

struct Sink {
    // ..
#    _0: (),
}
#
# impl Sink {
#     fn new() -> Sink { Sink { _0: () }}
# }
#
# impl fmt::Write for Sink {
#     fn write_str(&mut self, _: &str) -> fmt::Result { Ok(()) }
# }

#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
    let mut sink = Sink::new();

    // logs "panicked at '$reason', src/main.rs:27:4" to some `sink`
    let _ = writeln!(sink, "{}", info);

    loop {}
}

r[runtime.panic_handler.std]

Standard behavior

The standard library provides an implementation of panic_handler that defaults to unwinding the stack but that can be changed to abort the process. The standard library's panic behavior can be modified at runtime with the set_hook function.

r[runtime.global_allocator]

The global_allocator attribute

The global_allocator attribute is used on a static item implementing the GlobalAlloc trait to set the global allocator.

r[runtime.windows_subsystem]

The windows_subsystem attribute

r[runtime.windows_subsystem.intro] The windows_subsystem attribute may be applied at the crate level to set the subsystem when linking on a Windows target.

r[runtime.windows_subsystem.syntax] It uses the MetaNameValueStr syntax to specify the subsystem with a value of either console or windows.

r[runtime.windows_subsystem.ignored] This attribute is ignored on non-Windows targets, and for non-bin crate types.

r[runtime.windows_subsystem.console] The "console" subsystem is the default. If a console process is run from an existing console then it will be attached to that console, otherwise a new console window will be created.

r[runtime.windows_subsystem.windows] The "windows" subsystem is commonly used by GUI applications that do not want to display a console window on startup. It will run detached from any existing console.

#![windows_subsystem = "windows"]