Enum ptr_cell::Semantics

#[non_exhaustive]
pub enum Semantics {
    Relaxed,
    Coupled,
    Ordered,
}

Memory ordering semantics for atomic operations. Determines how value updates are synchronized between threads

Explanations

Lock-free programming is not easy to grasp. What’s more, resources explaining Rust’s atomic orderings in depth are pretty sparse. However, this is not really an issue. Atomics in Rust are almost identical to their C++ counterparts, of which there exist abundant explanations

Here are just some of them:

• Although not meant as an introduction to the release-acquire semantics, this fantastic article by Jeff Preshing definitely provides the much-needed clarification

• Another great article by Preshing, but this time dedicated entirely to the concept of the release-acquire semantics

• Memory order from the C++ standards. Way more technical, but has all contracts organized in a single place. Please note that Rust lacks a direct analog to C++’s memory_order_consume

If you’re still not sure what semantics to use, choose Coupled

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Relaxed

Relaxed semantics

No synchronization constraints and the best performance

Coupled

Release - Acquire coupling semantics

Mild synchronization constraints and fair performance

A read will always see the preceding write (if one exists). Any operations that take place before the write will also be seen, regardless of their semantics. See the documentation for Release and Acquire

A common assumption is that this is how memory operations naturally behave. While it’s true on some platforms (namely, x86 and x86-64), this behavior is not universal. Thus, this is likely the semantics you want to use

Ordered

SeqCst semantics

Maximum synchronization constraints and the worst performance

All memory operations will appear to be executed in a single, total order. See the documentation for SeqCst

Implementations

impl Semantics

pub const fn read_write(&self) -> Ordering

Returns the memory ordering for read-write operations with these semantics

Returns

• Relaxed for Relaxed semantics
• AcqRel for Coupled semantics
• SeqCst for Ordered semantics

Usage

use std::sync::atomic::Ordering;

// Copy a variant of Semantics
let semantics = ptr_cell::Semantics::Coupled;

// Get the corresponding Ordering
 assert_eq!(semantics.read_write(), Ordering::AcqRel)

impl Semantics

pub const fn write(&self) -> Ordering

Returns the memory ordering for write operations with these semantics

Returns

• Relaxed for Relaxed semantics
• Release for Coupled semantics
• SeqCst for Ordered semantics

Usage

use std::sync::atomic::Ordering;

// Copy a variant of Semantics
let semantics = ptr_cell::Semantics::Coupled;

// Get the corresponding Ordering
 assert_eq!(semantics.write(), Ordering::Release)

impl Semantics

pub const fn read(&self) -> Ordering

Returns the memory ordering for read operations with these semantics

Returns

• Relaxed for Relaxed semantics
• Acquire for Coupled semantics
• SeqCst for Ordered semantics

Usage

use std::sync::atomic::Ordering;

// Copy a variant of Semantics
let semantics = ptr_cell::Semantics::Coupled;

// Get the corresponding Ordering
 assert_eq!(semantics.read(), Ordering::Acquire)

Trait Implementations

impl Clone for Semantics

fn clone(&self) -> Semantics

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Semantics

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Semantics

fn default() -> Self

Returns the “default value” for a type.

impl Hash for Semantics

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Semantics

fn cmp(&self, other: &Semantics) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for Semantics

fn eq(&self, other: &Semantics) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Semantics

fn partial_cmp(&self, other: &Semantics) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for Semantics

impl Eq for Semantics

impl StructuralPartialEq for Semantics