@@ -1428,39 +1428,76 @@ fn _assert_sync_and_send() {
14281428 _assert_both :: < Thread > ( ) ;
14291429}
14301430
1431- /// Returns the number of hardware threads available to the program.
1432- ///
1433- /// This value should be considered only a hint.
1434- ///
1435- /// # Platform-specific behavior
1436- ///
1437- /// If interpreted as the number of actual hardware threads, it may undercount on
1438- /// Windows systems with more than 64 hardware threads. If interpreted as the
1439- /// available concurrency for that process, it may overcount on Windows systems
1440- /// when limited by a process wide affinity mask or job object limitations, and
1441- /// it may overcount on Linux systems when limited by a process wide affinity
1442- /// mask or affected by cgroups limits.
1431+ /// Returns an estimate of the default amount of parallelism a program should use.
1432+ ///
1433+ /// Parallelism is a resource. A given machine provides a certain capacity for
1434+ /// parallelism, i.e., a bound on the number of computations it can perform
1435+ /// simultaneously. This number often corresponds to the amount of CPUs or
1436+ /// computer has, but it may diverge in various cases.
1437+ ///
1438+ /// Host environments such as VMs or container orchestrators may want to
1439+ /// restrict the amount of parallelism made available to programs in them. This
1440+ /// is often done to limit the potential impact of (unintentionally)
1441+ /// resource-intensive programs on other programs running on the same machine.
1442+ ///
1443+ /// # Limitations
1444+ ///
1445+ /// The purpose of this API is to provide an easy and portable way to query
1446+ /// the default amount of parallelism the program should use. Among other things it
1447+ /// does not expose information on NUMA regions, does not account for
1448+ /// differences in (co)processor capabilities, and will not modify the program's
1449+ /// global state in order to more accurately query the amount of available
1450+ /// parallelism.
1451+ ///
1452+ /// The value returned by this function should be considered a simplified
1453+ /// approximation of the actual amount of parallelism available at any given
1454+ /// time. To get a more detailed or precise overview of the amount of
1455+ /// parallelism available to the program, you may wish to use
1456+ /// platform-specific APIs as well. The following platform limitations currently
1457+ /// apply to `available_parallelism`:
1458+ ///
1459+ /// On Windows:
1460+ /// - It may undercount the amount of parallelism available on systems with more
1461+ /// than 64 logical CPUs. However, programs typically need specific support to
1462+ /// take advantage of more than 64 logical CPUs, and in the absence of such
1463+ /// support, the number returned by this function accurately reflects the
1464+ /// number of logical CPUs the program can use by default.
1465+ /// - It may overcount the amount of parallelism available on systems limited by
1466+ /// process-wide affinity masks, or job object limitations.
1467+ ///
1468+ /// On Linux:
1469+ /// - It may overcount the amount of parallelism available when limited by a
1470+ /// process-wide affinity mask, or when affected by cgroup limits.
1471+ ///
1472+ /// On all targets:
1473+ /// - It may overcount the amount of parallelism available when running in a VM
1474+ /// with CPU usage limits (e.g. an overcommitted host).
14431475///
14441476/// # Errors
14451477///
1446- /// This function will return an error in the following situations, but is not
1447- /// limited to just these cases:
1478+ /// This function will, but is not limited to, return errors in the following
1479+ /// cases:
14481480///
1449- /// - If the number of hardware threads is not known for the target platform.
1450- /// - The process lacks permissions to view the number of hardware threads
1451- /// available.
1481+ /// - If the amount of parallelism is not known for the target platform.
1482+ /// - If the program lacks permission to query the amount of parallelism made
1483+ /// available to it .
14521484///
14531485/// # Examples
14541486///
14551487/// ```
14561488/// # #![allow(dead_code)]
14571489/// #![feature(available_parallelism)]
1458- /// use std::thread;
1490+ /// use std::{io, thread} ;
14591491///
1460- /// let count = thread::available_parallelism().map(|n| n.get()).unwrap_or(1);
1492+ /// fn main() -> io::Result<()> {
1493+ /// let count = thread::available_parallelism()?.get();
1494+ /// assert!(count >= 1_usize);
1495+ /// Ok(())
1496+ /// }
14611497/// ```
1498+ #[ doc( alias = "available_concurrency" ) ] // Alias for a previous name we gave this API on unstable.
14621499#[ doc( alias = "hardware_concurrency" ) ] // Alias for C++ `std::thread::hardware_concurrency`.
1463- #[ doc( alias = "available_concurrency " ) ] // Alias for a name we gave this API on unstable .
1500+ #[ doc( alias = "num_cpus " ) ] // Alias for a popular ecosystem crate which provides similar functionality .
14641501#[ unstable( feature = "available_parallelism" , issue = "74479" ) ]
14651502pub fn available_parallelism ( ) -> io:: Result < NonZeroUsize > {
14661503 imp:: available_parallelism ( )
0 commit comments