Skip to content

Commit

Permalink
Rollup merge of rust-lang#76868 - poliorcetics:intra-doc-std-sync, r=…
Browse files Browse the repository at this point in the history 
…jyn514

Finish moving to intra doc links for std::sync

Helps with rust-lang#75080.

@rustbot modify labels: T-doc A-intra-doc-links

r? @jyn514
  • Loading branch information
@RalfJung
RalfJung committed Sep 21, 2020
2 parents d93e2b6 + aaddcdb commit a44e0b0
Show file tree
Hide file tree
Showing 2 changed files with 36 additions and 54 deletions.
27 changes: 10 additions & 17 deletions library/std/src/sync/barrier.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
///
Expand All @@ -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
///
Expand All @@ -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
///
Expand Down Expand Up @@ -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
///
/// ```
Expand Down
63 changes: 26 additions & 37 deletions library/std/src/sync/once.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
///
Expand Down Expand Up @@ -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 {
Expand All @@ -140,8 +134,6 @@ pub struct OnceState {

/// Initialization value for static [`Once`] values.
///
/// [`Once`]: struct.Once.html
///
/// # Examples
///
/// ```
Expand Down Expand Up @@ -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.
///
Expand Down Expand Up @@ -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].
Expand All @@ -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
///
Expand Down Expand Up @@ -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
///
/// ```
Expand Down Expand Up @@ -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)]
Expand All @@ -547,7 +538,7 @@ impl OnceState {
/// });
/// ```
///
/// An unpoisoned `Once`:
/// An unpoisoned [`Once`]:
///
/// ```
/// #![feature(once_poison)]
Expand All @@ -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);
Expand Down

0 comments on commit a44e0b0

Please sign in to comment.