[−][src]Trait atomig::Atom
Types that can be represented by a primitive type supporting atomic operations.
This is trait is already implemented for all primitive types that support
atomic operations. It is also implemented for f32
, f64
and char
as
all of those can be represented by a primitive atomic type. In addition to
this, you can implement this trait for your own types as long as they can
be represented as one such primitive type.
The pack
and unpack
methods define the conversion to and from the
atomic representation. The methods should be fairly fast, because they are
called frequently by Atomic
: at least once for every method of
Atomic
.
Example
Imagine you have a Port
type to represent a network port and use strong
typing. It is simply a newtype around a u16
, so it is easily possible to
use atomic operations on it.
use atomig::{Atom, Atomic, Ordering}; struct Port(u16); impl Atom for Port { type Repr = u16; fn pack(self) -> Self::Repr { self.0 } fn unpack(src: Self::Repr) -> Self { Port(src) } } // Implementing `Atom` means that we can use `Atomic` with our type let a = Atomic::new(Port(80)); a.store(Port(8080), Ordering::SeqCst);
Deriving this trait
Instead of implementing the trait manually (like shown above), you can derive it automatically in many cases. In order to use that feature, you have to enabled the Cargo feature 'derive'.
use atomig::{Atom, Atomic, Ordering}; #[derive(Atom)] struct Port(u16); let a = Atomic::new(Port(80)); a.store(Port(8080), Ordering::SeqCst);
The trait can be automatically derived for two kinds of types:
struct
types with only one field. That field's type has to implementPrimitiveAtom
and is used asRepr
type. Works with tuple structs or normal structs with named fields.enum
types that have a#[repr(_)]
attribute specified and are C-like (i.e. no variant has any fields). The primitive type specified in the#[repr(_)]
attribute is used asRepr
type.
Example with enum:
use atomig::{Atom, Atomic, Ordering}; #[derive(Atom)] #[repr(u8)] enum Animal { Dog, Cat, Fox } let a = Atomic::new(Animal::Cat); a.store(Animal::Fox, Ordering::SeqCst);
Associated Types
type Repr: PrimitiveAtom
The atomic representation of this type.
In this trait's implementations for the primitive types themselves,
Repr
is set to Self
.
Required methods
fn pack(self) -> Self::Repr
Converts the type to its atomic representation.
fn unpack(src: Self::Repr) -> Self
Creates an instance of this type from the atomic representation.
This method is usually only called with values that were returned by
pack
. So in theory, you can assume that the argument is a valid
representation. However, there are two exceptions.
If your type also implements AtomLogic
or AtomInteger
, results of
those operations might get passed to unpack
. Furthermore, this method
can be called by anyone. So at the very least, you have to make sure
that invalid input values do not lead to memory unsafety!