pub trait Atom {
type Repr: PrimitiveAtom;
// Required methods
fn pack(self) -> Self::Repr;
fn unpack(src: Self::Repr) -> Self;
}Expand description
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:
structtypes with only one field. That field’s type has to implementAtom. Works with tuple structs or normal structs with one named field.enumtypes 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 asReprtype.
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);
Required Associated Types§
sourcetype Repr: PrimitiveAtom
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§
sourcefn unpack(src: Self::Repr) -> Self
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 undefined behavior (e.g. memory
unsafety)!