How LiteBox Implements Futex-Based Synchronization Across Platforms

LiteBox provides a portable, user-space futex abstraction that works across Linux, Windows, and OP-TEE by implementing a generic FutexManager using only abstract platform traits, eliminating the need for kernel futex syscalls.

The microsoft/litebox repository implements a futex-based synchronization module that enables efficient thread waiting and waking without requiring platform-specific kernel interfaces. This system allows LiteBox to run identical synchronization logic across diverse environments including Linux userland, Windows, and trusted execution environments like OP-TEE.

Core Architecture of LiteBox Futex-Based Synchronization

The FutexManager and Hash Table Design

At the heart of LiteBox's implementation is the FutexManager<Platform> struct defined in litebox/src/sync/futex.rs. This generic manager maintains a fixed-size hash table with HASH_TABLE_ENTRIES = 256 buckets, where each bucket is a LoanList (an intrusive linked list defined in litebox/src/utilities/loan_list.rs).

Each entry in the hash table stores a FutexEntry containing the waiter's Waker and an optional bitset for selective wake operations. The manager handles all synchronization logic in user space, only requiring the platform to provide basic primitives like mutexes and time providers through the RawSyncPrimitivesProvider trait defined in litebox/src/sync/mod.rs.

Platform Abstraction via RawSyncPrimitivesProvider

The RawSyncPrimitivesProvider trait abstracts all platform-specific functionality needed by the futex manager. Implementations must provide:

• A RawMutexProvider for basic locking
• Optional TimeProvider and DebugLogProvider when lock tracing is enabled

This design allows FutexManager to remain completely portable. For example, litebox_platform_linux_userland implements these traits using spin::Mutex and standard Instant, while OP-TEE implementations use secure world mutex primitives.

How Futex Wait Operations Work in LiteBox

When a thread calls the futex wait operation through FutexManager::wait in litebox/src/sync/futex.rs, the following sequence occurs:

1. Alignment verification: The system verifies the futex address is 4-byte aligned, returning an error if not.

2. Entry insertion: A FutexEntry containing the caller's Waker and optional bitset is inserted into the appropriate hash bucket using the LoanList structure.

3. Value check: The futex word is read once. If the value does not match the expected value, the entry is removed and ImmediatelyWokenBecauseValueMismatch is returned immediately.

4. Blocking: If the value matches, the current task blocks via WaitContext::wait_until, waiting for the entry's done flag to be set by a subsequent wake operation.

The waiting block utilizes the platform's wait primitive through WaitContext, which ultimately relies on platform-specific event loops such as Linux epoll, Windows I/O completion ports, or mock schedulers in test environments.

How Futex Wake Operations Work in LiteBox

The FutexManager::wake method handles waking waiters without invoking kernel futex syscalls. The implementation in litebox/src/sync/futex.rs follows this process:

1. Alignment check: Verifies the futex address is 4-byte aligned.

2. Bucket location: Computes the hash and locates the corresponding LoanList bucket.

3. Selective traversal: Walks the bucket's list, extracting FutexEntry items where the address matches and the entry's bitset intersects with the requested wake mask (if specified), until num_to_wake waiters have been collected.

4. Waking: For each extracted entry, sets done = true and invokes the stored Waker, allowing the blocked task to resume.

Because all waiters are tracked in user-space structures, the wake operation is completely in-process and requires no context switches to the kernel. This design is particularly efficient for LiteBox's containerized workloads where all threads share the same address space.

Cross-Platform Portability Strategy

LiteBox achieves cross-platform futex support through a layered architecture that separates generic synchronization logic from platform-specific primitives.

Linux Userland Implementation

On Linux, the futex syscall handler resides in litebox_shim_linux/src/syscalls/process.rs. This shim parses FutexArgs and FutexOperation (defined in litebox_common_linux/src/lib.rs and litebox_platform_linux_userland/src/lib.rs) and forwards them to the generic FutexManager.

The Linux implementation specifically checks for FUTEX_PRIVATE_FLAG and logs warnings for unsupported shared futex attempts via log_unsupported!("shared futex"), ensuring that only private futexes (single-process) are used. This limitation aligns with LiteBox's container model where processes are isolated.

Windows and OP-TEE Support

The same FutexManager code compiles for Windows and OP-TEE environments by substituting the Platform type parameter with platform-specific implementations of RawSyncPrimitivesProvider. For example:

• Windows: Uses I/O completion ports for the WaitContext implementation
• OP-TEE: Uses secure world mutex primitives and trusted time sources

This means application code using LiteBox futexes requires no changes when ported between Linux, Windows, or trusted execution environments.

Practical Example: Using LiteBox Futexes in Rust

The following example demonstrates how to use LiteBox's futex-based synchronization in application code. This same code runs unchanged across all supported platforms:

// Create a LiteBox instance (platform-specific)
let platform = litebox_platform_multiplex::Platform::new();
let litebox = LiteBox::new(platform);

// Obtain a reference to the futex manager (exposed via the shim)
let futex_mgr = litebox.global.futex_manager.clone();

// ----- Wait side (in one thread) -----
let futex_addr = unsafe { /* obtain a RawMutPointer<u32> to a shared word */ };
let wait_ctx = litebox.wait_cx(); // WaitContext tied to the current task

std::thread::spawn(move || {
    // Wait until the word becomes 1 (private futex)
    futex_mgr
        .wait(&wait_ctx, futex_addr, 0, None)
        .expect("futex wait failed");
    println!("woken!");
});

// ----- Wake side (in another thread) -----
let new_val = 1u32;
unsafe { futex_addr.write_at_offset(0, new_val).unwrap() };
futex_mgr
    .wake(futex_addr, NonZeroU32::new(1).unwrap(), None)
    .expect("futex wake failed");

In this example, the FutexManager::wait and FutexManager::wake methods handle all synchronization without kernel futex syscalls, demonstrating the efficiency of LiteBox's user-space implementation.

Summary

LiteBox's futex-based synchronization module provides a portable, high-performance solution for thread waiting and waking across diverse platforms:

• Generic Implementation: The FutexManager<Platform> in litebox/src/sync/futex.rs implements all futex logic using only abstract platform traits, enabling compilation for Linux, Windows, and OP-TEE.
• User-Space Efficiency: All wait and wake operations occur in-process using a 256-bucket hash table of LoanList structures, eliminating kernel context switches for private futexes.
• Platform Abstraction: The RawSyncPrimitivesProvider trait isolates platform-specific details like mutex implementations and time providers, allowing the same futex manager to run on litebox_platform_linux_userland and other targets.
• Linux Compatibility: The shim layer in litebox_shim_linux/src/syscalls/process.rs translates Linux futex syscalls into generic manager calls, supporting FUTEX_PRIVATE_FLAG while logging unsupported shared futex attempts.

Frequently Asked Questions

What is a futex and why does LiteBox use them?

A futex (fast userspace mutex) is a synchronization primitive that allows threads to wait for memory-address-based conditions efficiently. LiteBox uses a futex-based synchronization module to provide POSIX-compatible thread synchronization across platforms that may not natively support Linux futexes, such as Windows or OP-TEE. By implementing futex semantics in user space, LiteBox avoids expensive kernel transitions while maintaining compatibility with existing Linux applications.

How does LiteBox handle shared futexes across processes?

LiteBox does not support shared futexes across processes. The implementation in litebox/src/sync/futex.rs explicitly ignores shared-futex flags with a log_unsupported!("shared futex") warning. This limitation is intentional because LiteBox runs isolated containers where each process has its own address space, making private futexes sufficient. The Linux shim in litebox_shim_linux/src/syscalls/process.rs enforces this by checking for FUTEX_PRIVATE_FLAG and rejecting shared futex operations.

What platforms does LiteBox's futex module support?

LiteBox's futex module supports Linux userland, Windows, and OP-TEE (trusted execution environments). The same FutexManager code compiles for all platforms because it is generic over the RawSyncPrimitivesProvider trait. Platform-specific implementations in litebox_platform_linux_userland, litebox_platform_windows, and OP-TEE platforms provide the required mutex, time, and wait context primitives, while shim layers translate native system calls into generic futex operations.

Where is the futex implementation located in the LiteBox codebase?

The core futex implementation resides in litebox/src/sync/futex.rs, which contains the FutexManager, FutexEntry, and wait/wake logic. Supporting files include litebox/src/sync/mod.rs (defining RawSyncPrimitivesProvider), litebox/src/utilities/loan_list.rs (the intrusive list for wait queues), and platform-specific shims such as litebox_shim_linux/src/syscalls/process.rs (Linux syscall handling) and litebox_platform_linux_userland/src/lib.rs (argument parsing).

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