Apply suggestions, reformulating some paragraphs and improving some examples
This commit is contained in:
parent
2bbc2b3de4
commit
dfd454bd38
1 changed files with 36 additions and 38 deletions
|
@ -1030,22 +1030,39 @@ mod self_upper_keyword {}
|
||||||
//
|
//
|
||||||
/// A place that is valid for the duration of a program.
|
/// A place that is valid for the duration of a program.
|
||||||
///
|
///
|
||||||
/// A `static` item is similar to a [`const`] item in that it lives for the
|
/// A static item is a value which is valid for the entire duration of your
|
||||||
/// entire duration of the program and need to have its type explicited, with a
|
/// program (a `'static` lifetime).
|
||||||
/// `static` lifetime, outliving any other lifetime. Added to that, `static`
|
///
|
||||||
/// items represent a precise memory location.
|
/// On the surface, `static` items seem very similar to [`const`]s: both contain
|
||||||
|
/// a value, both require type annotations and both can only be initialized with
|
||||||
|
/// constant functions and values. However, `static`s are notably different in
|
||||||
|
/// that they represent a location in memory. That means that you can have
|
||||||
|
/// references to `static` items and potentially even modify them, making them
|
||||||
|
/// essentially global variables.
|
||||||
///
|
///
|
||||||
/// Static items do not call [`drop`] at the end of the program.
|
/// Static items do not call [`drop`] at the end of the program.
|
||||||
///
|
///
|
||||||
/// There are two types of `static` items: those declared in association with
|
/// There are two types of `static` items: those declared in association with
|
||||||
/// the [`mut`] keyword and those without.
|
/// the [`mut`] keyword and those without.
|
||||||
///
|
///
|
||||||
|
/// Items that are both static and owned cannot be moved:
|
||||||
|
///
|
||||||
|
/// ```rust,compile_fail,E0507
|
||||||
|
/// static VEC: Vec<u32> = vec![];
|
||||||
|
///
|
||||||
|
/// fn move_vec(v: Vec<u32>) -> Vec<u32> {
|
||||||
|
/// v
|
||||||
|
/// }
|
||||||
|
///
|
||||||
|
/// move_vec(VEC);
|
||||||
|
/// ```
|
||||||
|
///
|
||||||
/// # Simple `static`s
|
/// # Simple `static`s
|
||||||
///
|
///
|
||||||
/// Non-[`mut`] `static` items that contain a type that is not interior mutable
|
/// Accessing non-[`mut`] `static` items is considered safe, but some
|
||||||
/// may be placed in read-only memory. All access to a `static` item are
|
/// restrictions apply. Most notably, the type of a `static` value needs to
|
||||||
/// considered safe but some restrictions apply. See the [Reference] for more
|
/// implement the [`Sync`] trait, ruling out interior mutability containers
|
||||||
/// information.
|
/// like [`RefCell`]. See the [Reference] for more information.
|
||||||
///
|
///
|
||||||
/// ```rust
|
/// ```rust
|
||||||
/// static FOO: [i32; 5] = [1, 2, 3, 4, 5];
|
/// static FOO: [i32; 5] = [1, 2, 3, 4, 5];
|
||||||
|
@ -1054,43 +1071,22 @@ mod self_upper_keyword {}
|
||||||
/// let r2 = &FOO as *const _;
|
/// let r2 = &FOO as *const _;
|
||||||
/// // With a strictly read-only static, references will have the same adress
|
/// // With a strictly read-only static, references will have the same adress
|
||||||
/// assert_eq!(r1, r2);
|
/// assert_eq!(r1, r2);
|
||||||
|
/// // A static item is used just like a variable
|
||||||
|
/// println!("{:?}", FOO);
|
||||||
/// ```
|
/// ```
|
||||||
///
|
///
|
||||||
/// # Mutable `static`s
|
/// # Mutable `static`s
|
||||||
///
|
///
|
||||||
/// If a `static` item is declared with the [`mut`] keyword, then it is allowed
|
/// If a `static` item is declared with the [`mut`] keyword, then it is allowed
|
||||||
/// to be modified by the program. To make concurrency bugs hard to run into,
|
/// to be modified by the program. However, accessing mutable `static`s can
|
||||||
/// all access to a `static mut` require an [`unsafe`] block. Care should be
|
/// cause undefined behavior in a number of ways, for example due to data races
|
||||||
/// taken to ensure access (both read and write) are thread-safe.
|
/// in a multithreaded context. As such, all accesses to mutable `static`s
|
||||||
|
/// require an [`unsafe`] block.
|
||||||
///
|
///
|
||||||
/// Despite their unsafety, mutable `static`s are very useful: they can be used
|
/// Despite their unsafety, mutable `static`s are necessary in many contexts:
|
||||||
/// to represent global state shared by the whole program or be used in
|
/// they can be used to represent global state shared by the whole program or in
|
||||||
/// [`extern`] blocks to bind to variables from C libraries.
|
/// [`extern`] blocks to bind to variables from C libraries.
|
||||||
///
|
///
|
||||||
/// As global state:
|
|
||||||
///
|
|
||||||
/// ```rust
|
|
||||||
/// # #![allow(unused_variables)]
|
|
||||||
/// # fn main() {}
|
|
||||||
/// # 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;
|
|
||||||
/// }
|
|
||||||
///
|
|
||||||
/// // 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);
|
|
||||||
/// }
|
|
||||||
/// ```
|
|
||||||
///
|
|
||||||
/// In an [`extern`] block:
|
/// In an [`extern`] block:
|
||||||
///
|
///
|
||||||
/// ```rust,no_run
|
/// ```rust,no_run
|
||||||
|
@ -1108,7 +1104,9 @@ mod self_upper_keyword {}
|
||||||
/// [`mut`]: keyword.mut.html
|
/// [`mut`]: keyword.mut.html
|
||||||
/// [`unsafe`]: keyword.unsafe.html
|
/// [`unsafe`]: keyword.unsafe.html
|
||||||
/// [`drop`]: mem/fn.drop.html
|
/// [`drop`]: mem/fn.drop.html
|
||||||
/// [Reference]: ../reference/items/static-items.html#static-items
|
/// [`Sync`]: marker/trait.Sync.html
|
||||||
|
/// [`RefCell`]: cell/struct.RefCell.html
|
||||||
|
/// [Reference]: ../reference/items/static-items.html
|
||||||
mod static_keyword {}
|
mod static_keyword {}
|
||||||
|
|
||||||
#[doc(keyword = "struct")]
|
#[doc(keyword = "struct")]
|
||||||
|
|
Loading…
Reference in a new issue