Skip to content

Finish moving to intra doc links for std::sync #76868

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 21, 2020
Merged

Finish moving to intra doc links for std::sync #76868

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bffd211
Finish moving to intra doc links for std::sync
poliorcetics Sep 18, 2020
b534d9f
Fix broken link
poliorcetics Sep 18, 2020
aaddcdb
Fix nits
poliorcetics Sep 20, 2020
File filter

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 10 additions & 17 deletions library/std/src/sync/barrier.rs
View file
Open in desktop
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 from [`Barrier::wait()`] is the
/// "leader thread".
///
/// 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
62 changes: 26 additions & 36 deletions library/std/src/sync/once.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,11 +95,9 @@ 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`]
/// functionality. This type can only be constructed with the [`Once::new()`]
/// constructor.
///
/// [`Once::new`]: struct.Once.html#method.new
///
/// # Examples
///
/// ```
Expand All @@ -126,11 +124,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`].
Copy link
Member

@jyn514 jyn514 Sep 18, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using "once" as a noun makes me uncomfortable :( unfortunately the name is stable so not much we can do about it
Copy link
Contributor Author

@poliorcetics poliorcetics Sep 20, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure what to do about it. I thought up some alternate wordings but they are not any better IMO:

  • the Once instance
  • the original Once
Copy link
Member

@jyn514 jyn514 Sep 20, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I don't think it needs to change, it's just unfortunate. 'the Once' makes it clear you're talking about an instance of the struct, it just sounds weird.
#[unstable(feature = "once_poison", issue = "33577")]
#[derive(Debug)]
pub struct OnceState {
Expand All @@ -140,8 +135,6 @@ pub struct OnceState {

/// Initialization value for static [`Once`] values.
///
/// [`Once`]: struct.Once.html
///
/// # Examples
///
/// ```
Expand Down Expand Up @@ -212,7 +205,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 +242,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 +262,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 +322,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 +514,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 +539,7 @@ impl OnceState {
/// });
/// ```
///
/// An unpoisoned `Once`:
/// An unpoisoned [`Once`]:
///
/// ```
/// #![feature(once_poison)]
Expand All @@ -565,8 +557,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