From 00a647e0e6b8cc35ac685709df77c338813345b8 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Sat, 31 May 2025 16:58:51 -0700
Subject: [PATCH] Update global_allocator to use the attribute template

This also adds a little more detail. This is still a little light, and
to some degree that is intentional because there is significant overlap
with the standard library, and the standard library docs do contain a
little more detail.
---
 src/runtime.md | 39 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 37 insertions(+), 2 deletions(-)

diff --git a/src/runtime.md b/src/runtime.md
index f6ffb8b1d..15f026876 100644
--- a/src/runtime.md
+++ b/src/runtime.md
@@ -6,8 +6,43 @@ This section documents features that define some aspects of the Rust runtime.
 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.global_allocator.intro]
+The *`global_allocator` [attribute][attributes]* is used to define a [memory allocator][std::alloc].
+
+> [!EXAMPLE]
+> ```rust
+> use std::alloc::{GlobalAlloc, System, Layout};
+>
+> struct MyAllocator;
+>
+> unsafe impl GlobalAlloc for MyAllocator {
+>     unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
+>         unsafe { System.alloc(layout) }
+>     }
+>
+>     unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
+>         unsafe { System.dealloc(ptr, layout) }
+>     }
+> }
+>
+> #[global_allocator]
+> static GLOBAL: MyAllocator = MyAllocator;
+> ```
+
+r[runtime.global_allocator.syntax]
+The `global_allocator` attribute uses the [MetaWord] syntax and thus does not take any inputs.
+
+r[runtime.global_allocator.allowed-positions]
+The `global_allocator` attribute may only be applied to a [static item] that implements the [`GlobalAlloc`] trait.
+
+r[runtime.global_allocator.duplicates]
+The `global_allocator` attribute may only be specified once on an item.
+
+r[runtime.global_allocator.single]
+At most one `global_allocator` may be specified in the crate graph.
+
+r[runtime.global_allocator.stdlib]
+The `global_allocator` attribute is exported in the [standard library prelude][core::prelude::v1].
 
 r[runtime.windows_subsystem]
 ## The `windows_subsystem` attribute