Rollup merge of #76868 - poliorcetics:intra-doc-std-sync, r=jyn514
Finish moving to intra doc links for std::sync Helps with #75080. @rustbot modify labels: T-doc A-intra-doc-links r? @jyn514
This commit is contained in:
commit
9e2ebf31dd
|
@ -43,11 +43,8 @@ struct BarrierState {
|
|||
generation_id: usize,
|
||||
}
|
||||
|
||||
/// A `BarrierWaitResult` is returned by [`wait`] when all threads in the [`Barrier`]
|
||||
/// have rendezvoused.
|
||||
///
|
||||
/// [`wait`]: struct.Barrier.html#method.wait
|
||||
/// [`Barrier`]: struct.Barrier.html
|
||||
/// A `BarrierWaitResult` is returned by [`Barrier::wait()`] when all threads
|
||||
/// in the [`Barrier`] have rendezvoused.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
@ -70,10 +67,10 @@ impl fmt::Debug for Barrier {
|
|||
impl Barrier {
|
||||
/// Creates a new barrier that can block a given number of threads.
|
||||
///
|
||||
/// A barrier will block `n`-1 threads which call [`wait`] and then wake up
|
||||
/// all threads at once when the `n`th thread calls [`wait`].
|
||||
/// A barrier will block `n`-1 threads which call [`wait()`] and then wake
|
||||
/// up all threads at once when the `n`th thread calls [`wait()`].
|
||||
///
|
||||
/// [`wait`]: #method.wait
|
||||
/// [`wait()`]: Barrier::wait
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
@ -97,12 +94,9 @@ impl Barrier {
|
|||
/// be used continuously.
|
||||
///
|
||||
/// A single (arbitrary) thread will receive a [`BarrierWaitResult`] that
|
||||
/// returns `true` from [`is_leader`] when returning from this function, and
|
||||
/// all other threads will receive a result that will return `false` from
|
||||
/// [`is_leader`].
|
||||
///
|
||||
/// [`BarrierWaitResult`]: struct.BarrierWaitResult.html
|
||||
/// [`is_leader`]: struct.BarrierWaitResult.html#method.is_leader
|
||||
/// returns `true` from [`BarrierWaitResult::is_leader()`] when returning
|
||||
/// from this function, and all other threads will receive a result that
|
||||
/// will return `false` from [`BarrierWaitResult::is_leader()`].
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
@ -156,13 +150,12 @@ impl fmt::Debug for BarrierWaitResult {
|
|||
}
|
||||
|
||||
impl BarrierWaitResult {
|
||||
/// Returns `true` if this thread from [`wait`] is the "leader thread".
|
||||
/// Returns `true` if this thread is the "leader thread" for the call to
|
||||
/// [`Barrier::wait()`].
|
||||
///
|
||||
/// Only one thread will have `true` returned from their result, all other
|
||||
/// threads will have `false` returned.
|
||||
///
|
||||
/// [`wait`]: struct.Barrier.html#method.wait
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
|
|
|
@ -95,10 +95,7 @@ use crate::thread::{self, Thread};
|
|||
|
||||
/// A synchronization primitive which can be used to run a one-time global
|
||||
/// initialization. Useful for one-time initialization for FFI or related
|
||||
/// functionality. This type can only be constructed with the [`Once::new`]
|
||||
/// constructor.
|
||||
///
|
||||
/// [`Once::new`]: struct.Once.html#method.new
|
||||
/// functionality. This type can only be constructed with [`Once::new()`].
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
@ -126,11 +123,8 @@ unsafe impl Sync for Once {}
|
|||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
unsafe impl Send for Once {}
|
||||
|
||||
/// State yielded to [`call_once_force`]’s closure parameter. The state can be
|
||||
/// used to query the poison status of the [`Once`].
|
||||
///
|
||||
/// [`call_once_force`]: struct.Once.html#method.call_once_force
|
||||
/// [`Once`]: struct.Once.html
|
||||
/// State yielded to [`Once::call_once_force()`]’s closure parameter. The state
|
||||
/// can be used to query the poison status of the [`Once`].
|
||||
#[unstable(feature = "once_poison", issue = "33577")]
|
||||
#[derive(Debug)]
|
||||
pub struct OnceState {
|
||||
|
@ -140,8 +134,6 @@ pub struct OnceState {
|
|||
|
||||
/// Initialization value for static [`Once`] values.
|
||||
///
|
||||
/// [`Once`]: struct.Once.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
|
@ -212,7 +204,7 @@ impl Once {
|
|||
/// happens-before relation between the closure and code executing after the
|
||||
/// return).
|
||||
///
|
||||
/// If the given closure recursively invokes `call_once` on the same `Once`
|
||||
/// If the given closure recursively invokes `call_once` on the same [`Once`]
|
||||
/// instance the exact behavior is not specified, allowed outcomes are
|
||||
/// a panic or a deadlock.
|
||||
///
|
||||
|
@ -249,7 +241,7 @@ impl Once {
|
|||
///
|
||||
/// The closure `f` will only be executed once if this is called
|
||||
/// concurrently amongst many threads. If that closure panics, however, then
|
||||
/// it will *poison* this `Once` instance, causing all future invocations of
|
||||
/// it will *poison* this [`Once`] instance, causing all future invocations of
|
||||
/// `call_once` to also panic.
|
||||
///
|
||||
/// This is similar to [poisoning with mutexes][poison].
|
||||
|
@ -269,21 +261,21 @@ impl Once {
|
|||
self.call_inner(false, &mut |_| f.take().unwrap()());
|
||||
}
|
||||
|
||||
/// Performs the same function as [`call_once`] except ignores poisoning.
|
||||
/// Performs the same function as [`call_once()`] except ignores poisoning.
|
||||
///
|
||||
/// Unlike [`call_once`], if this `Once` has been poisoned (i.e., a previous
|
||||
/// call to `call_once` or `call_once_force` caused a panic), calling
|
||||
/// `call_once_force` will still invoke the closure `f` and will _not_
|
||||
/// result in an immediate panic. If `f` panics, the `Once` will remain
|
||||
/// in a poison state. If `f` does _not_ panic, the `Once` will no
|
||||
/// longer be in a poison state and all future calls to `call_once` or
|
||||
/// `call_once_force` will be no-ops.
|
||||
/// Unlike [`call_once()`], if this [`Once`] has been poisoned (i.e., a previous
|
||||
/// call to [`call_once()`] or [`call_once_force()`] caused a panic), calling
|
||||
/// [`call_once_force()`] will still invoke the closure `f` and will _not_
|
||||
/// result in an immediate panic. If `f` panics, the [`Once`] will remain
|
||||
/// in a poison state. If `f` does _not_ panic, the [`Once`] will no
|
||||
/// longer be in a poison state and all future calls to [`call_once()`] or
|
||||
/// [`call_once_force()`] will be no-ops.
|
||||
///
|
||||
/// The closure `f` is yielded a [`OnceState`] structure which can be used
|
||||
/// to query the poison status of the `Once`.
|
||||
/// to query the poison status of the [`Once`].
|
||||
///
|
||||
/// [`call_once`]: struct.Once.html#method.call_once
|
||||
/// [`OnceState`]: struct.OnceState.html
|
||||
/// [`call_once()`]: Once::call_once
|
||||
/// [`call_once_force()`]: Once::call_once_force
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
@ -329,18 +321,20 @@ impl Once {
|
|||
self.call_inner(true, &mut |p| f.take().unwrap()(p));
|
||||
}
|
||||
|
||||
/// Returns `true` if some `call_once` call has completed
|
||||
/// Returns `true` if some [`call_once()`] call has completed
|
||||
/// successfully. Specifically, `is_completed` will return false in
|
||||
/// the following situations:
|
||||
/// * `call_once` was not called at all,
|
||||
/// * `call_once` was called, but has not yet completed,
|
||||
/// * the `Once` instance is poisoned
|
||||
/// * [`call_once()`] was not called at all,
|
||||
/// * [`call_once()`] was called, but has not yet completed,
|
||||
/// * the [`Once`] instance is poisoned
|
||||
///
|
||||
/// This function returning `false` does not mean that `Once` has not been
|
||||
/// This function returning `false` does not mean that [`Once`] has not been
|
||||
/// executed. For example, it may have been executed in the time between
|
||||
/// when `is_completed` starts executing and when it returns, in which case
|
||||
/// the `false` return value would be stale (but still permissible).
|
||||
///
|
||||
/// [`call_once()`]: Once::call_once
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
|
@ -519,14 +513,11 @@ impl Drop for WaiterQueue<'_> {
|
|||
|
||||
impl OnceState {
|
||||
/// Returns `true` if the associated [`Once`] was poisoned prior to the
|
||||
/// invocation of the closure passed to [`call_once_force`].
|
||||
///
|
||||
/// [`call_once_force`]: struct.Once.html#method.call_once_force
|
||||
/// [`Once`]: struct.Once.html
|
||||
/// invocation of the closure passed to [`Once::call_once_force()`].
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// A poisoned `Once`:
|
||||
/// A poisoned [`Once`]:
|
||||
///
|
||||
/// ```
|
||||
/// #![feature(once_poison)]
|
||||
|
@ -547,7 +538,7 @@ impl OnceState {
|
|||
/// });
|
||||
/// ```
|
||||
///
|
||||
/// An unpoisoned `Once`:
|
||||
/// An unpoisoned [`Once`]:
|
||||
///
|
||||
/// ```
|
||||
/// #![feature(once_poison)]
|
||||
|
@ -565,8 +556,6 @@ impl OnceState {
|
|||
}
|
||||
|
||||
/// Poison the associated [`Once`] without explicitly panicking.
|
||||
///
|
||||
/// [`Once`]: struct.Once.html
|
||||
// NOTE: This is currently only exposed for the `lazy` module
|
||||
pub(crate) fn poison(&self) {
|
||||
self.set_state_on_drop_to.set(POISONED);
|
||||
|
|
Loading…
Reference in New Issue