Skip to content

Adding links for Atomics docs #29377 #40871

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 2 commits into from
Apr 1, 2017
Merged

Adding links for Atomics docs #29377 #40871

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
756f224
Adding links for Atomics docs #29377
projektir Mar 28, 2017
4ea03c8
Fixing formatting issues #29377
projektir Mar 29, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 66 additions & 38 deletions src/libcore/sync/atomic.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,27 +15,37 @@
//! types.
//!
//! This module defines atomic versions of a select number of primitive
//! types, including `AtomicBool`, `AtomicIsize`, and `AtomicUsize`.
//! types, including [`AtomicBool`], [`AtomicIsize`], and [`AtomicUsize`].
//! Atomic types present operations that, when used correctly, synchronize
//! updates between threads.
//!
//! Each method takes an `Ordering` which represents the strength of
//! [`AtomicBool`]: struct.AtomicBool.html
//! [`AtomicIsize`]: struct.AtomicIsize.html
//! [`AtomicUsize`]: struct.AtomicUsize.html
//!
//! Each method takes an [`Ordering`] which represents the strength of
//! the memory barrier for that operation. These orderings are the
//! same as [LLVM atomic orderings][1]. For more information see the [nomicon][2].
//!
//! [`Ordering`]: enum.Ordering.html
//!
//! [1]: http://llvm.org/docs/LangRef.html#memory-model-for-concurrent-operations
//! [2]: ../../../nomicon/atomics.html
//!
//! Atomic variables are safe to share between threads (they implement `Sync`)
//! Atomic variables are safe to share between threads (they implement [`Sync`])
//! but they do not themselves provide the mechanism for sharing and follow the
//! [threading model](../../../std/thread/index.html#the-threading-model) of rust.
//! The most common way to share an atomic variable is to put it into an `Arc` (an
//! The most common way to share an atomic variable is to put it into an [`Arc`][arc] (an
//! atomically-reference-counted shared pointer).
//!
//! [`Sync`]: ../../marker/trait.Sync.html
//! [arc]: ../struct.Arc.html
Copy link
Member

Choose a reason for hiding this comment

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

https://travis-ci.org/rust-lang/rust/jobs/215789767#L8942 (It says this link is broken.)

The reason for this is that these docs also get rendered for libcore, not just libstd. So can you change it to ../../../std/sync/struct.Arc.html? Tricky!

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yeah, I had some issues with this one. I wasn't sure if a longer path was better for this to get linked in both place correctly. I'll play around it some more.

Copy link
Member

Choose a reason for hiding this comment

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

For now it is, yeah. Someday...

//!
//! Most atomic types may be stored in static variables, initialized using
//! the provided static initializers like `ATOMIC_BOOL_INIT`. Atomic statics
//! the provided static initializers like [`ATOMIC_BOOL_INIT`]. Atomic statics
//! are often used for lazy global initialization.
//!
//! [`ATOMIC_BOOL_INIT`]: constant.ATOMIC_BOOL_INIT.html
//!
//! # Examples
//!
Expand Down Expand Up @@ -149,21 +159,26 @@ unsafe impl<T> Sync for AtomicPtr<T> {}
#[derive(Copy, Clone, Debug)]
pub enum Ordering {
/// No ordering constraints, only atomic operations. Corresponds to LLVM's
/// `Monotonic` ordering.
/// [`Monotonic`][1] ordering.
/// [1]: http://llvm.org/docs/Atomics.html#monotonic
Copy link
Member

Choose a reason for hiding this comment

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

While you're here, would you mind helping with a minor formatting issue as well? This should look like this:

     /// No ordering constraints, only atomic operations.
     ///
     /// Corresponds to LLVM's [`Monotonic`] ordering.
     ///
     /// [`Monotonic`]: http://llvm.org/docs/Atomics.html#monotonic

Thanks 😄

#[stable(feature = "rust1", since = "1.0.0")]
Relaxed,
/// When coupled with a store, all previous writes become visible
/// to the other threads that perform a load with `Acquire` ordering
/// to the other threads that perform a load with [`Acquire`][1] ordering
/// on the same value.
/// [1]: http://llvm.org/docs/Atomics.html#acquire
Copy link
Member

Choose a reason for hiding this comment

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

Similar here, could this be

    /// to the other threads that perform a load with [`Acquire`] ordering
    /// on the same value.
    ///
    /// [`Aquire`]: http://llvm.org/docs/Atomics.html#acquire

#[stable(feature = "rust1", since = "1.0.0")]
Release,
/// When coupled with a load, all subsequent loads will see data
/// written before a store with `Release` ordering on the same value
/// written before a store with [`Release`][1] ordering on the same value
/// in other threads.
/// [1]: http://llvm.org/docs/Atomics.html#release
Copy link
Member

Choose a reason for hiding this comment

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

same here

#[stable(feature = "rust1", since = "1.0.0")]
Acquire,
/// When coupled with a load, uses `Acquire` ordering, and with a store
/// `Release` ordering.
/// When coupled with a load, uses [`Acquire`][1] ordering, and with a store
/// [`Release`][2] ordering.
/// [1]: http://llvm.org/docs/Atomics.html#acquire
/// [2]: http://llvm.org/docs/Atomics.html#release
Copy link
Member

Choose a reason for hiding this comment

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

and here:

    /// When coupled with a load, uses [`Acquire`] ordering, and with a store
    /// [`Release`] ordering.
    /// 
    /// [`Acquire`]: http://llvm.org/docs/Atomics.html#acquire
    /// [`Release`]: http://llvm.org/docs/Atomics.html#release

#[stable(feature = "rust1", since = "1.0.0")]
AcqRel,
/// Like `AcqRel` with the additional guarantee that all threads see all
Expand All @@ -176,7 +191,8 @@ pub enum Ordering {
__Nonexhaustive,
}

/// An `AtomicBool` initialized to `false`.
/// An [`AtomicBool`] initialized to `false`.
/// [`AtomicBool`]: struct.AtomicBool.html
Copy link
Member

Choose a reason for hiding this comment

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

an extra /// between these two lines, please!

#[cfg(target_has_atomic = "8")]
#[stable(feature = "rust1", since = "1.0.0")]
pub const ATOMIC_BOOL_INIT: AtomicBool = AtomicBool::new(false);
Expand Down Expand Up @@ -241,7 +257,7 @@ impl AtomicBool {

/// Loads a value from the bool.
///
/// `load` takes an [`Ordering`] argument which describes the memory ordering
/// `load()` takes an [`Ordering`] argument which describes the memory ordering
Copy link
Member

Choose a reason for hiding this comment

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

we don't include the () in function names; some of our docs do, but we decided against that style.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Good to know! I'll be sure to fix this up in the Once PR, as well.

/// of this operation.
///
/// # Panics
Expand All @@ -250,7 +266,7 @@ impl AtomicBool {
///
/// [`Ordering`]: enum.Ordering.html
/// [`Release`]: enum.Ordering.html#variant.Release
/// [`AcqRel`]: enum.Ordering.html#variant.Release
/// [`AcqRel`]: enum.Ordering.html#variant.AcqRel
Copy link
Member

Choose a reason for hiding this comment

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

nice catch! 😓

///
/// # Examples
///
Expand All @@ -269,7 +285,7 @@ impl AtomicBool {

/// Stores a value into the bool.
///
/// `store` takes an [`Ordering`] argument which describes the memory ordering
/// `store()` takes an [`Ordering`] argument which describes the memory ordering
Copy link
Member

Choose a reason for hiding this comment

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

same here

/// of this operation.
///
/// [`Ordering`]: enum.Ordering.html
Expand All @@ -287,7 +303,10 @@ impl AtomicBool {
///
/// # Panics
///
/// Panics if `order` is `Acquire` or `AcqRel`.
/// Panics if `order` is [`Acquire`] or [`AcqRel`].
///
/// [`Acquire`]: enum.Ordering.html#variant.Acquire
/// [`AcqRel`]: enum.Ordering.html#variant.AcqRel
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn store(&self, val: bool, order: Ordering) {
Expand All @@ -298,7 +317,7 @@ impl AtomicBool {

/// Stores a value into the bool, returning the old value.
///
/// `swap` takes an [`Ordering`] argument which describes the memory ordering
/// `swap()` takes an [`Ordering`] argument which describes the memory ordering
Copy link
Member

Choose a reason for hiding this comment

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

same here

/// of this operation.
///
/// [`Ordering`]: enum.Ordering.html
Expand All @@ -324,7 +343,7 @@ impl AtomicBool {
/// The return value is always the previous value. If it is equal to `current`, then the value
/// was updated.
///
/// `compare_and_swap` also takes an [`Ordering`] argument which describes the memory
/// `compare_and_swap()` also takes an [`Ordering`] argument which describes the memory
Copy link
Member

Choose a reason for hiding this comment

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

and here (I'll stop now, but all the others too)

/// ordering of this operation.
///
/// [`Ordering`]: enum.Ordering.html
Expand Down Expand Up @@ -356,7 +375,7 @@ impl AtomicBool {
/// The return value is a result indicating whether the new value was written and containing
/// the previous value. On success this value is guaranteed to be equal to `current`.
///
/// `compare_exchange` takes two [`Ordering`] arguments to describe the memory
/// `compare_exchange()` takes two [`Ordering`] arguments to describe the memory
/// ordering of this operation. The first describes the required ordering if the
/// operation succeeds while the second describes the required ordering when the
/// operation fails. The failure ordering can't be [`Release`] or [`AcqRel`] and must
Expand Down Expand Up @@ -404,17 +423,18 @@ impl AtomicBool {

/// Stores a value into the `bool` if the current value is the same as the `current` value.
///
/// Unlike `compare_exchange`, this function is allowed to spuriously fail even when the
/// Unlike [`compare_exchange()`], this function is allowed to spuriously fail even when the
/// comparison succeeds, which can result in more efficient code on some platforms. The
/// return value is a result indicating whether the new value was written and containing the
/// previous value.
///
/// `compare_exchange_weak` takes two [`Ordering`] arguments to describe the memory
/// `compare_exchange_weak()` takes two [`Ordering`] arguments to describe the memory
/// ordering of this operation. The first describes the required ordering if the operation
/// succeeds while the second describes the required ordering when the operation fails. The
/// failure ordering can't be [`Release`] or [`AcqRel`] and must be equivalent or
/// weaker than the success ordering.
///
/// [`compare_exchange()`]: #method.compare_exchange
Copy link
Member

Choose a reason for hiding this comment

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

when removing the ()s this one will have to go too

/// [`Ordering`]: enum.Ordering.html
/// [`Release`]: enum.Ordering.html#variant.Release
/// [`AcqRel`]: enum.Ordering.html#variant.Release
Expand Down Expand Up @@ -645,7 +665,7 @@ impl<T> AtomicPtr<T> {

/// Loads a value from the pointer.
///
/// `load` takes an [`Ordering`] argument which describes the memory ordering
/// `load()` takes an [`Ordering`] argument which describes the memory ordering
/// of this operation.
///
/// # Panics
Expand Down Expand Up @@ -674,7 +694,7 @@ impl<T> AtomicPtr<T> {

/// Stores a value into the pointer.
///
/// `store` takes an [`Ordering`] argument which describes the memory ordering
/// `store()` takes an [`Ordering`] argument which describes the memory ordering
/// of this operation.
///
/// [`Ordering`]: enum.Ordering.html
Expand All @@ -694,7 +714,11 @@ impl<T> AtomicPtr<T> {
///
/// # Panics
///
/// Panics if `order` is `Acquire` or `AcqRel`.
/// Panics if `order` is [`Acquire`] or [`AcqRel`].
///
/// [`Acquire`]: enum.Ordering.html#variant.Acquire
/// [`AcqRel`]: enum.Ordering.html#variant.AcqRel
///
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn store(&self, ptr: *mut T, order: Ordering) {
Expand All @@ -705,7 +729,7 @@ impl<T> AtomicPtr<T> {

/// Stores a value into the pointer, returning the old value.
///
/// `swap` takes an [`Ordering`] argument which describes the memory ordering
/// `swap()` takes an [`Ordering`] argument which describes the memory ordering
/// of this operation.
///
/// [`Ordering`]: enum.Ordering.html
Expand Down Expand Up @@ -733,7 +757,7 @@ impl<T> AtomicPtr<T> {
/// The return value is always the previous value. If it is equal to `current`, then the value
/// was updated.
///
/// `compare_and_swap` also takes an [`Ordering`] argument which describes the memory
/// `compare_and_swap()` also takes an [`Ordering`] argument which describes the memory
/// ordering of this operation.
///
/// [`Ordering`]: enum.Ordering.html
Expand Down Expand Up @@ -765,7 +789,7 @@ impl<T> AtomicPtr<T> {
/// The return value is a result indicating whether the new value was written and containing
/// the previous value. On success this value is guaranteed to be equal to `current`.
///
/// `compare_exchange` takes two [`Ordering`] arguments to describe the memory
/// `compare_exchange()` takes two [`Ordering`] arguments to describe the memory
/// ordering of this operation. The first describes the required ordering if
/// the operation succeeds while the second describes the required ordering when
/// the operation fails. The failure ordering can't be [`Release`] or [`AcqRel`]
Expand Down Expand Up @@ -812,18 +836,18 @@ impl<T> AtomicPtr<T> {

/// Stores a value into the pointer if the current value is the same as the `current` value.
///
/// Unlike [`compare_exchange`], this function is allowed to spuriously fail even when the
/// Unlike [`compare_exchange()`], this function is allowed to spuriously fail even when the
/// comparison succeeds, which can result in more efficient code on some platforms. The
/// return value is a result indicating whether the new value was written and containing the
/// previous value.
///
/// `compare_exchange_weak` takes two [`Ordering`] arguments to describe the memory
/// `compare_exchange_weak()` takes two [`Ordering`] arguments to describe the memory
/// ordering of this operation. The first describes the required ordering if the operation
/// succeeds while the second describes the required ordering when the operation fails. The
/// failure ordering can't be [`Release`] or [`AcqRel`] and must be equivalent or
/// weaker than the success ordering.
///
/// [`compare_exchange`]: #method.compare_exchange
/// [`compare_exchange()`]: #method.compare_exchange
/// [`Ordering`]: enum.Ordering.html
/// [`Release`]: enum.Ordering.html#variant.Release
/// [`AcqRel`]: enum.Ordering.html#variant.AcqRel
Expand Down Expand Up @@ -962,7 +986,7 @@ macro_rules! atomic_int {

/// Loads a value from the atomic integer.
///
/// `load` takes an [`Ordering`] argument which describes the memory ordering of this
/// `load()` takes an [`Ordering`] argument which describes the memory ordering of this
/// operation.
///
/// # Panics
Expand Down Expand Up @@ -990,7 +1014,7 @@ macro_rules! atomic_int {

/// Stores a value into the atomic integer.
///
/// `store` takes an [`Ordering`] argument which describes the memory ordering of this
/// `store()` takes an [`Ordering`] argument which describes the memory ordering of this
/// operation.
///
/// [`Ordering`]: enum.Ordering.html
Expand All @@ -1008,7 +1032,11 @@ macro_rules! atomic_int {
///
/// # Panics
///
/// Panics if `order` is `Acquire` or `AcqRel`.
/// Panics if `order` is [`Acquire`] or [`AcqRel`].
///
/// [`Acquire`]: enum.Ordering.html#variant.Acquire
/// [`AcqRel`]: enum.Ordering.html#variant.AcqRel
///
Copy link
Member

Choose a reason for hiding this comment

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

could you remove this extra line please?

#[inline]
#[$stable]
pub fn store(&self, val: $int_type, order: Ordering) {
Expand All @@ -1017,7 +1045,7 @@ macro_rules! atomic_int {

/// Stores a value into the atomic integer, returning the old value.
///
/// `swap` takes an [`Ordering`] argument which describes the memory ordering of this
/// `swap()` takes an [`Ordering`] argument which describes the memory ordering of this
/// operation.
///
/// [`Ordering`]: enum.Ordering.html
Expand All @@ -1043,7 +1071,7 @@ macro_rules! atomic_int {
/// The return value is always the previous value. If it is equal to `current`, then the
/// value was updated.
///
/// `compare_and_swap` also takes an [`Ordering`] argument which describes the memory
/// `compare_and_swap()` also takes an [`Ordering`] argument which describes the memory
/// ordering of this operation.
///
/// [`Ordering`]: enum.Ordering.html
Expand Down Expand Up @@ -1083,7 +1111,7 @@ macro_rules! atomic_int {
/// containing the previous value. On success this value is guaranteed to be equal to
/// `current`.
///
/// `compare_exchange` takes two [`Ordering`] arguments to describe the memory
/// `compare_exchange()` takes two [`Ordering`] arguments to describe the memory
/// ordering of this operation. The first describes the required ordering if
/// the operation succeeds while the second describes the required ordering when
/// the operation fails. The failure ordering can't be [`Release`] or [`AcqRel`] and
Expand Down Expand Up @@ -1125,18 +1153,18 @@ macro_rules! atomic_int {
/// Stores a value into the atomic integer if the current value is the same as the
/// `current` value.
///
/// Unlike [`compare_exchange`], this function is allowed to spuriously fail even
/// Unlike [`compare_exchange()`], this function is allowed to spuriously fail even
/// when the comparison succeeds, which can result in more efficient code on some
/// platforms. The return value is a result indicating whether the new value was
/// written and containing the previous value.
///
/// `compare_exchange_weak` takes two [`Ordering`] arguments to describe the memory
/// `compare_exchange_weak()` takes two [`Ordering`] arguments to describe the memory
/// ordering of this operation. The first describes the required ordering if the
/// operation succeeds while the second describes the required ordering when the
/// operation fails. The failure ordering can't be [`Release`] or [`AcqRel`] and
/// must be equivalent or weaker than the success ordering.
///
/// [`compare_exchange`]: #method.compare_exchange
/// [`compare_exchange()`]: #method.compare_exchange
/// [`Ordering`]: enum.Ordering.html
/// [`Release`]: enum.Ordering.html#variant.Release
/// [`AcqRel`]: enum.Ordering.html#variant.AcqRel
Expand Down