Skip to content

Docs for atomic orderings: link to the 'nomicon article for further reading #39200

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 5 commits into from
Jan 24, 2017
Merged

Docs for atomic orderings: link to the 'nomicon article for further reading #39200

Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b4192aa
Module level doc
DirkyJerky Jan 20, 2017
c4c9ff2
'.'
DirkyJerky Jan 20, 2017
02ead27
Into item level docs (enum Ordering)
DirkyJerky Jan 20, 2017
dfa9736
Clarify the `default` option to use
DirkyJerky Jan 20, 2017
c0a5b99
Revert previous commit
DirkyJerky Jan 20, 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
10 changes: 9 additions & 1 deletion src/libcore/sync/atomic.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,10 @@
//!
//! 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].
//! same as [LLVM atomic orderings][1]. For more information see the [nomicon][2].
//!
//! [1]: http://llvm.org/docs/LangRef.html#memory-model-for-concurrent-operations
//! [2]: https://doc.rust-lang.org/nomicon/atomics.html
//!
//! Atomic variables are safe to share between threads (they implement `Sync`)
//! but they do not themselves provide the mechanism for sharing and follow the
Expand Down Expand Up @@ -139,8 +140,15 @@ unsafe impl<T> Sync for AtomicPtr<T> {}
/// to be moved either before or after the atomic operation; on the other end
/// "relaxed" atomics allow all reorderings.
///
/// If you are confused or don't have enough time to research which ordering to use, use `SeqCst`.
/// Of all the options it has the most unsurpising effect (see the nomicon for details. [1])
/// The downside is you miss out on several optimizations the other orderings offer.
///
Copy link
Contributor Author

Choose a reason for hiding this comment

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

This is just something completely optional I feel would help people (beginners) who have no clue how orderings work and just want to get sample code working.

Copy link
Member

Choose a reason for hiding this comment

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

I’d argue that if one is confused/doesn’t have time to research, they should not be writing code involving atomics at all and just use a Mutex.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Very good point

/// Rust's memory orderings are [the same as
/// LLVM's](http://llvm.org/docs/LangRef.html#memory-model-for-concurrent-operations).
///
/// For more information see the [nomicon][1].
/// [1]: https://doc.rust-lang.org/nomicon/atomics.html
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Copy, Clone, Debug)]
pub enum Ordering {
Expand Down