How does `once_cell::sync::OnceCell` differ from `std::sync::OnceLock` introduced in Rust 1.70?

once_cell::sync::OnceCell and std::sync::OnceLock provide identical functionality—thread-safe one-time initialization of a value—but differ in availability, API naming, and feature scope. OnceLock is the standard library's adoption of the OnceCell pattern, stabilized in Rust 1.70 after years of the once_cell crate serving this need. The once_cell crate offers additional APIs beyond what's in std, including Lazy<T> for deferred initialization with a closure, race::OnceCell for non-thread-safe scenarios, and the sync::Lazy type. For projects on Rust 1.70+, OnceLock is the idiomatic choice for standard use cases, while once_cell remains valuable for additional features or supporting older Rust versions.

Basic OnceCell Usage

// Using once_cell crate
use once_cell::sync::OnceCell;
 
static INSTANCE: OnceCell<String> = OnceCell::new();
 
fn main() {
    // Get or initialize
    let value = INSTANCE.get_or_init(|| {
        println!("Initializing...");
        String::from("Hello, World!")
    });
    
    println!("{}", value);
    
    // Subsequent calls return existing value
    let value2 = INSTANCE.get_or_init(|| {
        panic!("This won't be called");
    });
    
    println!("{}", value2);
}

OnceCell provides thread-safe lazy initialization.

Basic OnceLock Usage

// Using std (Rust 1.70+)
use std::sync::OnceLock;
 
static INSTANCE: OnceLock<String> = OnceLock::new();
 
fn main() {
    // Get or initialize
    let value = INSTANCE.get_or_init(|| {
        println!("Initializing...");
        String::from("Hello, World!")
    });
    
    println!("{}", value);
    
    // Subsequent calls return existing value
    let value2 = INSTANCE.get_or_init(|| {
        panic!("This won't be called");
    });
    
    println!("{}", value2);
}

OnceLock provides identical functionality with different naming.

API Comparison

use once_cell::sync::OnceCell;
use std::sync::OnceLock;
 
fn main() {
    // OnceCell API
    let cell: OnceCell<i32> = OnceCell::new();
    cell.get();                    // Option<&T>
    cell.get_or_init(|| 42);       // &T
    cell.get_mut();                // Option<&mut T>
    cell.get_unchecked();          // &T (unsafe)
    cell.set(42);                  // Result<(), T>
    cell.take();                   // Option<T>
    cell.into_inner();             // Option<T>
    
    // OnceLock API (same functionality, different names)
    let lock: OnceLock<i32> = OnceLock::new();
    lock.get();                    // Option<&T>
    lock.get_or_init(|| 42);       // &T
    lock.get_mut();                // Option<&mut T>
    lock.get_unchecked();          // &T (unsafe)
    lock.set(42);                  // Result<(), T>
    lock.take();                   // Option<T>
    lock.into_inner();             // Option<T>
    
    // APIs are essentially identical
}

Both provide the same core operations with equivalent semantics.

The Lazy Type Difference

// once_cell provides Lazy<T> for deferred initialization
use once_cell::sync::Lazy;
 
static CONFIG: Lazy<Vec<String>> = Lazy::new(|| {
    let mut config = Vec::new();
    config.push("setting1".to_string());
    config.push("setting2".to_string());
    config
});
 
fn main() {
    // CONFIG initializes on first access
    println!("Before access");
    println!("Config: {:?}", *CONFIG);  // Initializes here
    println!("After access");
    
    // std doesn't have Lazy<T>
    // Workaround in std:
    use std::sync::OnceLock;
    static CONFIG_STD: OnceLock<Vec<String>> = OnceLock::new();
    
    // Manual get_or_init each time
    let config = CONFIG_STD.get_or_init(|| {
        vec!["setting1".to_string(), "setting2".to_string()]
    });
}

Lazy<T> provides automatic initialization; OnceLock requires explicit get_or_init.

Lazy Initialization Pattern Comparison

use once_cell::sync::Lazy;
use std::sync::OnceLock;
 
// once_cell::Lazy - declarative, automatic
static DB_POOL: Lazy<DbPool> = Lazy::new(|| {
    DbPool::connect("localhost:5432")
});
 
// std::sync::OnceLock - explicit initialization
static DB_POOL_STD: OnceLock<DbPool> = OnceLock::new();
 
fn get_pool() -> &'static DbPool {
    DB_POOL_STD.get_or_init(|| DbPool::connect("localhost:5432"))
}
 
struct DbPool;
impl DbPool {
    fn connect(_addr: &str) -> Self { DbPool }
}
 
fn main() {
    // Lazy: access directly
    let _pool = &*DB_POOL;
    
    // OnceLock: use helper or get_or_init each time
    let _pool = get_pool();
}

Lazy is more ergonomic for static lazy values.

Unsync Variants

// once_cell provides unsync (single-threaded) variants
use once_cell::unsync::OnceCell as UnsyncOnceCell;
use once_cell::unsync::Lazy as UnsyncLazy;
 
fn main() {
    // Single-threaded OnceCell (no synchronization overhead)
    let cell: UnsyncOnceCell<String> = UnsyncOnceCell::new();
    cell.set("value".to_string()).unwrap();
    
    // Single-threaded Lazy
    let lazy: UnsyncLazy<Vec<i32>> = UnsyncLazy::new(|| {
        vec![1, 2, 3]
    });
    
    println!("{:?}", *lazy);
    
    // std::sync::OnceLock is always thread-safe
    // No unsync variant in std (use Cell<Option<T>> or similar)
}

once_cell::unsync provides single-threaded variants without atomics overhead.

TryInsert Capability

use once_cell::sync::OnceCell;
use std::sync::OnceLock;
 
fn main() {
    // Both support try_insert (nightly/unstable in std)
    let cell: OnceCell<i32> = OnceCell::new();
    
    // once_cell: try_insert is stable
    match cell.try_insert(42) {
        Ok(&value) => println!("Inserted: {}", value),
        Err((_current, attempted)) => {
            println!("Already set to {}, tried {}", _current, attempted);
        }
    }
    
    // std::sync::OnceLock::set provides similar functionality
    let lock: OnceLock<i32> = OnceLock::new();
    match lock.set(42) {
        Ok(()) => println!("Set successfully"),
        Err(_) => println!("Already set"),
    }
}

Both support checking if already initialized when setting.

Thread Safety Implementation

use std::sync::OnceLock;
use once_cell::sync::OnceCell;
use std::thread;
 
fn main() {
    // Both use similar internal synchronization
    // OnceLock uses std::sync::Once internally
    // OnceCell uses a custom lock-free implementation
    
    static CELL: OnceCell<i32> = OnceCell::new();
    static LOCK: OnceLock<i32> = OnceLock::new();
    
    let h1 = thread::spawn(|| {
        CELL.get_or_init(|| {
            println!("OnceCell initializing");
            42
        })
    });
    
    let h2 = thread::spawn(|| {
        LOCK.get_or_init(|| {
            println!("OnceLock initializing");
            42
        })
    });
    
    h1.join().unwrap();
    h2.join().unwrap();
    
    // Both guarantee:
    // 1. Initialization happens exactly once
    // 2. All threads see the initialized value
    // 3. Initialization is thread-safe
}

Both provide the same thread-safety guarantees.

Migration from OnceCell to OnceLock

// Before: using once_cell
use once_cell::sync::OnceCell;
 
static OLD_STYLE: OnceCell<String> = OnceCell::new();
 
// After: using std
use std::sync::OnceLock;
 
static NEW_STYLE: OnceLock<String> = OnceLock::new();
 
// Migration is straightforward:
// 1. Change import
// 2. Change type name
// 3. API is compatible
 
// For Lazy, you need to keep using once_cell or create wrapper
use once_cell::sync::Lazy;  // Keep this
 
static STILL_NEEDED: Lazy<String> = Lazy::new(|| "value".to_string());
 
// Or create your own Lazy wrapper around OnceLock:
struct MyLazy<T> {
    cell: OnceLock<T>,
    init: fn() -> T,
}
 
impl<T> MyLazy<T> {
    fn new(init: fn() -> T) -> Self {
        MyLazy { cell: OnceLock::new(), init }
    }
    
    fn get(&self) -> &T {
        self.cell.get_or_init(|| (self.init)())
    }
}
 
impl<T: 'static> std::ops::Deref for MyLazy<T> {
    type Target = T;
    fn deref(&self) -> &T {
        self.get()
    }
}

Migration is simple except for Lazy which requires additional work.

Performance Characteristics

use once_cell::sync::OnceCell;
use std::sync::OnceLock;
use std::time::Instant;
 
fn main() {
    // Both have similar performance characteristics
    // First access: initialization cost + synchronization
    // Subsequent accesses: fast read (atomic check)
    
    const ITERATIONS: u32 = 1_000_000;
    
    static CELL: OnceCell<i32> = OnceCell::new();
    static LOCK: OnceLock<i32> = OnceLock::new();
    
    // Initialize both
    CELL.get_or_init(|| 42);
    LOCK.get_or_init(|| 42);
    
    // Benchmark reads
    let start = Instant::now();
    for _ in 0..ITERATIONS {
        let _ = CELL.get();
    }
    let cell_time = start.elapsed();
    
    let start = Instant::now();
    for _ in 0..ITERATIONS {
        let _ = LOCK.get();
    }
    let lock_time = start.elapsed();
    
    println!("OnceCell: {:?}", cell_time);
    println!("OnceLock: {:?}", lock_time);
    // Performance is nearly identical
}

Both have minimal overhead after initialization.

When to Use Each

// Use std::sync::OnceLock when:
// 1. You're on Rust 1.70+
// 2. You only need basic one-time initialization
// 3. You want to avoid external dependencies
// 4. Standard library is preferred
 
static CONFIG: OnceLock<Config> = OnceLock::new();
 
// Use once_cell::sync::OnceCell when:
// 1. Supporting Rust < 1.70
// 2. You need Lazy<T>
// 3. You need unsync variants
// 4. You need race::OnceCell (no interior mutability)
 
// Use once_cell::sync::Lazy when:
// 1. You want declarative static initialization
// 2. You want automatic initialization on access
// 3. The initialization closure captures environment
 
static COMPLEX: Lazy<Vec<String>> = Lazy::new(|| {
    let mut v = Vec::new();
    for i in 0..100 {
        v.push(format!("item_{}", i));
    }
    v
});

Choose based on Rust version and feature needs.

The race Module

// once_cell provides race module for non-blocking variants
use once_cell::race;
 
fn main() {
    // race::OnceBox: for boxed values, no interior mutability
    static BOXED: race::OnceBox<String> = race::OnceBox::new();
    BOXED.set(Box::new("value".to_string())).unwrap();
    
    // race::OnceRef: for references
    static REF: race::OnceRef<str> = race::OnceRef::new();
    REF.set("value").unwrap();
    
    // std doesn't have these specialized variants
    // They're useful when you need:
    // - Non-blocking reads after initialization
    // - No interior mutability guarantees
    // - Specialized memory management
}

The race module provides specialized non-blocking variants.

Complete Feature Matrix

use once_cell::sync::{OnceCell, Lazy};
use once_cell::unsync::{OnceCell as UnsyncOnceCell, Lazy as UnsyncLazy};
use once_cell::race::{OnceBox, OnceRef};
use std::sync::OnceLock;
 
fn main() {
    // === std::sync::OnceLock ===
    // Thread-safe one-time initialization
    // Stable in Rust 1.70+
    // Methods: new, get, get_or_init, get_mut, get_unchecked, set, take, into_inner
    
    // === once_cell::sync::OnceCell ===
    // Identical to OnceLock
    // Available in older Rust versions
    // Same methods as OnceLock
    
    // === once_cell::sync::Lazy ===
    // Thread-safe automatic initialization
    // NO EQUIVALENT IN STD
    // Implements Deref for automatic access
    
    // === once_cell::unsync::OnceCell ===
    // Single-threaded, no atomics
    // NO EQUIVALENT IN STD
    // Use Cell<Option<T>> for similar (but different) behavior
    
    // === once_cell::unsync::Lazy ===
    // Single-threaded automatic initialization
    // NO EQUIVALENT IN STD
    
    // === once_cell::race::OnceBox ===
    // Non-blocking, for boxed values
    // NO EQUIVALENT IN STD
    
    // === once_cell::race::OnceRef ===
    // Non-blocking, for references
    // NO EQUIVALENT IN STD
}

once_cell provides more variants than std.

Synthesis

Core functionality: OnceCell and OnceLock provide identical thread-safe one-time initialization with equivalent APIs.

Availability:

OnceLock: Standard library, Rust 1.70+
OnceCell: External crate, works on older Rust versions

API differences: Essentially none—same methods, same semantics, different names.

once_cell advantages:

Lazy<T>: Automatic initialization on access (no explicit get_or_init)
unsync module: Single-threaded variants without atomics overhead
race module: Non-blocking variants for specialized use cases
Backward compatibility with older Rust versions

OnceLock advantages:

No external dependencies
Standard library guarantees stability
Idiomatic for new projects on Rust 1.70+
Simpler Cargo.toml

Migration path: For basic use, replace OnceCell with OnceLock by changing imports and type names. For Lazy, either keep using once_cell or implement your own wrapper.

Key insight: OnceLock standardizes the most common use case of OnceCell—thread-safe one-time initialization. The once_cell crate remains valuable for its additional types (Lazy, unsync variants, race module) that aren't in std. For simple lazy statics on Rust 1.70+, OnceLock is the right choice. For declarative initialization or single-threaded scenarios, once_cell provides ergonomics that std doesn't yet match.

Loading page…

How does once_cell::sync::OnceCell differ from std::sync::OnceLock introduced in Rust 1.70?

Basic OnceCell Usage

Basic OnceLock Usage

API Comparison

The Lazy Type Difference

Lazy Initialization Pattern Comparison

Unsync Variants

TryInsert Capability

Thread Safety Implementation

Migration from OnceCell to OnceLock

Performance Characteristics

When to Use Each

The race Module

Complete Feature Matrix

Synthesis

How does once_cell::sync::OnceCell differ from std::sync::OnceLock introduced in Rust 1.70?

Basic OnceCell Usage

Basic OnceLock Usage

API Comparison

The Lazy Type Difference

Lazy Initialization Pattern Comparison

Unsync Variants

TryInsert Capability

Thread Safety Implementation

Migration from OnceCell to OnceLock

Performance Characteristics

When to Use Each

The race Module

Complete Feature Matrix

Synthesis

How does `once_cell::sync::OnceCell` differ from `std::sync::OnceLock` introduced in Rust 1.70?

How does `once_cell::sync::OnceCell` differ from `std::sync::OnceLock` introduced in Rust 1.70?