[−][src]Crate atomig

Generic and convenient std atomics.

This crate offers the generic Atomic<T> type which can perform atomic operations on T. There is an important difference to C++'s atomic and the Atomic type from the atomic crate: the Atomic<T> in this crate only works with types that actually support atomic operations on the target platform. A lock-based fallback for other types is not used!

This crate uses the atomic types from std::sync::atomic under the hood and actually does not contain any "interesting" runtime code itself. In other words: this is just a nicer API. Thanks to this, this crate does not use any unsafe code!

Quick example

You can simply use Atomic<T> with all types that implement Atom which are all types that support atomic operations on your platform, but also types that can be represented as the former kind of types (like f32 and char).

use atomig::{Atomic, Ordering};

let a = Atomic::new(true);  // Atomic<bool>
a.store(false, Ordering::SeqCst);

The interface of Atomic very closely matches the interface of the atomic types in std::sync::atomic and you should be able to use this crate as a drop-in replacement. For more examples, see the examples/ folder in the repository.

As you can see in the example, Ordering (from std::sync::atomic) is reexported in this crate for your import convenience.

Traits

This crate contains a number of traits to safely abstract over different atomic types. There are four rather "low level" traits (in the impls module) and three more "high level" ones.

The most important one is probably Atom: to use a type T in Atomic<T>, is has to implement Atom. You can implement that trait for your own types as long as they can be represented by a type that implements impls::PrimitiveAtom. In many cases, you can also simply #[derive(Atom)] for your own types. See Atom's documentation for more information.

Cargo features

This crate has two Cargo features which are disabled by default:

  • derive: enables the custom derives for Atom, AtomLogic and AtomInteger. It is disabled by default because it requires compiling a few dependencies for procedural macros.
  • nightly: only usable with a nightly compiler. Does two things:
    • Adds unstable methods to this API, specifically fetch_update, fetch_max and fetch_min.
    • Uses the cfg(target_has_atomic = "...") feature to only compile the parts of the library that are actually supported by the target platform. Without this, this crate probably won't compile on platforms that do not support all atomic features offered by std::sync::atomic.

Re-exports

pub use std::sync::atomic::Ordering;
pub use atomig_macro::Atom;
pub use atomig_macro::AtomInteger;
pub use atomig_macro::AtomLogic;

Modules

impls

Traits for atomic implementations. You probably do not need to worry about this module.

Structs

Atomic

The main type of this library: a generic atomic type.

Traits

Atom

Types that can be represented by a primitive type supporting atomic operations.

AtomInteger

Atoms for which integer operations on their atomic representation make sense.

AtomLogic

Atoms for which logical operations on their atomic representation make sense.