@@ -1428,39 +1428,76 @@ fn _assert_sync_and_send() {
1428
1428
_assert_both :: < Thread > ( ) ;
1429
1429
}
1430
1430
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).
1443
1475
///
1444
1476
/// # Errors
1445
1477
///
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:
1448
1480
///
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 .
1452
1484
///
1453
1485
/// # Examples
1454
1486
///
1455
1487
/// ```
1456
1488
/// # #![allow(dead_code)]
1457
1489
/// #![feature(available_parallelism)]
1458
- /// use std::thread;
1490
+ /// use std::{io, thread} ;
1459
1491
///
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
+ /// }
1461
1497
/// ```
1498
+ #[ doc( alias = "available_concurrency" ) ] // Alias for a previous name we gave this API on unstable.
1462
1499
#[ 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 .
1464
1501
#[ unstable( feature = "available_parallelism" , issue = "74479" ) ]
1465
1502
pub fn available_parallelism ( ) -> io:: Result < NonZeroUsize > {
1466
1503
imp:: available_parallelism ( )
0 commit comments