> ## Documentation Index > Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt > Use this file to discover all available pages before exploring further. # Rust Static Item A `static` item in Rust defines a globally scoped variable with a fixed, unique memory address that persists for the entire duration of the program's execution. Unlike `const` items, which are semantically inlined at each point of use, a `static` item guarantees a single, shared instance in the compiled binary's data segment. ## Syntax A static item is declared using the `static` keyword, followed by an uppercase identifier, a mandatory type annotation, and a constant expression for initialization. ```rust theme={"dark"} // Immutable static item static GLOBAL_TIMEOUT: u64 = 5000; // Mutable static item (highly discouraged in modern Rust) static mut COUNTER: u32 = 0; ``` ## Core Mechanics and Constraints * **Mandatory Type Annotation:** The Rust compiler will not infer the type of a `static` item. The type must be explicitly declared. * **Constant Evaluation:** The initialization value must be a constant expression. It must be fully evaluable at compile time. You cannot initialize a `static` item with the result of a runtime function call (unless that function is a `const fn`). * **Memory Layout:** Immutable `static` items are typically stored in the read-only data segment (`.rodata`) of the binary. Mutable `static` items (`static mut`) are stored in the `.data` or `.bss` segments. They are never allocated on the stack or the heap. * **Implicit Lifetime:** All `static` items inherently possess the `'static` lifetime. Any reference taken to an immutable `static` item (`&GLOBAL_TIMEOUT`) will yield a type of `&'static u64`. * **Destructors:** `Drop` destructors are **never** executed for `static` items when the program terminates. Any resources held by a static item are reclaimed by the operating system upon process exit, bypassing Rust's standard drop semantics. ## Thread Safety and the `Sync` Trait Because `static` items are globally accessible from any thread, Rust enforces strict concurrency rules at compile time. Any type used as an immutable `static` item must implement the `Sync` trait. This guarantees that it is safe for multiple threads to hold shared references (`&T`) to the item concurrently. Types that utilize interior mutability without thread-safe synchronization (such as `RefCell` or `Cell`) are `!Sync` and will cause a compilation error if assigned to a `static` item. ## Mutability, `unsafe`, and References While declaring a `static mut` item is allowed, **reading from or writing to a `static mut` item is inherently `unsafe`**. Global mutable state bypasses Rust's standard borrow checker guarantees, making it trivial to cause data races. Furthermore, in modern Rust (1.79+ and strictly enforced in the 2024 edition), creating **any** reference (shared `&T` or mutable `&mut T`) to a `static mut` is a deny-by-default lint or hard error (`static_mut_refs`). Because guaranteeing exclusive access globally is practically impossible, taking references to `static mut` items is highly prone to undefined behavior via aliasing violations. To interact with a `static mut`, developers must use raw pointers instead of references: ```rust theme={"dark"} static mut ACTIVE_CONNECTIONS: usize = 0; fn increment_connections() { unsafe { // Taking a reference like `&mut ACTIVE_CONNECTIONS` is forbidden. // Raw pointers must be used via macros like `addr_of_mut!`. let ptr = std::ptr::addr_of_mut!(ACTIVE_CONNECTIONS); *ptr += 1; } } ``` ## Safe Alternatives for Global Mutable State Due to the severe safety hazards and strict aliasing rules surrounding `static mut`, its use is highly discouraged. Idiomatic Rust achieves global mutable state by combining immutable `static` items with safe interior mutability primitives. These abstractions enforce synchronization at runtime or utilize hardware-level atomic instructions: * **`std::sync::atomic` types:** Used for simple primitives (e.g., `AtomicUsize`, `AtomicBool`) to guarantee lock-free, thread-safe mutation. * **`std::sync::Mutex` or `std::sync::RwLock`:** Used for complex types requiring exclusive or shared-read/exclusive-write access. * **`std::sync::LazyLock`:** (Available in Rust 1.80+) Used to defer the initialization of complex static data until its first use. It is frequently used to wrap a `Mutex` or `RwLock` when the initialization requires non-const operations. ```rust theme={"dark"} use std::sync::atomic::{AtomicUsize, Ordering}; use std::sync::{LazyLock, Mutex}; // Safe atomic counter static SAFE_COUNTER: AtomicUsize = AtomicUsize::new(0); // Safe complex global state using LazyLock and Mutex static GLOBAL_CONFIG: LazyLock> = LazyLock::new(|| { Mutex::new(String::from("default_configuration")) }); fn update_state() { SAFE_COUNTER.fetch_add(1, Ordering::Relaxed); let mut config = GLOBAL_CONFIG.lock().unwrap(); *config = String::from("updated_configuration"); } ``` ## `static` vs. `const` While both represent compile-time defined values, their memory models differ fundamentally: * **`const`**: Represents a value. The compiler replaces every reference to a `const` with the value itself (inlining). It does not have a guaranteed memory address. * **`static`**: Represents a memory location. All references to a `static` point to the exact same memory address in the compiled binary.

Tired of Poor Rust Skills? Fix That With Deep Grasping! Learn More