LiteBox Synchronization Primitives: Mutex, RwLock, Futex, and Condition Variables

LiteBox provides five core synchronization primitives—Mutex, RwLock, Condvar, FutexManager, and the RawSyncPrimitivesProvider trait—that enable thread-safe concurrency across Linux, Windows, and embedded targets without requiring the standard library.

The microsoft/litebox repository implements a platform-agnostic synchronization layer designed for no_std environments. These synchronization primitives abstract OS-specific raw mutexes into safe Rust APIs that mirror std::sync while eliminating poisoning semantics and reducing kernel transitions through spin-optimized paths.

Overview of LiteBox Synchronization Primitives

All synchronization types reside in the litebox::sync module and are generic over a Platform type implementing RawSyncPrimitivesProvider. This architecture allows the same high-level APIs to operate across Linux userland, Windows, LVBS, and OP-TEE environments.

The following primitives are defined in litebox/src/sync/:

• Mutex — Spin-enabled mutual exclusion lock (mutex.rs)
• RwLock — Reader-writer lock with mapped guard variants (rwlock.rs)
• Condvar — Condition variable placeholder (condvar.rs)
• FutexManager — Fast userspace mutex implementation (futex.rs)
• RawSyncPrimitivesProvider — Platform abstraction trait (mod.rs)

Core Synchronization Primitives

Mutex: Spin-Enabled Mutual Exclusion

The Mutex type in litebox/src/sync/mutex.rs provides a mutual exclusion lock that spins briefly before delegating to the platform's blocking primitive. This hybrid approach minimizes expensive kernel transitions during low-contention scenarios.

Mutex returns a MutexGuard that automatically unlocks when dropped. Unlike std::sync::Mutex, LiteBox's implementation does not implement poisoning—successful acquisition always returns the guard regardless of previous panics.

use litebox::sync::Mutex;
use litebox::platform::mock::MockPlatform;

static COUNTER: Mutex<MockPlatform, u32> = Mutex::new(0);

fn increment() {
    let mut guard = COUNTER.lock();
    *guard += 1;
    // Guard dropped here, releasing the lock
}

RwLock: Reader-Writer Locking

Defined in litebox/src/sync/rwlock.rs, RwLock supports multiple concurrent readers or a single exclusive writer. The implementation uses a u32 state word to track reader counts and writer flags, falling back to the platform raw mutex only when contention requires blocking.

The type provides RwLockReadGuard and RwLockWriteGuard, both offering mapped variants (map, try_map) that allow downgrading a guard to a subfield of the protected data without releasing the lock.

use litebox::sync::RwLock;
use litebox::platform::mock::MockPlatform;

static DATA: RwLock<MockPlatform, Vec<u8>> = RwLock::new(Vec::new());

fn read_data() {
    let guard = DATA.read();
    println!("Length: {}", guard.len());
}

fn write_data() {
    let mut guard = DATA.write();
    guard.push(42);
}

Condvar: Condition Variables

The Condvar type in litebox/src/sync/condvar.rs currently serves as a thin wrapper around the raw mutex abstraction. While the API surface mimics std::sync::Condvar, the implementation is pending full futex integration.

This primitive is intended to enable threads to wait for boolean conditions to become true while atomically releasing the associated mutex.

use litebox::sync::Condvar;
use litebox::platform::mock::MockPlatform;

static COND: Condvar<MockPlatform> = Condvar::new();
// Note: Full wait/notify implementation pending futex integration

FutexManager: Fast Userspace Mutex

FutexManager in litebox/src/sync/futex.rs implements Linux-style futex semantics for user-space scheduling. This primitive manages a hash-bucket table of wait-queues (LoanList) keyed by memory addresses, allowing threads to sleep (wait) and wake (wake) with minimal kernel intervention.

The futex layer serves as the foundation for higher-level blocking primitives and enables LiteBox to implement no_std compatible parking lot-style synchronization.

use litebox::sync::FutexManager;
use litebox::platform::mock::MockPlatform;
use core::num::NonZeroU32;

fn futex_demo() {
    let futex = FutexManager::<MockPlatform>::new();
    let mut word: u32 = 0;
    let ptr = unsafe { MockPlatform::raw_mut_pointer(&mut word) };
    
    // Wait for value to change from 0
    futex.wait(&litebox::event::wait::WaitContext::new(), ptr, 0, None).unwrap();
    
    // Wake one waiter
    futex.wake(ptr, NonZeroU32::new(1).unwrap(), None).unwrap();
}

Platform Abstraction with RawSyncPrimitivesProvider

All synchronization primitives depend on the RawSyncPrimitivesProvider trait defined in litebox/src/sync/mod.rs. This trait binds a platform's RawMutex implementation to LiteBox's high-level APIs, enabling the same synchronization code to compile for Linux userland, Windows, LVBS, and secure hypervisors like OP-TEE.

Platform crates (e.g., litebox_platform_linux_userland, litebox_platform_windows_userland) implement this trait to supply concrete blocking and atomic operations. When lock-tracing is enabled, the trait also connects time and debug-log services for profiling synchronization behavior.

Summary

LiteBox delivers a complete no_std synchronization toolkit through the litebox::sync module:

• Mutex provides spin-optimized mutual exclusion with automatic guard-based unlocking in litebox/src/sync/mutex.rs
• RwLock supports concurrent readers or exclusive writers with mapped guard variants in litebox/src/sync/rwlock.rs
• Condvar offers a condition variable API pending full futex integration in litebox/src/sync/condvar.rs
• FutexManager implements low-level wait/wake semantics for user-space scheduling in litebox/src/sync/futex.rs
• RawSyncPrimitivesProvider enables cross-platform portability by abstracting raw mutex implementations in litebox/src/sync/mod.rs

Frequently Asked Questions

Are LiteBox synchronization primitives compatible with no_std environments?

Yes, all LiteBox synchronization primitives are explicitly designed for no_std compatibility. They avoid dependencies on the Rust standard library by relying on the platform-specific RawSyncPrimitivesProvider trait to supply blocking and atomic operations.

How does LiteBox Mutex differ from std::sync::Mutex?

LiteBox's Mutex differs in three key ways: it implements spin-optimization before blocking to reduce kernel transitions, it does not implement poisoning semantics (always returning the guard on success), and it is generic over a Platform type rather than using system calls directly.

What platforms does LiteBox support?

LiteBox supports Linux userland, Windows, LVBS (Lightweight Virtualization-Based Security), and secure hypervisors like OP-TEE. Each platform implements the RawSyncPrimitivesProvider trait in dedicated platform crates (e.g., litebox_platform_linux_userland).

Does LiteBox implement lock poisoning?

No, LiteBox deliberately avoids poisoning semantics. Unlike std::sync types that poison locks when threads panic while holding them, LiteBox primitives simply return the guard upon successful acquisition regardless of previous thread behavior.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}