# How LiteBox Implements Futex-Based Synchronization Across Platforms

> Discover how LiteBox achieves cross-platform futex synchronization without kernel syscalls. Learn about its portable futex abstraction for Linux, Windows, and OP-TEE.

- Repository: [Microsoft/litebox](https://github.com/microsoft/litebox)
- Tags: internals
- Published: 2026-02-16

---

**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`](https://github.com/microsoft/litebox/blob/main/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`](https://github.com/microsoft/litebox/blob/main/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`](https://github.com/microsoft/litebox/blob/main/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`](https://github.com/microsoft/litebox/blob/main/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`](https://github.com/microsoft/litebox/blob/main/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`](https://github.com/microsoft/litebox/blob/main/litebox_shim_linux/src/syscalls/process.rs). This shim parses `FutexArgs` and `FutexOperation` (defined in [`litebox_common_linux/src/lib.rs`](https://github.com/microsoft/litebox/blob/main/litebox_common_linux/src/lib.rs) and [`litebox_platform_linux_userland/src/lib.rs`](https://github.com/microsoft/litebox/blob/main/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:

```rust
// 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`](https://github.com/microsoft/litebox/blob/main/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`](https://github.com/microsoft/litebox/blob/main/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`](https://github.com/microsoft/litebox/blob/main/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`](https://github.com/microsoft/litebox/blob/main/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`](https://github.com/microsoft/litebox/blob/main/litebox/src/sync/futex.rs), which contains the `FutexManager`, `FutexEntry`, and wait/wake logic. Supporting files include [`litebox/src/sync/mod.rs`](https://github.com/microsoft/litebox/blob/main/litebox/src/sync/mod.rs) (defining `RawSyncPrimitivesProvider`), [`litebox/src/utilities/loan_list.rs`](https://github.com/microsoft/litebox/blob/main/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`](https://github.com/microsoft/litebox/blob/main/litebox_shim_linux/src/syscalls/process.rs) (Linux syscall handling) and [`litebox_platform_linux_userland/src/lib.rs`](https://github.com/microsoft/litebox/blob/main/litebox_platform_linux_userland/src/lib.rs) (argument parsing).