Skip to content

Commit 237a999

Browse files
ehussehuss
committed
Add alternatives for static-mut-refs
This is an attempt to provide more specific examples on how people can safely work around `static-mut-refs`. Closes rust-lang/rust#123059
1 parent d56e0f3 commit 237a999

File tree

1 file changed

+289
-0
lines changed

1 file changed

+289
-0
lines changed

‎src/rust-2024/static-mut-references.md

Lines changed: 289 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,295 @@ In situations where no locally-reasoned abstraction is possible and you are ther
4848
[`addr_of_mut!`]: https://docs.rust-lang.org/core/ptr/macro.addr_of_mut.html
4949
[raw]: ../../reference/expressions/operator-expr.html#raw-borrow-operators
5050

51+
Note that the following examples are just illustrations and are not intended as full-fledged implementations. There are many details for your specific situation that may require alterations to fit your needs. These are intended to help you see different ways to approach your problem. It is recommended to read the documentation for the specific types in the standard library, the reference on [undefined behavior], the [Rustonomicon], and if you are having questions to reach out on one of the Rust forums such as the [Users Forum].
52+
53+
[undefined behavior]: ../../reference/behavior-considered-undefined.html
54+
[Rustonomicon]: ../../nomicon/index.html
55+
[Users Forum]: https://users.rust-lang.org/
56+
57+
### Don't use globals
58+
59+
This is probably something you already know, but if possible it is best to avoid mutable global state. Of course this can be a little more awkward or difficult at times, particularly if you need to pass a mutable reference around between many functions.
60+
61+
### Atomics
62+
63+
The [atomic types][atomics] provide integers, pointers, and booleans that can be used in a `static` (without `mut`).
64+
65+
```rust,edition2024
66+
# use std::sync::atomic::Ordering;
67+
# use std::sync::atomic::AtomicU64;
68+
69+
// Chnage from this:
70+
// static mut COUNTER: u64 = 0;
71+
// to this:
72+
static COUNTER: AtomicU64 = AtomicU64::new(0);
73+
74+
fn main() {
75+
// Be sure to analyze your use case to determine the correct Ordering to use.
76+
COUNTER.fetch_add(1, Ordering::Relaxed);
77+
}
78+
```
79+
80+
[atomics]: ../../std/sync/atomic/index.html
81+
82+
### Mutex or RwLock
83+
84+
When your type is more complex than an atomic, consider using a [`Mutex`] or [`RwLock`] to ensure proper access to the global value.
85+
86+
```rust,edition2024
87+
# use std::sync::Mutex;
88+
# use std::collections::VecDeque;
89+
90+
// Change from this:
91+
// static mut QUEUE: VecDeque<String> = VecDeque::new();
92+
// to this:
93+
static QUEUE: Mutex<VecDeque<String>> = Mutex::new(VecDeque::new());
94+
95+
fn main() {
96+
QUEUE.lock().unwrap().push_back(String::from("abc"));
97+
let first = QUEUE.lock().unwrap().pop_front();
98+
}
99+
```
100+
101+
[`Mutex`]: ../../std/sync/struct.Mutex.html
102+
[`RwLock`]: ../../std/sync/struct.RwLock.html
103+
104+
### OnceLock or LazyLock
105+
106+
If you are using a `static mut` because you need to do some one-time initialization that can't be `const`, you can instead reach for [`OnceLock`] or [`LazyLock`] instead.
107+
108+
```rust,edition2024
109+
# use std::sync::LazyLock;
110+
#
111+
# struct GlobalState;
112+
#
113+
# impl GlobalState {
114+
# fn new() -> GlobalState {
115+
# GlobalState
116+
# }
117+
# fn example(&self) {}
118+
# }
119+
120+
// Instead of some temporary or uninitialized type like:
121+
// static mut STATE: Option<GlobalState> = None;
122+
// use this instead:
123+
static STATE: LazyLock<GlobalState> = LazyLock::new(|| {
124+
GlobalState::new()
125+
});
126+
127+
fn main() {
128+
STATE.example();
129+
}
130+
```
131+
132+
[`OnceLock`] is similar to [`LazyLock`], but can be used if you need to pass information into the constructor, which can work well with single initialization points (like `main`), or if the inputs are available wherever you access the global.
133+
134+
```rust,edition2024
135+
# use std::sync::OnceLock;
136+
#
137+
# struct GlobalState;
138+
#
139+
# impl GlobalState {
140+
# fn new(verbose: bool) -> GlobalState {
141+
# GlobalState
142+
# }
143+
# fn example(&self) {}
144+
# }
145+
#
146+
# struct Args {
147+
# verbose: bool
148+
# }
149+
# fn parse_arguments() -> Args {
150+
# Args { verbose: true }
151+
# }
152+
153+
static STATE: OnceLock<GlobalState> = OnceLock::new();
154+
155+
fn main() {
156+
let args = parse_arguments();
157+
let state = GlobalState::new(args.verbose);
158+
let _ = STATE.set(state);
159+
// ...
160+
STATE.get().unwrap().example();
161+
}
162+
```
163+
164+
[`OnceLock`]: ../../std/sync/struct.OnceLock.html
165+
[`LazyLock`]: ../../std/sync/struct.LazyLock.html
166+
167+
### `no_std` one-time initialization
168+
169+
This example is similar to [`OnceLock`] in that it provides one-time initialization of a global, but it does not require `std` which is useful in a `no_std` context. Assuming your target supports atomics, then you can use an atomic to check for the initialization of the global. The pattern might look something like this:
170+
171+
```rust,edition2024
172+
# use core::sync::atomic::AtomicUsize;
173+
# use core::sync::atomic::Ordering;
174+
#
175+
# struct Args {
176+
# verbose: bool,
177+
# }
178+
# fn parse_arguments() -> Args {
179+
# Args { verbose: true }
180+
# }
181+
#
182+
# struct GlobalState {
183+
# verbose: bool,
184+
# }
185+
#
186+
# impl GlobalState {
187+
# const fn default() -> GlobalState {
188+
# GlobalState { verbose: false }
189+
# }
190+
# fn new(verbose: bool) -> GlobalState {
191+
# GlobalState { verbose }
192+
# }
193+
# fn example(&self) {}
194+
# }
195+
196+
const UNINITIALIZED: usize = 0;
197+
const INITIALIZING: usize = 1;
198+
const INITIALIZED: usize = 2;
199+
200+
static STATE_INITIALIZED: AtomicUsize = AtomicUsize::new(UNINITIALIZED);
201+
static mut STATE: GlobalState = GlobalState::default();
202+
203+
fn set_global_state(state: GlobalState) {
204+
if STATE_INITIALIZED
205+
.compare_exchange(
206+
UNINITIALIZED,
207+
INITIALIZING,
208+
Ordering::SeqCst,
209+
Ordering::SeqCst,
210+
)
211+
.is_ok()
212+
{
213+
// SAFETY: The reads and writes to STATE are guarded with the INITIALIZED guard.
214+
unsafe {
215+
STATE = state;
216+
}
217+
STATE_INITIALIZED.store(INITIALIZED, Ordering::SeqCst);
218+
} else {
219+
panic!("already initialized, or concurrent initialization");
220+
}
221+
}
222+
223+
fn get_state() -> &'static GlobalState {
224+
if STATE_INITIALIZED.load(Ordering::Acquire) != INITIALIZED {
225+
panic!("not initialized");
226+
} else {
227+
// SAFETY: Mutable access is not possible after state has been initialized.
228+
unsafe { &*&raw const STATE }
229+
}
230+
}
231+
232+
fn main() {
233+
let args = parse_arguments();
234+
let state = GlobalState::new(args.verbose);
235+
set_global_state(state);
236+
// ...
237+
let state = get_state();
238+
state.example();
239+
}
240+
```
241+
242+
This example assumes you can put some default value in the static before it is initialized (the const `default` constructor in this example). If that is not possible, consider using either [`MaybeUninit`], dynamic trait dispatch (with a dummy type that implements a trait), or some other approach to have a default placeholder.
243+
244+
[`MaybeUninit`]: ../../core/mem/union.MaybeUninit.html
245+
246+
### Raw pointers
247+
248+
In some cases you can continue to use `static mut`, but avoid creating references. For example, if you just need to pass [raw pointers] into a C library, don't create an intermediate reference. Instead you can use [raw borrow operators], like in the following example:
249+
250+
```rust,edition2024,no_run
251+
# #[repr(C)]
252+
# struct GlobalState {
253+
# value: i32
254+
# }
255+
#
256+
# impl GlobalState {
257+
# const fn new() -> GlobalState {
258+
# GlobalState { value: 0 }
259+
# }
260+
# }
261+
262+
static mut STATE: GlobalState = GlobalState::new();
263+
264+
unsafe extern "C" {
265+
fn example_ffi(state: *mut GlobalState);
266+
}
267+
268+
fn main() {
269+
unsafe {
270+
// Change from this:
271+
// example_ffi(&mut STATE as *mut GlobalState);
272+
// to this:
273+
example_ffi(&raw mut STATE);
274+
}
275+
}
276+
```
277+
278+
Just beware that you still need to uphold the aliasing constraints around mutable pointers. This may require some internal or external synchronization or proofs about how it is used across threads, interrupt handlers, and reentrancy.
279+
280+
[raw borrow operators]: ../../reference/expressions/operator-expr.html#raw-borrow-operators
281+
[raw pointers]: ../../reference/types/pointer.html#raw-pointers-const-and-mut
282+
283+
### `UnsafeCell` with `Sync`
284+
285+
[`UnsafeCell`] does not impl `Sync`, so it cannot be used in a `static`. You can create your own wrapper around [`UnsafeCell`] to add a `Sync` impl so that it can be used in a `static` to implement interior mutability. This approach can be useful if you have external locks or other guarantees that uphold the safety invariants required for mutable pointers.
286+
287+
Note that this is largely the same as the [raw pointers](#raw-pointers) example. The wrapper helps to emphasize how you are using the type, and focus on which safety requirements you should be careful of. But otherwise they are roughly the same.
288+
289+
```rust,edition2024
290+
# use std::cell::UnsafeCell;
291+
#
292+
# fn with_interrupts_disabled<T: Fn()>(f: T) {
293+
# // A real example would disable interrupts.
294+
# f();
295+
# }
296+
#
297+
# #[repr(C)]
298+
# struct GlobalState {
299+
# value: i32,
300+
# }
301+
#
302+
# impl GlobalState {
303+
# const fn new() -> GlobalState {
304+
# GlobalState { value: 0 }
305+
# }
306+
# }
307+
308+
#[repr(transparent)]
309+
pub struct SyncUnsafeCell<T>(UnsafeCell<T>);
310+
311+
unsafe impl<T> Sync for SyncUnsafeCell<T> {}
312+
313+
static STATE: SyncUnsafeCell<GlobalState> = SyncUnsafeCell(UnsafeCell::new(GlobalState::new()));
314+
315+
fn set_value(value: i32) {
316+
with_interrupts_disabled(|| {
317+
let state = STATE.0.get();
318+
unsafe {
319+
// SAFETY: This value is only ever read in our interrupt handler,
320+
// and interrupts are disabled, and we only use this in one thread.
321+
(*state).value = value;
322+
}
323+
});
324+
}
325+
```
326+
327+
The standard library has a nightly-only (unstable) variant of [`UnsafeCell`] called [`SyncUnsafeCell`]. This example above shows a very simplified version of the standard library type, but would be used roughly the same way.
328+
329+
[`UnsafeCell`]: ../../std/cell/struct.UnsafeCell.html
330+
[`SyncUnsafeCell`]: ../../std/cell/struct.SyncUnsafeCell.html
331+
332+
### Safe references
333+
334+
In some cases it may be safe to create a reference of a `static mut`. The whole point of the [`static_mut_refs`] lint is that this is very hard to do correctly! However, that's not to say it is *impossible*. If you have a situation where you can guarantee that the aliasing requirements are upheld, such as guaranteeing the static is narrowly scoped (only used in a small module or function), has some internal or external synchronization, accounts for interrupt handlers and reentrancy, etc., then taking a reference may be fine.
335+
336+
There are two approaches you can take for this. You can either allow the [`static_mut_refs`] lint (preferably as narrowly as you can), or convert raw pointers to a reference, as with `&mut *&raw mut MY_STATIC`.
337+
338+
<!-- TODO: Should we prefer one or the other here? -->
339+
51340
## Migration
52341

53342
There is no automatic migration to fix these references to `static mut`. To avoid undefined behavior you must rewrite your code to use a different approach as recommended in the [Alternatives](#alternatives) section.

0 commit comments

Comments
 (0)