static_generics/

namespace.rs

//! Namespaced generic statics with zero-cost access.
//!
//! Each `(Namespace, T)` slot is emitted the way clang emits a C++ template
//! static: a weak, COMDAT-grouped, zero-initialized definition in its own
//! `.bss` section. The address is then computed with the optimal
//! PC-relative sequence for the architecture, so access compiles to 1-2
//! instructions with no runtime overhead on supported targets.
//!
//! ```rust
//! use core::sync::atomic::{AtomicU64, Ordering};
//! use static_generics::{define_namespace, namespace::Namespace};
//!
//! define_namespace!(MyNs);
//!
//! MyNs::generic_static::<AtomicU64>().store(7, Ordering::Relaxed);
//! assert_eq!(MyNs::generic_static::<AtomicU64>().load(Ordering::Relaxed), 7);
//! ```

use cfg_if::cfg_if;
use core::{mem, ptr};

const fn cmp_max(a: usize, b: usize) -> usize {
    if a > b { a } else { b }
}

// log2 of a power-of-two alignment, for `.p2align` (log2 on every object
// format). All Rust alignments are powers of two, so this is exact.
// Unused on fallback-only configurations.
#[allow(dead_code)]
const fn align_log2(align: usize) -> usize {
    let mut log = 0;
    let mut v = align;
    while v > 1 {
        v >>= 1;
        log += 1;
    }
    log
}

/// Wrapper that folds a `const N: usize` key into the slot type.
///
/// `generic_static_const::<T, N>` is implemented as
/// `generic_static::<ConstKey<T, N>>`.
#[repr(transparent)]
struct ConstKey<T, const N: usize>(T);

// SAFETY: single transparent field; all-zero is valid iff it is valid for `T`.
unsafe impl<T, const N: usize> bytemuck::Zeroable for ConstKey<T, N> where T: bytemuck::Zeroable {}

// Dummy generic function generating a unique mangled symbol name per `(NS, T)`.
// The `sym` operand in `slot_addr` extracts this name at compile time.
// Never called; used only as a unique key.
#[inline(never)]
fn unique_symbol<NS: Namespace, T: 'static>() -> core::any::TypeId {
    // Generate *unique* function body per (NS, T) so LLVM function merger or linker do not deduplicate
    // code thus breaking "unique symbol" assumption.
    core::any::TypeId::of::<(NS, T)>()
}

/// Raw address of the zero-initialized slot for `(NS, T)`.
///
/// Storage is defined with weak + COMDAT linkage in a per-symbol `.bss`
/// section, the same way clang emits C++ template statics; the address is
/// then computed with the optimal PC-relative sequence for the
/// architecture. `#[inline(always)]` everywhere except the wasm32 fast path,
/// so access optimizes down to the bare address computation with no call
/// overhead.
// Never inlined on the wasm32 fast path: the inline asm there switches to a
// `.bss` section mid-function and must switch back to the exact enclosing
// function section (`.previous` does not exist on wasm), which is only known
// when the body stays in its own function.
#[cfg_attr(all(target_family = "wasm", feature = "nightly"), inline(never))]
#[cfg_attr(not(all(target_family = "wasm", feature = "nightly")), inline(always))]
// Every fast path defines a named data label (`gen_static_{id}:`), which
// the `named_asm_labels` lint denies by default. This is safe here: the
// label is unique per `(NS, T)` and re-emission in the same object is
// suppressed by the `.ifnotdef` guard.
#[allow(named_asm_labels)]
fn slot_addr<NS, T>() -> *mut T
where
    NS: Namespace,
    T: 'static + bytemuck::Zeroable,
{
    #[allow(unused_assignments)]
    let mut addr: *mut () = ptr::null_mut();

    // 1) define the storage symbol (weak + COMDAT), selected by object
    // format. The wasm32 fast path fuses its definition into the address
    // block below instead
    cfg_if! {
        // Forced slow path: Cranelift backend or Miri.
        if #[cfg(any(static_generics_fallback, miri))] {
        // wasm32 fast path (`nightly` feature): storage is emitted
        // by the fused block below, which must restore the exact enclosing
        // function section afterwards.
        } else if #[cfg(all(
            target_family = "wasm",
            target_arch = "wasm32",
            feature = "nightly"
        ))] {
        // Apple (Mach-O): no COMDAT groups; the linker coalesces by
        // `weak_definition` name. Mirrors clang (`__DATA,__data` even when
        // zeroed, never `__common`).
        } else if #[cfg(target_vendor = "apple")] {
            unsafe {
                core::arch::asm!(
                    ".ifnotdef gen_static_{id}",
                    ".pushsection __DATA,__data",
                    ".globl gen_static_{id}",
                    ".weak_definition gen_static_{id}",
                    ".p2align {p2align}, 0x0",
                    "gen_static_{id}:",
                    ".space {size}",
                    ".popsection",
                    ".endif",
                    size = const { cmp_max(mem::size_of::<T>(), 1) },
                    p2align = const { align_log2(mem::align_of::<T>()) },
                    id = sym unique_symbol::<NS, T>,
                    options(nostack, nomem)
                );
            }
        // Windows/UEFI/Cygwin (COFF/PE): `discard` COMDAT (SELECT_ANY).
        // Mirrors clang (`.section .bss,"bw",discard,"<sym>"` + `.globl`).
        } else if #[cfg(any(
            target_os = "windows",
            target_os = "uefi",
            target_os = "cygwin"
        ))] {
            unsafe {
                core::arch::asm!(
                    ".ifnotdef gen_static_{id}",
                    ".pushsection .bss,\"bw\",discard,gen_static_{id}",
                    ".globl gen_static_{id}",
                    ".p2align {p2align}, 0x0",
                    "gen_static_{id}:",
                    ".zero {size}",
                    ".popsection",
                    ".endif",
                    size = const { cmp_max(mem::size_of::<T>(), 1) },
                    p2align = const { align_log2(mem::align_of::<T>()) },
                    id = sym unique_symbol::<NS, T>,
                    options(nostack, nomem)
                );
            }
        // ELF: `weak` + named `.bss` COMDAT group. Mirrors clang
        // (`.section .bss.<sym>,"awG",@nobits,<sym>,comdat`). Gated on the
        // architectures with an address branch below; anything else —
        // including AIX/XCOFF, which is not ELF — falls through to the slow
        // fallback with no asm emitted.
        } else if #[cfg(all(
            any(
                target_arch = "x86_64",
                target_arch = "aarch64",
                target_arch = "arm64ec",
                target_arch = "x86",
                target_arch = "arm",
                target_arch = "riscv32",
                target_arch = "riscv64",
                target_arch = "loongarch64",
                target_arch = "loongarch32",
                target_arch = "powerpc64",
                target_arch = "powerpc",
                target_arch = "s390x"
            ),
            not(target_os = "aix")
        ))] {
            cfg_if! {
                if #[cfg(target_arch = "arm")] {
                    unsafe {
                        core::arch::asm!(
                            ".ifnotdef gen_static_{id}",
                            ".pushsection .bss.gen_static_{id},\"awG\",%nobits,gen_static_{id},comdat",
                            ".weak gen_static_{id}",
                            ".hidden gen_static_{id}",
                            ".type gen_static_{id},%object",
                            ".p2align {p2align}, 0x0",
                            "gen_static_{id}:",
                            ".zero {size}",
                            ".size gen_static_{id}, {size}",
                            ".popsection",
                            ".endif",
                            size = const { cmp_max(mem::size_of::<T>(), 1) },
                            p2align = const { align_log2(mem::align_of::<T>()) },
                            id = sym unique_symbol::<NS, T>,
                            options(nostack, nomem)
                        );
                    }
                } else {
                    unsafe {
                        core::arch::asm!(
                            ".ifnotdef gen_static_{id}",
                            ".pushsection .bss.gen_static_{id},\"awG\",@nobits,gen_static_{id},comdat",
                            ".weak gen_static_{id}",
                            ".hidden gen_static_{id}",
                            ".type gen_static_{id},@object",
                            ".p2align {p2align}, 0x0",
                            "gen_static_{id}:",
                            ".zero {size}",
                            ".size gen_static_{id}, {size}",
                            ".popsection",
                            ".endif",
                            size = const { cmp_max(mem::size_of::<T>(), 1) },
                            p2align = const { align_log2(mem::align_of::<T>()) },
                            id = sym unique_symbol::<NS, T>,
                            options(nostack, nomem)
                        );
                    }
                }
            }
        } else {
        }
    }

    // 2) compute the slot address (architecture-specific), or take the
    // slow fallback.
    cfg_if! {
        // Forced slow path: Cranelift backend or Miri.
        if #[cfg(any(static_generics_fallback, miri))] {
            #[cfg(feature = "std")]
            {
                addr = crate::fallback::generic_static_fallback_mut::<NS, T>() as *mut T
                    as *mut ();
            }
            #[cfg(not(feature = "std"))]
            core::compile_error!(
                "static-generics: Cranelift/Miri needs the slow fallback (enable `std` feature)"
            );
        // wasm32 fast path (`nightly` feature): storage uses weak +
        // COMDAT linkage in a per-symbol `.bss` section and the address is a single
        // `i32.const` (linker resolves it via `R_WASM_MEMORY_ADDR`). `me`
        // restores the exact enclosing function section afterwards (there is
        // no `.previous` or `.popsection` on wasm), which is why `slot_addr`
        // #[inline(never)]. However, wasm-opt and JIT should be able to inline this
        // function anyways.
        // Covers wasm32-unknown-unknown, wasm32-wasip1/wasip2,
        // wasm32-unknown-emscripten, wasm32v1-none.
        } else if #[cfg(all(
            target_family = "wasm",
            target_arch = "wasm32",
            feature = "nightly"
        ))] {
            unsafe {
                core::arch::asm!(
                    ".ifnotdef gen_static_{id}",
                    ".hidden gen_static_{id}",
                    ".type gen_static_{id},@object",
                    ".section .bss.gen_static_{id},\"G\",@,gen_static_{id},comdat",
                    ".weak gen_static_{id}",
                    ".p2align {align}, 0x0",
                    "gen_static_{id}:",
                    ".skip {size}, 0",
                    ".size gen_static_{id}, {size}",
                    ".section .text.{me},\"\",@",
                    ".endif",
                    "i32.const gen_static_{id}",
                    "local.set {x}",
                    size = const { cmp_max(mem::size_of::<T>(), 1) },
                    align = const { align_log2(mem::align_of::<T>()) },
                    id = sym unique_symbol::<NS, T>,
                    me = sym slot_addr::<NS, T>,
                    x = out(local) addr,
                    options(nostack, nomem)
                );
            }
        // x86-64: RIP-relative LEA works on ELF, Mach-O and COFF, in
        // both PIC and static relocation models. Covers all tier 1-3
        // x86_64 targets (linux, windows, macos, freebsd, netbsd, uefi, etc).
        } else if #[cfg(target_arch = "x86_64")] {
            unsafe {
                core::arch::asm!(
                    "lea {x}, [rip + gen_static_{id}]",
                    id = sym unique_symbol::<NS, T>,
                    x = out(reg) addr,
                    options(nostack, nomem)
                );
            }
        // aarch64 + arm64ec, Apple (Mach-O): ADRP with @PAGE/@PAGEOFF.
        // Covers macos, ios, tvos, watchos, visionos (all Apple, tier 1-3).
        } else if #[cfg(all(target_arch = "aarch64", target_vendor = "apple"))] {
            unsafe {
                core::arch::asm!(
                    "adrp {x}, gen_static_{id}@PAGE",
                    "add {x}, {x}, gen_static_{id}@PAGEOFF",
                    id = sym unique_symbol::<NS, T>,
                    x = out(reg) addr,
                    options(nostack, nomem)
                );
            }
        // aarch64 + arm64ec, non-Apple (ELF and COFF): ADRP with :lo12:.
        // Covers linux, windows, freebsd, netbsd, openbsd, android, none, uefi, etc..
        } else if #[cfg(all(
            any(target_arch = "aarch64", target_arch = "arm64ec"),
            not(target_vendor = "apple")
        ))] {
            unsafe {
                core::arch::asm!(
                    "adrp {x}, gen_static_{id}",
                    "add {x}, {x}, :lo12:gen_static_{id}",
                    id = sym unique_symbol::<NS, T>,
                    x = out(reg) addr,
                    options(nostack, nomem)
                );
            }
        // x86 (32-bit, i386/i586/i686), ELF PIC: GOT-relative via call/pop
        // thunk + GOTOFF. Required because 32-bit x86 has no EIP-relative
        // addressing; absolute R_386_32 is not allowed in PIE/shared.
        } else if #[cfg(all(
            target_arch = "x86",
            not(any(
                target_vendor = "apple",
                target_os = "windows",
                target_os = "uefi",
                target_os = "cygwin",
                target_os = "none"
            ))
        ))] {
            unsafe {
                core::arch::asm!(
                    "call 2f",
                    "2: popl {x}",
                    "addl $_GLOBAL_OFFSET_TABLE_+[.-2b], {x}",
                    "leal gen_static_{id}@GOTOFF({x}), {x}",
                    id = sym unique_symbol::<NS, T>,
                    x = out(reg) addr,
                    options(att_syntax, nomem)
                );
            }
        // x86 (32-bit), Apple (Mach-O) PIC: call/pop + direct PC-relative
        // LEA.
        } else if #[cfg(all(target_arch = "x86", target_vendor = "apple"))] {
            unsafe {
                core::arch::asm!(
                    "call 2f",
                    "2: popl {x}",
                    "leal gen_static_{id}-2b({x}), {x}",
                    id = sym unique_symbol::<NS, T>,
                    x = out(reg) addr,
                    options(att_syntax, nomem)
                );
            }
        // x86 (32-bit), COFF/PE and bare-metal static: absolute address.
        // Windows/UEFI use base relocs (IMAGE_REL_I386_DIR32) so absolute
        // is ASLR-compatible via loader fixups. `none` is static (no PIE).
        // Covers windows-msvc/gnu/gnullvm, uefi, cygwin (tier 1-3).
        } else if #[cfg(all(
            target_arch = "x86",
            any(
                target_os = "windows",
                target_os = "uefi",
                target_os = "cygwin",
                target_os = "none"
            )
        ))] {
            unsafe {
                core::arch::asm!(
                    "lea {x}, [gen_static_{id}]",
                    id = sym unique_symbol::<NS, T>,
                    x = out(reg) addr,
                    options(nostack, nomem)
                );
            }
        // arm (32-bit, ARM/Thumb), COFF/PE: absolute via MOVW/MOVT.
        // Covers thumbv7a-pc-windows-msvc, thumbv7a-uwp-windows-msvc, uefi.
        } else if #[cfg(all(
            target_arch = "arm",
            any(target_os = "windows", target_os = "uefi", target_os = "cygwin")
        ))] {
            unsafe {
                core::arch::asm!(
                    "movw {x}, :lower16:gen_static_{id}",
                    "movt {x}, :upper16:gen_static_{id}",
                    id = sym unique_symbol::<NS, T>,
                    x = out(reg) addr,
                    options(nostack, nomem)
                );
            }
        // arm (32-bit), Thumb mode (thumbv7, thumbv6m, thumbv8m, ...),
        // ELF/Mach-O/bare-metal: literal pool + `add r, pc`.
        // Covers thumbv7neon-linux-gnueabihf, thumbv7em-none-eabi(hf),
        // thumbv6m-none-eabi, thumbv8m-*, armv7s-ios, armv7k-watchos, etc.
        } else if #[cfg(all(
            target_arch = "arm",
            not(any(target_os = "windows", target_os = "uefi", target_os = "cygwin")),
            target_feature = "thumb-mode"
        ))] {
            unsafe {
                core::arch::asm!(
                    "ldr {x}, 2f",
                    "1: add {x}, pc, {x}",
                    "b 3f",
                    "2: .word gen_static_{id}-1b-4",
                    "3:",
                    id = sym unique_symbol::<NS, T>,
                    x = out(reg) addr,
                    options(nostack, nomem)
                );
            }
        // arm (32-bit), ARM mode (armv6/armv7, ...), ELF/Mach-O/bare-metal:
        // Covers armv6/armv7-linux-gnueabi(hf), arm-freebsd/netbsd, none-eabi,
        // android (arm-linux-androideabi, armv7-linux-androideabi), etc.
        } else if #[cfg(all(
            target_arch = "arm",
            not(any(target_os = "windows", target_os = "uefi", target_os = "cygwin")),
            not(target_feature = "thumb-mode")
        ))] {
            unsafe {
                core::arch::asm!(
                    "ldr {x}, 2f",
                    "1: add {x}, pc, {x}",
                    "b 3f",
                    "2: .word gen_static_{id}-1b-8",
                    "3:",
                    id = sym unique_symbol::<NS, T>,
                    x = out(reg) addr,
                    options(nostack, nomem)
                );
            }
        // riscv32 + riscv64: AUIPC + ADDI with %pcrel_hi/%pcrel_lo.
        // PC-relative, works in PIC and static models, on all ELF OSes.
        // Covers riscv64-linux-gnu/musl, riscv32-linux-gnu/musl,
        // riscv*-none-elf, freebsd, netbsd, openbsd, nuttx, vxworks (tier 2-3).
        } else if #[cfg(any(target_arch = "riscv32", target_arch = "riscv64"))] {
            unsafe {
                core::arch::asm!(
                    "1: auipc {x}, %pcrel_hi(gen_static_{id})",
                    "addi {x}, {x}, %pcrel_lo(1b)",
                    id = sym unique_symbol::<NS, T>,
                    x = out(reg) addr,
                    options(nostack, nomem)
                );
            }
        // loongarch64: PCALAU12I + ADDI.D with %pc_hi20/%pc_lo12.
        // PC-relative, PIC- and static-compatible. Covers
        // loongarch64-linux-gnu/musl/ohos, loongarch64-none (tier 2-3).
        } else if #[cfg(target_arch = "loongarch64")] {
            unsafe {
                core::arch::asm!(
                    "pcalau12i {x}, %pc_hi20(gen_static_{id})",
                    "addi.d {x}, {x}, %pc_lo12(gen_static_{id})",
                    id = sym unique_symbol::<NS, T>,
                    x = out(reg) addr,
                    options(nostack, nomem)
                );
            }
        // loongarch32: same as 64-bit but ADDI.W (32-bit addresses).
        // Covers loongarch32-unknown-none(-softfloat) (tier 3).
        } else if #[cfg(target_arch = "loongarch32")] {
            unsafe {
                core::arch::asm!(
                    "pcalau12i {x}, %pc_hi20(gen_static_{id})",
                    "addi.w {x}, {x}, %pc_lo12(gen_static_{id})",
                    id = sym unique_symbol::<NS, T>,
                    x = out(reg) addr,
                    options(nostack, nomem)
                );
            }
        // powerpc64 (BE + LE, ELFv1/v2): TOC-relative via r2.
        // r2 is the reserved TOC base; `sym@toc` is link-time TOC-relative.
        // Covers powerpc64-linux-gnu/musl, powerpc64le-*, freebsd, openbsd (tier 2-3).
        // AIX (XCOFF) excluded - different TOC ABI.
        } else if #[cfg(all(target_arch = "powerpc64", not(target_os = "aix")))] {
            unsafe {
                core::arch::asm!(
                    "addis {x}, 2, gen_static_{id}@toc@ha",
                    "addi {x}, {x}, gen_static_{id}@toc@l",
                    id = sym unique_symbol::<NS, T>,
                    x = out(reg) addr,
                    options(nostack, nomem)
                );
            }
        // powerpc (32-bit): pure PC-relative via BCL/MFLR thunk.
        } else if #[cfg(all(target_arch = "powerpc", not(target_os = "aix")))] {
            unsafe {
                core::arch::asm!(
                    "bcl 20, 31, 1f",
                    "1: mflr {x}",
                    "addis {x}, {x}, (gen_static_{id}-1b)@ha",
                    "addi {x}, {x}, (gen_static_{id}-1b)@l",
                    id = sym unique_symbol::<NS, T>,
                    x = out(reg) addr,
                    out("lr") _,
                    options(nostack, nomem)
                );
            }
        // s390x: LARL (load address relative long).
        } else if #[cfg(target_arch = "s390x")] {
            unsafe {
                core::arch::asm!(
                    "larl {x}, gen_static_{id}",
                    id = sym unique_symbol::<NS, T>,
                    x = out(reg) addr,
                    options(nostack, nomem)
                );
            }
        // Remaining architectures lack support for stable asm or do not allow to efficiently implement generic statics.
        // The fallback to slowpath.
        } else {
            #[cfg(feature = "std")]
            {
                addr = crate::fallback::generic_static_fallback_mut::<NS, T>() as *mut T
                    as *mut ();
            }
            #[cfg(not(feature = "std"))]
            core::compile_error!(
                "static-generics is not supported on this target without the slow fallback (enable `std` feature)"
            );
        }
    }

    // Should error on unsupported targets
    debug_assert!(!addr.is_null(), "unsupported platform");

    addr.cast::<T>()
}

/// A namespace for generic statics.
///
/// # Safety
///
/// Implementing this trait is not unsafe per-se but you should use the [`crate::define_namespace`]
/// instead.
pub unsafe trait Namespace: 'static + Send + Sync + Copy + Clone {
    /// The returned reference points to the static namespaced global variable for each
    /// generic `T`. The static's value is zero-initialized.
    ///
    /// On targets with a fast weak-COMDAT + `asm!` path this compiles to 1-2
    /// instructions with no runtime overhead. Anywhere else (unsupported
    /// architectures, Miri, and the Cranelift backend) the `std` feature enables a
    /// slow `Mutex<HashMap>`-based fallback; without it compilation fails with `compile_error!`.
    #[inline(always)]
    #[must_use]
    fn generic_static<T>() -> &'static T
    where
        T: 'static + bytemuck::Zeroable,
    {
        unsafe { &*slot_addr::<Self, T>() }
    }

    /// The returned reference points to the static namespaced global variable for each
    /// `(T, const N: usize)` pair (with lifetimes erased). The static's value is
    /// zero-initialized.
    ///
    /// This is the `const`-keyed alternative to [`Namespace::generic_static`]: the same
    /// `T` with a different `N` is a different address.
    ///
    /// ```rust
    /// use static_generics::{define_namespace, namespace::Namespace};
    /// use core::sync::atomic::{AtomicU64, Ordering};
    ///
    /// define_namespace!(Counters);
    ///
    /// Counters::generic_static_const::<AtomicU64, 0>().store(1, Ordering::Relaxed);
    /// Counters::generic_static_const::<AtomicU64, 1>().store(2, Ordering::Relaxed);
    /// assert_eq!(Counters::generic_static_const::<AtomicU64, 0>().load(Ordering::Relaxed), 1);
    /// assert_eq!(Counters::generic_static_const::<AtomicU64, 1>().load(Ordering::Relaxed), 2);
    /// ```
    #[inline(always)]
    #[must_use]
    fn generic_static_const<T, const N: usize>() -> &'static T
    where
        T: 'static + bytemuck::Zeroable,
    {
        &Self::generic_static::<ConstKey<T, N>>().0
    }

    /// Raw (`*mut T`) view of the same slot as [`Namespace::generic_static`].
    ///
    /// Equivalent of `static mut` for static generics.
    ///
    /// # Safety
    ///
    /// The pointer itself is always valid (non-null, aligned, valid for `T`,
    /// stable per `(Self, T)`, never dropped). The caller must follow `static mut`
    /// safety rules while the pointer (or anything derived
    /// from it) is used:
    ///
    /// * no other live reference — shared or mutable — to the same slot
    ///   aliases the access.
    /// * no data races.
    /// * the zero-initialized contents are a valid `T` ([`bytemuck::Zeroable`]),
    ///   and the slot is never dropped — do not store types needing `Drop`
    ///   (use `once` for those).
    ///
    /// ```rust
    /// use static_generics::{define_namespace, namespace::Namespace};
    ///
    /// define_namespace!(Counters);
    ///
    /// let ptr = unsafe { Counters::generic_static_mut::<u64>() };
    /// assert!(!ptr.is_null());
    /// unsafe { ptr.write(7) };
    /// assert_eq!(unsafe { ptr.read() }, 7);
    /// // Same slot as the shared view.
    /// assert!(core::ptr::eq(ptr as *const u64, Counters::generic_static::<u64>()));
    /// ```
    #[inline(always)]
    unsafe fn generic_static_mut<T>() -> *mut T
    where
        T: 'static + bytemuck::Zeroable,
    {
        slot_addr::<Self, T>()
    }

    /// Raw (`*mut T`) view of the same slot as
    /// [`Namespace::generic_static_const`]: the same `T` with a different `N`
    /// is a different address.
    ///
    /// # Safety
    ///
    /// Same contract as [`Namespace::generic_static_mut`].
    ///
    /// ```rust
    /// use static_generics::{define_namespace, namespace::Namespace};
    ///
    /// define_namespace!(Counters);
    ///
    /// let a = unsafe { Counters::generic_static_const_mut::<u64, 0>() };
    /// let b = unsafe { Counters::generic_static_const_mut::<u64, 1>() };
    /// assert!(!core::ptr::eq(a, b));
    /// unsafe { a.write(1) };
    /// unsafe { b.write(2) };
    /// assert_eq!(unsafe { a.read() }, 1);
    /// ```
    #[inline(always)]
    unsafe fn generic_static_const_mut<T, const N: usize>() -> *mut T
    where
        T: 'static + bytemuck::Zeroable,
    {
        // SAFETY: `ConstKey` is `#[repr(transparent)]` over `T`, so casting
        // `*mut ConstKey<T, N>` to `*mut T` keeps the same address.
        unsafe { Self::generic_static_mut::<ConstKey<T, N>>().cast::<T>() }
    }
}

/// Extensions on top of [`Namespace::generic_static`] to make using
/// generic statics easier.
pub trait NamespaceExt: Namespace {
    /// Alias for [`Namespace::generic_static`].
    #[inline(always)]
    #[must_use]
    fn get<T>() -> &'static T
    where
        T: 'static + bytemuck::Zeroable,
    {
        Self::generic_static::<T>()
    }

    /// Alias for [`Namespace::generic_static_mut`].
    ///
    /// # Safety
    ///
    /// Same as [`Namespace::generic_static_mut`].
    #[inline(always)]
    unsafe fn get_mut<T>() -> *mut T
    where
        T: 'static + bytemuck::Zeroable,
    {
        // SAFETY: forwarded from the caller upholding the aliasing contract.
        unsafe { Self::generic_static_mut::<T>() }
    }

    /// Lazily-initialized generic static for types that are *not* [`Zeroable`](bytemuck::Zeroable).
    ///
    /// Backed by [`crate::once::OnceSlot`]: the first call runs `init` and
    /// later calls (with the same `NS` and `T`) return the same address.
    ///
    /// ```rust
    /// use static_generics::{define_namespace, namespace::NamespaceExt};
    ///
    /// define_namespace!(MyNs);
    ///
    /// let one = MyNs::once::<String>(|| String::from("hello"));
    /// let two = MyNs::once::<String>(|| String::from("ignored"));
    /// assert_eq!(one.as_str(), "hello");
    /// assert!(core::ptr::eq(one, two));
    /// ```
    #[must_use]
    fn once<T>(init: impl FnOnce() -> T) -> &'static T
    where
        T: 'static + Send + Sync,
    {
        Self::generic_static::<crate::once::OnceSlot<T>>().get_or_init(init)
    }

    /// Alias for [`Namespace::generic_static_const`].
    #[inline(always)]
    #[must_use]
    fn get_const<T, const N: usize>() -> &'static T
    where
        T: 'static + bytemuck::Zeroable,
    {
        Self::generic_static_const::<T, N>()
    }

    /// Alias for [`Namespace::generic_static_const_mut`].
    ///
    /// # Safety
    ///
    /// Same as [`Namespace::generic_static_mut`].
    #[inline(always)]
    unsafe fn get_const_mut<T, const N: usize>() -> *mut T
    where
        T: 'static + bytemuck::Zeroable,
    {
        // SAFETY: forwarded from the caller upholding the aliasing contract.
        unsafe { Self::generic_static_const_mut::<T, N>() }
    }

    /// Lazily-initialized generic static keyed by `(T, const N: usize)`.
    ///
    /// Like [`NamespaceExt::once`], but the same `T` with a different `N`
    /// is a different address. Backed by [`crate::once::OnceSlot`].
    #[must_use]
    fn once_const<T, const N: usize>(init: impl FnOnce() -> T) -> &'static T
    where
        T: 'static + Send + Sync,
    {
        Self::generic_static_const::<crate::once::OnceSlot<T>, N>().get_or_init(init)
    }
}

impl<NS: Namespace> NamespaceExt for NS {}

/// Define a namespace for static generics. Namespace is like "scope" for generics. Were you to always use [`DefaultNamespace`](crate::DefaultNamespace)
/// you would end up with eventually running out of static slots. Defining multiple namespaces allows you to have virtually unlimited
/// set of static generics per each usage.
#[macro_export]
macro_rules! define_namespace {
    ($vis:vis $name:ident) => {
        #[derive(Debug, Copy, Clone)]
        $vis struct $name;

        unsafe impl $crate::namespace::Namespace for $name {}
    };
}

/// Declare a typed accessor function for one generic static.
///
/// ```rust
/// use static_generics::{define_namespace, define_static};
/// use core::sync::atomic::AtomicU64;
///
/// define_namespace!(MyNs);
/// define_static!(pub fn counter<T>() -> AtomicU64; in MyNs);
///
/// counter::<u32>().fetch_add(1, core::sync::atomic::Ordering::Relaxed);
/// ```
#[macro_export]
macro_rules! define_static {
    ($vis:vis fn $name:ident () -> *mut $ty:ty ; in $ns:ty) => {
        $vis unsafe fn $name() -> *mut $ty
        where
            $ty: $crate::Zeroable,
        {
            // SAFETY: caller must follow `static mut` safety rules
            unsafe { <$ns as $crate::namespace::Namespace>::generic_static_mut::<$ty>() }
        }
    };
    ($vis:vis fn $name:ident <$($gen:ident),+ $(,)?> () -> *mut $ty:ty ; in $ns:ty) => {
        $vis unsafe fn $name<$($gen: 'static),+>() -> *mut $ty
        where
            $ty: $crate::Zeroable,
        {
            // SAFETY: caller must follow `static mut` safety rules
            unsafe { <$ns as $crate::namespace::Namespace>::generic_static_mut::<$ty>() }
        }
    };
    ($vis:vis fn $name:ident <const $N:ident : usize $(,)?> () -> *mut $ty:ty ; in $ns:ty) => {
        $vis unsafe fn $name<const $N: usize>() -> *mut $ty
        where
            $ty: $crate::Zeroable,
        {
            // SAFETY: caller must follow `static mut` safety rules
            unsafe { <$ns as $crate::namespace::Namespace>::generic_static_const_mut::<$ty, $N>() }
        }
    };
    ($vis:vis fn $name:ident <$gen:ident, const $N:ident : usize $(,)?> () -> *mut $ty:ty ; in $ns:ty) => {
        $vis unsafe fn $name<$gen: 'static, const $N: usize>() -> *mut $ty
        where
            $ty: $crate::Zeroable,
        {
            // SAFETY: caller must follow `static mut` safety rules
            unsafe { <$ns as $crate::namespace::Namespace>::generic_static_const_mut::<$ty, $N>() }
        }
    };
    ($vis:vis fn $name:ident () -> $ty:ty ; in $ns:ty) => {
        $vis fn $name() -> &'static $ty
        where
            $ty: $crate::Zeroable,
        {
            <$ns as $crate::namespace::Namespace>::generic_static::<$ty>()
        }
    };
    ($vis:vis fn $name:ident <$($gen:ident),+ $(,)?> () -> $ty:ty ; in $ns:ty) => {
        $vis fn $name<$($gen: 'static),+>() -> &'static $ty
        where
            $ty: $crate::Zeroable,
        {
            <$ns as $crate::namespace::Namespace>::generic_static::<$ty>()
        }
    };
    ($vis:vis fn $name:ident <const $N:ident : usize $(,)?> () -> $ty:ty ; in $ns:ty) => {
        $vis fn $name<const $N: usize>() -> &'static $ty
        where
            $ty: $crate::Zeroable,
        {
            <$ns as $crate::namespace::Namespace>::generic_static_const::<$ty, $N>()
        }
    };
    ($vis:vis fn $name:ident <$gen:ident, const $N:ident : usize $(,)?> () -> $ty:ty ; in $ns:ty) => {
        $vis fn $name<$gen: 'static, const $N: usize>() -> &'static $ty
        where
            $ty: $crate::Zeroable,
        {
            <$ns as $crate::namespace::Namespace>::generic_static_const::<$ty, $N>()
        }
    };
}