about summary refs log tree commit diff
path: root/library/std
diff options
context:
space:
mode:
Diffstat (limited to 'library/std')
-rw-r--r--library/std/src/fs.rs7
-rw-r--r--library/std/src/panic.rs6
-rw-r--r--library/std/src/panicking.rs14
-rw-r--r--library/std/src/path.rs2
-rw-r--r--library/std/src/sync/lazy_lock.rs60
-rw-r--r--library/std/src/sync/poison.rs2
-rw-r--r--library/std/src/sys/args/common.rs2
-rw-r--r--library/std/src/thread/mod.rs3
8 files changed, 80 insertions, 16 deletions
diff --git a/library/std/src/fs.rs b/library/std/src/fs.rs
index 72ad7c244ee..b3ca118a452 100644
--- a/library/std/src/fs.rs
+++ b/library/std/src/fs.rs
@@ -1111,6 +1111,11 @@ impl File {
     /// `futimes` on macOS before 10.13) and the `SetFileTime` function on Windows. Note that this
     /// [may change in the future][changes].
     ///
+    /// On most platforms, including UNIX and Windows platforms, this function can also change the
+    /// timestamps of a directory. To get a `File` representing a directory in order to call
+    /// `set_times`, open the directory with `File::open` without attempting to obtain write
+    /// permission.
+    ///
     /// [changes]: io#platform-specific-behavior
     ///
     /// # Errors
@@ -1128,7 +1133,7 @@ impl File {
     ///     use std::fs::{self, File, FileTimes};
     ///
     ///     let src = fs::metadata("src")?;
-    ///     let dest = File::options().write(true).open("dest")?;
+    ///     let dest = File::open("dest")?;
     ///     let times = FileTimes::new()
     ///         .set_accessed(src.accessed()?)
     ///         .set_modified(src.modified()?);
diff --git a/library/std/src/panic.rs b/library/std/src/panic.rs
index 234fb284a59..cff4f20b5a8 100644
--- a/library/std/src/panic.rs
+++ b/library/std/src/panic.rs
@@ -108,8 +108,6 @@ impl<'a> PanicHookInfo<'a> {
     /// # Example
     ///
     /// ```should_panic
-    /// #![feature(panic_payload_as_str)]
-    ///
     /// std::panic::set_hook(Box::new(|panic_info| {
     ///     if let Some(s) = panic_info.payload_as_str() {
     ///         println!("panic occurred: {s:?}");
@@ -122,7 +120,7 @@ impl<'a> PanicHookInfo<'a> {
     /// ```
     #[must_use]
     #[inline]
-    #[unstable(feature = "panic_payload_as_str", issue = "125175")]
+    #[stable(feature = "panic_payload_as_str", since = "CURRENT_RUSTC_VERSION")]
     pub fn payload_as_str(&self) -> Option<&str> {
         if let Some(s) = self.payload.downcast_ref::<&str>() {
             Some(s)
@@ -388,7 +386,7 @@ pub fn catch_unwind<F: FnOnce() -> R + UnwindSafe, R>(f: F) -> Result<R> {
 /// ```
 #[stable(feature = "resume_unwind", since = "1.9.0")]
 pub fn resume_unwind(payload: Box<dyn Any + Send>) -> ! {
-    panicking::rust_panic_without_hook(payload)
+    panicking::resume_unwind(payload)
 }
 
 /// Makes all future panics abort directly without running the panic hook or unwinding.
diff --git a/library/std/src/panicking.rs b/library/std/src/panicking.rs
index 7873049d20b..224cd39855a 100644
--- a/library/std/src/panicking.rs
+++ b/library/std/src/panicking.rs
@@ -696,14 +696,14 @@ pub fn begin_panic_handler(info: &core::panic::PanicInfo<'_>) -> ! {
     let msg = info.message();
     crate::sys::backtrace::__rust_end_short_backtrace(move || {
         if let Some(s) = msg.as_str() {
-            rust_panic_with_hook(
+            panic_with_hook(
                 &mut StaticStrPayload(s),
                 loc,
                 info.can_unwind(),
                 info.force_no_backtrace(),
             );
         } else {
-            rust_panic_with_hook(
+            panic_with_hook(
                 &mut FormatStringPayload { inner: &msg, string: None },
                 loc,
                 info.can_unwind(),
@@ -767,7 +767,7 @@ pub const fn begin_panic<M: Any + Send>(msg: M) -> ! {
 
     let loc = Location::caller();
     crate::sys::backtrace::__rust_end_short_backtrace(move || {
-        rust_panic_with_hook(
+        panic_with_hook(
             &mut Payload { inner: Some(msg) },
             loc,
             /* can_unwind */ true,
@@ -792,7 +792,7 @@ fn payload_as_str(payload: &dyn Any) -> &str {
 /// panics, panic hooks, and finally dispatching to the panic runtime to either
 /// abort or unwind.
 #[optimize(size)]
-fn rust_panic_with_hook(
+fn panic_with_hook(
     payload: &mut dyn PanicPayload,
     location: &Location<'_>,
     can_unwind: bool,
@@ -861,7 +861,7 @@ fn rust_panic_with_hook(
 /// This is the entry point for `resume_unwind`.
 /// It just forwards the payload to the panic runtime.
 #[cfg_attr(feature = "panic_immediate_abort", inline)]
-pub fn rust_panic_without_hook(payload: Box<dyn Any + Send>) -> ! {
+pub fn resume_unwind(payload: Box<dyn Any + Send>) -> ! {
     panic_count::increase(false);
 
     struct RewrapBox(Box<dyn Any + Send>);
@@ -885,8 +885,8 @@ pub fn rust_panic_without_hook(payload: Box<dyn Any + Send>) -> ! {
     rust_panic(&mut RewrapBox(payload))
 }
 
-/// An unmangled function (through `rustc_std_internal_symbol`) on which to slap
-/// yer breakpoints.
+/// A function with a fixed suffix (through `rustc_std_internal_symbol`)
+/// on which to slap yer breakpoints.
 #[inline(never)]
 #[cfg_attr(not(test), rustc_std_internal_symbol)]
 #[cfg(not(feature = "panic_immediate_abort"))]
diff --git a/library/std/src/path.rs b/library/std/src/path.rs
index 055e7f81480..e7ba6936435 100644
--- a/library/std/src/path.rs
+++ b/library/std/src/path.rs
@@ -2683,6 +2683,8 @@ impl Path {
     ///
     /// assert_eq!("foo", Path::new("foo.rs").file_prefix().unwrap());
     /// assert_eq!("foo", Path::new("foo.tar.gz").file_prefix().unwrap());
+    /// assert_eq!(".config", Path::new(".config").file_prefix().unwrap());
+    /// assert_eq!(".config", Path::new(".config.toml").file_prefix().unwrap());
     /// ```
     ///
     /// # See Also
diff --git a/library/std/src/sync/lazy_lock.rs b/library/std/src/sync/lazy_lock.rs
index eba849d16da..a40e29a772a 100644
--- a/library/std/src/sync/lazy_lock.rs
+++ b/library/std/src/sync/lazy_lock.rs
@@ -25,6 +25,22 @@ union Data<T, F> {
 ///
 /// [`LazyCell`]: crate::cell::LazyCell
 ///
+/// # Poisoning
+///
+/// If the initialization closure passed to [`LazyLock::new`] panics, the lock will be poisoned.
+/// Once the lock is poisoned, any threads that attempt to access this lock (via a dereference
+/// or via an explicit call to [`force()`]) will panic.
+///
+/// This concept is similar to that of poisoning in the [`std::sync::poison`] module. A key
+/// difference, however, is that poisoning in `LazyLock` is _unrecoverable_. All future accesses of
+/// the lock from other threads will panic, whereas a type in [`std::sync::poison`] like
+/// [`std::sync::poison::Mutex`] allows recovery via [`PoisonError::into_inner()`].
+///
+/// [`force()`]: LazyLock::force
+/// [`std::sync::poison`]: crate::sync::poison
+/// [`std::sync::poison::Mutex`]: crate::sync::poison::Mutex
+/// [`PoisonError::into_inner()`]: crate::sync::poison::PoisonError::into_inner
+///
 /// # Examples
 ///
 /// Initialize static variables with `LazyLock`.
@@ -102,6 +118,10 @@ impl<T, F: FnOnce() -> T> LazyLock<T, F> {
     ///
     /// Returns `Ok(value)` if `Lazy` is initialized and `Err(f)` otherwise.
     ///
+    /// # Panics
+    ///
+    /// Panics if the lock is poisoned.
+    ///
     /// # Examples
     ///
     /// ```
@@ -136,6 +156,15 @@ impl<T, F: FnOnce() -> T> LazyLock<T, F> {
     /// Forces the evaluation of this lazy value and returns a mutable reference to
     /// the result.
     ///
+    /// # Panics
+    ///
+    /// If the initialization closure panics (the one that is passed to the [`new()`] method), the
+    /// panic is propagated to the caller, and the lock becomes poisoned. This will cause all future
+    /// accesses of the lock (via [`force()`] or a dereference) to panic.
+    ///
+    /// [`new()`]: LazyLock::new
+    /// [`force()`]: LazyLock::force
+    ///
     /// # Examples
     ///
     /// ```
@@ -193,6 +222,15 @@ impl<T, F: FnOnce() -> T> LazyLock<T, F> {
     /// This method will block the calling thread if another initialization
     /// routine is currently running.
     ///
+    /// # Panics
+    ///
+    /// If the initialization closure panics (the one that is passed to the [`new()`] method), the
+    /// panic is propagated to the caller, and the lock becomes poisoned. This will cause all future
+    /// accesses of the lock (via [`force()`] or a dereference) to panic.
+    ///
+    /// [`new()`]: LazyLock::new
+    /// [`force()`]: LazyLock::force
+    ///
     /// # Examples
     ///
     /// ```
@@ -227,7 +265,8 @@ impl<T, F: FnOnce() -> T> LazyLock<T, F> {
 }
 
 impl<T, F> LazyLock<T, F> {
-    /// Returns a mutable reference to the value if initialized, or `None` if not.
+    /// Returns a mutable reference to the value if initialized. Otherwise (if uninitialized or
+    /// poisoned), returns `None`.
     ///
     /// # Examples
     ///
@@ -256,7 +295,8 @@ impl<T, F> LazyLock<T, F> {
         }
     }
 
-    /// Returns a reference to the value if initialized, or `None` if not.
+    /// Returns a reference to the value if initialized. Otherwise (if uninitialized or poisoned),
+    /// returns `None`.
     ///
     /// # Examples
     ///
@@ -307,6 +347,14 @@ impl<T, F: FnOnce() -> T> Deref for LazyLock<T, F> {
     /// This method will block the calling thread if another initialization
     /// routine is currently running.
     ///
+    /// # Panics
+    ///
+    /// If the initialization closure panics (the one that is passed to the [`new()`] method), the
+    /// panic is propagated to the caller, and the lock becomes poisoned. This will cause all future
+    /// accesses of the lock (via [`force()`] or a dereference) to panic.
+    ///
+    /// [`new()`]: LazyLock::new
+    /// [`force()`]: LazyLock::force
     #[inline]
     fn deref(&self) -> &T {
         LazyLock::force(self)
@@ -315,6 +363,14 @@ impl<T, F: FnOnce() -> T> Deref for LazyLock<T, F> {
 
 #[stable(feature = "lazy_deref_mut", since = "1.89.0")]
 impl<T, F: FnOnce() -> T> DerefMut for LazyLock<T, F> {
+    /// # Panics
+    ///
+    /// If the initialization closure panics (the one that is passed to the [`new()`] method), the
+    /// panic is propagated to the caller, and the lock becomes poisoned. This will cause all future
+    /// accesses of the lock (via [`force()`] or a dereference) to panic.
+    ///
+    /// [`new()`]: LazyLock::new
+    /// [`force()`]: LazyLock::force
     #[inline]
     fn deref_mut(&mut self) -> &mut T {
         LazyLock::force_mut(self)
diff --git a/library/std/src/sync/poison.rs b/library/std/src/sync/poison.rs
index d5adc9e29b5..31889dcc10f 100644
--- a/library/std/src/sync/poison.rs
+++ b/library/std/src/sync/poison.rs
@@ -11,7 +11,7 @@
 //!
 //! The specifics of how this "poisoned" state affects other threads and whether
 //! the panics are recognized reliably or on a best-effort basis depend on the
-//! primitive. See [#Overview] below.
+//! primitive. See [Overview](#overview) below.
 //!
 //! For the alternative implementations that do not employ poisoning,
 //! see [`std::sync::nonpoison`].
diff --git a/library/std/src/sys/args/common.rs b/library/std/src/sys/args/common.rs
index e787105a05a..33f3794ee63 100644
--- a/library/std/src/sys/args/common.rs
+++ b/library/std/src/sys/args/common.rs
@@ -12,7 +12,7 @@ impl !Sync for Args {}
 
 impl Args {
     #[inline]
-    pub(super) fn new(args: Vec<OsString>) -> Self {
+    pub fn new(args: Vec<OsString>) -> Self {
         Args { iter: args.into_iter() }
     }
 }
diff --git a/library/std/src/thread/mod.rs b/library/std/src/thread/mod.rs
index dff981c900c..8d3ab82ace1 100644
--- a/library/std/src/thread/mod.rs
+++ b/library/std/src/thread/mod.rs
@@ -2018,6 +2018,9 @@ fn _assert_sync_and_send() {
 ///   which may take time on systems with large numbers of mountpoints.
 ///   (This does not apply to cgroup v2, or to processes not in a
 ///   cgroup.)
+/// - It does not attempt to take `ulimit` into account. If there is a limit set on the number of
+///   threads, `available_parallelism` cannot know how much of that limit a Rust program should
+///   take, or know in a reliable and race-free way how much of that limit is already taken.
 ///
 /// On all targets:
 /// - It may overcount the amount of parallelism available when running in a VM
generated by cgit-pink 1.4.1-3-g733a5 (git 2.37.1) at 2025-11-12 15:26:29 +0000