Update mutable static items example for modern Rust.

This updates the mutable static item example to fix some issues with how
it works and how it is presented.

First, the unsafe operations are wrapped in an `unsafe` block so that it
doesn't trigger `unsafe_op_in_unsafe_fn`.

Second, it switches the mutation example to use addr_of_mut to avoid the
undefined behavior, and to compile correctly in 2024 edition.

Third, it rewrites the second example to be safe with a different
description. My understanding is that the original example was written
at a time when it was considered that any potential race condition was
considered unsafe. However, that is no longer a widely held view. The
example has been rewritten to illustrate the two different ways you can
wrap mutable static access.

Author: ehuss

src/items/static-items.md

@@ -88,23 +88,30 @@ Mutable statics are still very useful, however. They can be used with C
 libraries and can also be bound from C libraries in an `extern` block.
 
 ```rust
-# fn atomic_add(_: &mut u32, _: u32) -> u32 { 2 }
+# fn atomic_add(_: *mut u32, _: u32) -> u32 { 2 }
 
 static mut LEVELS: u32 = 0;
 
 // This violates the idea of no shared state, and this doesn't internally
 // protect against races, so this function is `unsafe`
-unsafe fn bump_levels_unsafe1() -> u32 {
-    let ret = LEVELS;
-    LEVELS += 1;
-    return ret;
+unsafe fn bump_levels_unsafe() -> u32 {
+    unsafe {
+        let ret = LEVELS;
+        LEVELS += 1;
+        return ret;
+    }
 }
 
-// Assuming that we have an atomic_add function which returns the old value,
-// this function is "safe" but the meaning of the return value may not be what
-// callers expect, so it's still marked as `unsafe`
-unsafe fn bump_levels_unsafe2() -> u32 {
-    return atomic_add(&mut LEVELS, 1);
+// As an alternative to `bump_levels_unsafe`, this function is safe, assuming
+// that we have an atomic_add function which returns the old value. This
+// function is safe only if no other code accesses the static in a non-atomic
+// fashion. If such accesses are possible (such as in `bump_levels_unsafe`),
+// then this would need to be `unsafe` to indicate to the caller that they
+// must still guard against concurrent access.
+fn bump_levels_safe() -> u32 {
+    unsafe {
+        return atomic_add(std::ptr::addr_of_mut!(LEVELS), 1);
+    }
 }
 ```