atomic-time 1.0.0

Thread-safe atomic versions of Duration, SystemTime, Instant and their Option variants; lock-free on platforms with native AtomicU128 support, otherwise portable-atomic may fall back to a global lock

English | 简体中文

Introduction

atomic-time provides thread-safe atomic versions of Rust's standard time types. They are lock-free on platforms with native AtomicU128 support; otherwise, portable-atomic may fall back to a global lock. All types use AtomicU128 (via portable-atomic) under the hood and expose the same API patterns as the standard std::sync::atomic types (load, store, swap, compare_exchange, compare_exchange_weak, fetch_update).

Types

Installation

[dependencies]
atomic-time = "1"

Feature Flags

For no_std environments (only AtomicDuration and AtomicOptionDuration are available):

[dependencies]
atomic-time = { version = "1", default-features = false }

The optional serde feature can also be enabled in a no_std build with features = ["serde"].

All three property-testing integrations require std. This includes arbitrary, because the current upstream arbitrary v1 crate itself uses std. Opt into one of the integrations with:

[dependencies]
atomic-time = { version = "1", features = ["arbitrary"] }
# or: atomic-time = { version = "1", features = ["quickcheck"] }
# or: atomic-time = { version = "1", features = ["proptest"] }

The quickcheck feature implements Clone for AtomicDuration, AtomicOptionDuration, AtomicSystemTime, and AtomicOptionSystemTime. Cloning performs a SeqCst load, so under concurrent writes the cloned value is the value observed at that load's atomic linearization point.

AtomicInstant and AtomicOptionInstant intentionally do not implement arbitrary, quickcheck, or proptest traits (and do not gain Clone from these features). Their encodings use a process-local baseline, so a seed or corpus cannot produce portable, deterministic values across process runs.

On some bare-metal targets without native compare-and-swap support, the final application must use Cargo feature unification to enable portable-atomic's critical-section feature and provide a target-appropriate critical-section implementation, or adopt another safe configuration from the official portable-atomic guide.

Atomic Operations

All six atomic types provide is_always_lock_free, try_update, update, fetch_min, and fetch_max; the existing fetch_update remains available for compatibility. fetch_min and fetch_max return the value observed before the operation. For Option types, ordering is None < Some; Instant comparisons are meaningful only for values using the same process-local baseline.

AtomicDuration and AtomicOptionDuration also provide fetch_saturating_add and fetch_saturating_sub, returning the old value. For AtomicDuration, these saturate at Duration::MAX and Duration::ZERO. For AtomicOptionDuration, Some values saturate while None remains None (it is not treated as zero). These names intentionally use fetch_saturating_add/sub, rather than fetch_add/sub, to avoid implying integer wrapping; saturating add/sub helpers apply only to the Duration types.

Time Semantics

AtomicSystemTime and AtomicOptionSystemTime accept only values at or after SystemTime::UNIX_EPOCH; earlier values panic.

AtomicInstant and AtomicOptionInstant encode Instant relative to a process-local baseline initialized from SystemTime::now() and Instant::now(). Within the same process, values within the platform's representable Instant range round-trip precisely. Across processes or restarts, the encoding is not portable and decoding only approximates wall-clock time. System clock adjustments can change that cross-process or restart interpretation. Behavior across sleep follows the platform's Instant semantics. Encoded instants must not be persisted as deadlines. If an extreme Duration cannot be represented by the platform's Instant, decoding falls back to the process baseline instead of panicking.

Example

use std::sync::Arc;
use std::sync::atomic::Ordering;
use std::time::Duration;
use atomic_time::AtomicDuration;

let timeout = Arc::new(AtomicDuration::new(Duration::from_secs(30)));

// Update from another thread
let timeout_clone = timeout.clone();
std::thread::spawn(move || {
    timeout_clone.store(Duration::from_secs(60), Ordering::Release);
});

use std::sync::atomic::Ordering;
use std::time::Instant;
use atomic_time::AtomicOptionInstant;

// Track the last time an event occurred
let last_event = AtomicOptionInstant::none();
assert_eq!(last_event.load(Ordering::Relaxed), None);

last_event.store(Some(Instant::now()), Ordering::Release);
assert!(last_event.load(Ordering::Acquire).is_some());

Benchmarks

Run with cargo bench in the benchmark/ directory. Apple M4 Pro.

Duration (cargo bench --bench duration)

Instant (cargo bench --bench instant)

SystemTime (cargo bench --bench system_time)

Contended read = 4 background threads also reading; Load under write contention = 4 background threads writing, load measured on main thread; Contended store = 4 background threads writing, store measured on main thread. All numbers from Apple M4 Pro.

MSRV

The minimum supported Rust version is 1.85.

License

atomic-time is under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE, LICENSE-MIT for details.

Copyright (c) 2026 Al Liu.