Crate atomig

Expand description

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 three main traits to safely abstract over different atomic types. There are also three traits for plumbing in the impls module but these are considered implementation detail for the most part and can usually be ignored.

The most important trait 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.

Notes

Not all types and modules from std::sync::atomic are available on all platforms. std itself uses cfg(target_has_atomic) attributes to do that. Unfortunately, these cfg attributes are still unstable, thus atomig does not use them right now. This has the unfortunate effect that this whole library will fail to compile on any targets where any of the atomic methods/types are unavailable. Once this is stabilized, atomic will use those cfg attributes as appropriate to support platforms with partial atomic support.

Cargo features

This crate has some 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.
serde: enables the serde Serialize and Deserialize traits on Atomic<T> if T is serializable or deserializable.