Rollup merge of #118581 - ianrrees:add-drop-note-to-once_lock, r=workingjubilee

OnceLock: Add note about drop and statics

Hi!  Just a minor documentation addition, I've attempted to build docs locally but ran in to issues, so am not 100% sure this change will render correctly.

library/std/src/sync/once_lock.rs

@@ -17,25 +17,36 @@ use crate::sync::Once;
 /// ‘lazy static’ or ‘memoizing’):
 ///
 /// ```
-/// use std::collections::HashMap;
 /// use std::sync::OnceLock;
 ///
-/// fn hash_map() -> &'static HashMap<u32, char> {
+/// struct DeepThought {
-///     static HASHMAP: OnceLock<HashMap<u32, char>> = OnceLock::new();
+///     answer: String,
-///     HASHMAP.get_or_init(|| {
-///         let mut m = HashMap::new();
-///         m.insert(0, 'a');
-///         m.insert(1, 'b');
-///         m.insert(2, 'c');
-///         m
-///     })
 /// }
 ///
-/// // The `HashMap` is built, stored in the `OnceLock`, and returned.
+/// impl DeepThought {
-/// let _ = hash_map();
+/// #   fn great_question() -> String {
+/// #       "42".to_string()
+/// #   }
+/// #
+///     fn new() -> Self {
+///         Self {
+///             // M3 Ultra takes about 16 million years in --release config
+///             answer: Self::great_question(),
+///         }
+///     }
+/// }
 ///
-/// // The `HashMap` is retrieved from the `OnceLock` and returned.
+/// fn computation() -> &'static DeepThought {
-/// let _ = hash_map();
+///     // n.b. static items do not call [`Drop`] on program termination, so if
+///     // [`DeepThought`] impls Drop, that will not be used for this instance.
+///     static COMPUTATION: OnceLock<DeepThought> = OnceLock::new();
+///     COMPUTATION.get_or_init(|| DeepThought::new())
+/// }
+///
+/// // The `DeepThought` is built, stored in the `OnceLock`, and returned.
+/// let _ = computation().answer;
+/// // The `DeepThought` is retrieved from the `OnceLock` and returned.
+/// let _ = computation().answer;
 /// ```
 ///
 /// Writing to a `OnceLock` from a separate thread: