Struct AtomicOptionSystemTime

Source

pub struct AtomicOptionSystemTime(/* private fields */);

Available on crate feature std only.

Expand description

An atomic version of Option<std::time::SystemTime>.

Some values must be at or after SystemTime::UNIX_EPOCH.

Implementations§

Source §

impl AtomicOptionSystemTime

Source

pub const fn none() -> Self

Equivalent to atomic version Option::<SystemTime>::None.

§Examples

use atomic_time::AtomicOptionSystemTime;

let none = AtomicOptionSystemTime::none();
assert_eq!(none.load(std::sync::atomic::Ordering::SeqCst), None);

Source

pub fn now() -> Self

Returns the system time corresponding to “now”.

§Examples

use atomic_time::AtomicOptionSystemTime;

let sys_time = AtomicOptionSystemTime::now();

Source

pub fn new(system_time: Option<SystemTime>) -> Self

Creates a new AtomicOptionSystemTime with the given SystemTime value.

§Panics

If the given SystemTime value is earlier than the UNIX_EPOCH.

Source

pub fn load(&self, order: Ordering) -> Option<SystemTime>

Loads a value from the atomic system time.

Source

pub fn store(&self, system_time: Option<SystemTime>, order: Ordering)

Stores a value into the atomic system time.

§Panics

If the given SystemTime value is earlier than the UNIX_EPOCH.

Source

pub fn swap( &self, system_time: Option<SystemTime>, order: Ordering, ) -> Option<SystemTime>

Stores a value into the atomic system time, returning the previous value.

§Panics

If the given SystemTime value is earlier than the UNIX_EPOCH.

Source

pub fn compare_exchange( &self, current: Option<SystemTime>, new: Option<SystemTime>, success: Ordering, failure: Ordering, ) -> Result<Option<SystemTime>, Option<SystemTime>>

Stores a value into the atomic system time if the current value is the same as the current value.

§Panics

If the given SystemTime value is earlier than the UNIX_EPOCH.

Source

pub fn compare_exchange_weak( &self, current: Option<SystemTime>, new: Option<SystemTime>, success: Ordering, failure: Ordering, ) -> Result<Option<SystemTime>, Option<SystemTime>>

Stores a value into the atomic system time if the current value is the same as the current value.

§Panics

If the given SystemTime value is earlier than the UNIX_EPOCH.

Source

pub fn try_update<F>( &self, set_order: Ordering, fetch_order: Ordering, f: F, ) -> Result<Option<SystemTime>, Option<SystemTime>>
where F: FnMut(Option<SystemTime>) -> Option<Option<SystemTime>>,

Fetches the value and applies a function that can choose whether to store a new value.

Returns Ok(previous_value) when f returns Some(_), and Err(previous_value) when it returns None. The outer Option is the update decision; returning Some(None) stores None. The closure can run more than once when another thread changes the value concurrently, but it is applied only once to the value that is stored.

set_order describes the ordering of the successful update and fetch_order describes failed compare-and-exchange loads. They have the same requirements as the success and failure orderings of compare_exchange.

§Panics

Panics if the orderings are invalid for compare_exchange, or if a Some value passed to or returned from the function is earlier than UNIX_EPOCH.

§Examples

use atomic_time::AtomicOptionSystemTime;
use std::{sync::atomic::Ordering, time::{Duration, SystemTime}};

let start = SystemTime::UNIX_EPOCH + Duration::from_secs(7);
let x = AtomicOptionSystemTime::new(Some(start));
assert_eq!(x.try_update(Ordering::SeqCst, Ordering::SeqCst, |_| None), Err(Some(start)));
assert_eq!(x.try_update(Ordering::SeqCst, Ordering::SeqCst, |old| Some(old.map(|time| time + Duration::from_secs(1)))), Ok(Some(start)));

Source

pub fn fetch_update<F>( &self, set_order: Ordering, fetch_order: Ordering, f: F, ) -> Result<Option<SystemTime>, Option<SystemTime>>
where F: FnMut(Option<SystemTime>) -> Option<Option<SystemTime>>,

Fetches the value, and applies a function to it that returns an optional new value. Returns a Result of Ok(previous_value) if the function returned Some(_), else Err(previous_value).

Note: This may call the function multiple times if the value has been changed from other threads in the meantime, as long as the function returns Some(_), but the function will have been applied only once to the stored value.

fetch_update takes two Ordering arguments to describe the memory ordering of this operation. The first describes the required ordering for when the operation finally succeeds while the second describes the required ordering for loads. These correspond to the success and failure orderings of compare_exchange respectively.

Using Acquire as success ordering makes the store part of this operation Relaxed, and using Release makes the final successful load Relaxed. The (failed) load ordering can only be SeqCst, Acquire or Relaxed and must be equivalent to or weaker than the success ordering.

§Panics

If the given SystemTime value is earlier than the UNIX_EPOCH.

§Examples

use atomic_time::AtomicOptionSystemTime;
use std::{time::{Duration, SystemTime}, sync::atomic::Ordering};

let now = SystemTime::now();
let x = AtomicOptionSystemTime::none();
assert_eq!(x.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |_| None), Err(None));
x.store(Some(now), Ordering::SeqCst);
assert_eq!(x.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |x| Some(x.map(|val| val + Duration::from_secs(1)))), Ok(Some(now)));
assert_eq!(x.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |x| Some(x.map(|val| val + Duration::from_secs(1)))), Ok(Some(now + Duration::from_secs(1))));
assert_eq!(x.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |x| Some(x.map(|val| val + Duration::from_secs(1)))), Ok(Some(now + Duration::from_secs(2))));
assert_eq!(x.load(Ordering::SeqCst), Some(now + Duration::from_secs(3)));

Source

pub fn update<F>( &self, set_order: Ordering, fetch_order: Ordering, f: F, ) -> Option<SystemTime>
where F: FnMut(Option<SystemTime>) -> Option<SystemTime>,

Fetches the value, applies a function to produce a new value, stores it, and returns the previous value.

The closure can run more than once when another thread changes the value concurrently, but it is applied only once to the value that is stored. set_order and fetch_order have the same requirements as the success and failure orderings of compare_exchange.

§Panics

Panics if the orderings are invalid for compare_exchange, or if a Some value passed to or returned from the function is earlier than UNIX_EPOCH.

§Examples

use atomic_time::AtomicOptionSystemTime;
use std::{sync::atomic::Ordering, time::{Duration, SystemTime}};

let start = SystemTime::UNIX_EPOCH + Duration::from_secs(7);
let x = AtomicOptionSystemTime::new(Some(start));
assert_eq!(x.update(Ordering::SeqCst, Ordering::SeqCst, |old| old.map(|time| time + Duration::from_secs(1))), Some(start));
assert_eq!(x.load(Ordering::SeqCst), Some(start + Duration::from_secs(1)));

Source

pub fn fetch_min( &self, val: Option<SystemTime>, order: Ordering, ) -> Option<SystemTime>

Atomically stores the smaller of the current value and val, returning the previous value.

None is ordered before every Some value, and Some values are ordered by their duration from UNIX_EPOCH. order describes the memory ordering of the read-modify-write operation. Using Acquire makes its store part relaxed, and using Release makes its load part relaxed.

§Panics

Panics if a Some value in val is earlier than UNIX_EPOCH.

§Examples

use atomic_time::AtomicOptionSystemTime;
use std::{sync::atomic::Ordering, time::{Duration, SystemTime}};

let low = SystemTime::UNIX_EPOCH + Duration::from_secs(5);
let middle = low + Duration::from_secs(1);
let high = middle + Duration::from_secs(1);
let x = AtomicOptionSystemTime::new(Some(middle));
assert_eq!(x.fetch_min(Some(high), Ordering::SeqCst), Some(middle));
assert_eq!(x.fetch_min(Some(low), Ordering::SeqCst), Some(middle));
assert_eq!(x.load(Ordering::SeqCst), Some(low));

Source

pub fn fetch_max( &self, val: Option<SystemTime>, order: Ordering, ) -> Option<SystemTime>

Atomically stores the larger of the current value and val, returning the previous value.

None is ordered before every Some value, and Some values are ordered by their duration from UNIX_EPOCH. order describes the memory ordering of the read-modify-write operation. Using Acquire makes its store part relaxed, and using Release makes its load part relaxed.

§Panics

Panics if a Some value in val is earlier than UNIX_EPOCH.

§Examples

use atomic_time::AtomicOptionSystemTime;
use std::{sync::atomic::Ordering, time::{Duration, SystemTime}};

let high = SystemTime::UNIX_EPOCH + Duration::from_secs(7);
let x = AtomicOptionSystemTime::none();
assert_eq!(x.fetch_max(None, Ordering::SeqCst), None);
assert_eq!(x.fetch_max(Some(high), Ordering::SeqCst), None);
assert_eq!(x.load(Ordering::SeqCst), Some(high));

Source

pub fn is_lock_free() -> bool

Returns true if operations on values of this type are lock-free. If the compiler or the platform doesn’t support the necessary atomic instructions, global locks for every potentially concurrent atomic operation will be used.

§Examples

use atomic_time::AtomicOptionSystemTime;

let is_lock_free = AtomicOptionSystemTime::is_lock_free();

Source

pub const fn is_always_lock_free() -> bool

Returns whether operations on values of this type are always lock-free.

A false result does not preclude lock-free operations selected through runtime CPU feature detection; use is_lock_free to query the current target at runtime.

§Examples

use atomic_time::AtomicOptionSystemTime;

const ALWAYS_LOCK_FREE: bool = AtomicOptionSystemTime::is_always_lock_free();
let _ = ALWAYS_LOCK_FREE;

Source

pub fn into_inner(self) -> Option<SystemTime>

Consumes the atomic and returns the contained value.

This is safe because passing self by value guarantees that no other threads are concurrently accessing the atomic data.

Trait Implementations§

Source §

impl Arbitrary for AtomicOptionSystemTime

Available on crate feature quickcheck only.

Source §

fn arbitrary(g: &mut Gen) -> Self

Return an arbitrary value. Read more

Source §

fn shrink(&self) -> Box<dyn Iterator<Item = Self>>

Return an iterator of values that are smaller than itself. Read more

Source §

impl Arbitrary for AtomicOptionSystemTime

Available on crate feature proptest only.

Source §

type Parameters = ()

The type of parameters that arbitrary_with accepts for configuration of the generated Strategy. Parameters must implement Default.

Source §

type Strategy = BoxedStrategy<AtomicOptionSystemTime>

The type of Strategy used to generate values of type Self.

Source §

fn arbitrary_with(_: Self::Parameters) -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self). The strategy is passed the arguments given in args. Read more

Source §