Thetis26

Lock-free & wait-free C++20 — where every microsecond counts.

---

High-performance C++20 library for lockless/wait-free data structures, low-latency networking, and post-quantum cryptography.

Built for HFT, real-time telemetry, embedded devices (ESP32, RISC-V), and distributed infrastructure.

Concurrent Data Structures

Every structure ships in three variants: lock-based (baseline), lock-free, and wait-free — with 3-way benchmarks to prove it.

Structure	Variants	Key Feature
Ring Buffer	SPSC, MPMC v1-v4, LRQ	Up to 379 M ops/sec (SPSC), LCRQ linked segments
Dense Hashmap	v1-v6, WF v1-v6	Cooperative migration, dynamic resize, dual EBR
Ordered Dict	LF/WF skip list + EBR	Fraser/Harris + Kogan-Petrank helping
Stack	Treiber CAS, elimination array	Lock-free and wait-free with elimination backoff
Priority Queue	LF/WF skip list	CAS-guarded delete_min

All lock-free and wait-free variants use explicit std::memory_order (no default seq_cst), and include formal verification models (TLA+, CBMC, SPIN, GenMC, Nidhugg).

Performance at a Glance

Structure Best Throughput Ring Buffer SPSC 379 M ops/sec Ring Buffer MPMC 18 M ops/sec Dense Hashmap WF 117 M ops/sec Ordered Dict WF 27 M ops/sec UDP Loopback RTT ~9 us

Ordered Dict — Apple M4 1T: Lock 22M > LF 16M > WF 16M 4T: WF 24M > LF 14M > Lock 3M 8T: LF 26M = WF 26M >> Lock 2M WF overtakes Lock at 4 threads, matches LF at 8. Mutex collapses.

See docs/benchmark_summary.md and docs/performance.md for full results across Apple M4 and AMD 9950X3D.

Concurrency Primitives

• RDCSS / MCAS — multi-word compare-and-swap (Harris et al.)
• CAS2 — 128-bit on x86_64, 64-bit on RISC-V 32
• EBR — epoch-based reclamation for safe memory management
• STM — OneFile wait-free software transactional memory
• Pool Allocator — cache-line-aligned, thread-safe

Networking

• UDP/Multicast — zero-copy, kqueue/epoll/io_uring backends
• TCP — non-blocking with event loop integration
• TLS — via mbedtls (PQ-safe: ML-KEM-768, ML-DSA-65)
• WebSocket — frame parser, auto-reconnect client
• HTTP — minimal client for REST APIs

Post-Quantum Crypto

• AEAD — XChaCha20-Poly1305 (Monocypher)
• KEM — ML-KEM-768 (NIST PQC, via PQClean)
• Signatures — ML-DSA-65 (NIST PQC)
• Hash — BLAKE2b, SHA-3-256, SHA-256
• Constant-time verification — dudect methodology (Welch's t-test)

Quick Start

# Build
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

# Run all tests
ctest --test-dir build -j$(nproc) --output-on-failure

# Run a specific test
ctest --test-dir build -R test_dense_hashmap

When to Use Which Variant

	Lock-based	Lock-free	Wait-free
Wins at	1-2 threads, tiny critical sections	4-16 threads, write-heavy	High contention, tail latency matters
Mechanism	Mutex / rwlock	CAS retry loops	Bounded helping (Kogan-Petrank)
Throughput	Flatlines at 12-16M	Scales with core count	Matches LF within 5-15%
Tail latency	Unbounded (starvation)	Unbounded (CAS storm)	Bounded by design
Best for	Prototyping, low-thread embedded	General-purpose concurrent	Real-time, HFT, safety-critical

Formal Verification

20 models across 5 tools, all passing:

TLA+ · CBMC · SPIN · GenMC · Nidhugg

Models are in models/. Run with:

docker build -f docker/Dockerfile.formal -t thetis26-formal .
docker run --rm thetis26-formal

Cross-Platform

Builds and tests on: x86_64 Linux, ARM64 Linux, macOS (Apple Silicon), RISC-V 32, FreeBSD, ESP32-C3/S3.

Script	What it does	Runtime
scripts/ci_multiplatform.sh	All platforms (Docker)	~1-2 hours
scripts/cross_arm64.sh	ARM64 cross-compile + QEMU	~10-15 min
scripts/cross_rv32.sh	RISC-V 32 cross-compile	~40+ min
scripts/cross_freebsd.sh	FreeBSD cross-compile + QEMU	~5 min
scripts/cross_esp32.sh	ESP32-C3/S3 compile + QEMU	~15-20 min

Testing

75 test targets covering correctness, fuzz testing, performance scaling, networking, and crypto.

# Sanitizers
scripts/run_ctest_asan.sh          # AddressSanitizer
scripts/run_ctest_tsan.sh          # ThreadSanitizer

# Coverage
scripts/run_ctest_coverage.sh      # llvm-cov (Clang) or gcovr (GCC)

# 3-way benchmarks (lock vs lock-free vs wait-free)
build/tests/test_ring_buffer_wf    -tc="*3-way*"
build/tests/test_dense_hashmap_wf  -tc="*3-way*"
build/tests/test_ordered_dict_wf   -tc="*3-way*"

# Thread count scaling (1T -> 32T)
build/tests/test_dense_hashmap_scaling
build/tests/test_ordered_dict_scaling
build/tests/test_ring_buffer_scaling

# Fuzz testing
THETIS_FUZZ_ROUNDS=20 build/tests/test_fuzz_dense_hashmap

Profiling & Flamegraphs

# Generate profiles
scripts/profile_tests.sh --target test_ordered_dict_lf    # single test
scripts/profile_tests.sh                                   # ALL tests (~15-30 min)

macOS — use Instruments:

xcrun xctrace record --template "Time Profiler" \
  --launch build/tests/test_dense_hashmap_scaling \
  --output output/hashmap.trace
open output/hashmap.trace

Linux — use perf:

perf report -i output/profiles/<timestamp>/<test>/perf.data

Tip: Use long-running targets like test_dense_hashmap_scaling for meaningful profiles.

Typical Runtimes

Command	Time
ctest --test-dir build -j$(nproc)	~1 min
scripts/run_ctest_asan.sh	~2-3 min
scripts/run_ctest_tsan.sh	~6 min
scripts/ci.sh --quick	~2 min
scripts/ci.sh	~15-20 min
scripts/profile_tests.sh	~15-30 min
scripts/ci_multiplatform.sh	~1-2 hours

CI

scripts/ci.sh                      # Full: Release + ASAN + TSAN + fuzz + formal verification
scripts/ci.sh --quick              # Release + CTest only

Demo Applications

• VDF-DB — Verifiable Delay Function database with Block-STM executor, WAL, snapshots, crash recovery
• UDP motion detection — multi-node camera + analysis pipeline
• Multicast demo — pub/sub over UDP multicast
• Exchange connectors — WebSocket feeds for Binance, Coinbase, Kraken, Bybit, OKX

Project Structure

include/thetis/          # Header-only data structures + primitives
include/thetis/net/      # Networking (UDP, TCP, TLS, WebSocket)
include/thetis/crypto/   # Post-quantum crypto (ML-KEM, ML-DSA, AEAD)
src/                     # Compiled library source
tests/                   # 75 test targets
examples/                # Demo applications
models/                  # Formal verification (TLA+, CBMC, SPIN, GenMC)
scripts/                 # Build, CI, profiling, cross-compilation
docker/                  # Dockerfiles for all platforms
docs/                    # Performance analysis, research notes

Dependencies

All vendored in third_party/ — no external package managers, no downloads at build time.

Library	License	Purpose
Monocypher 4.0.2	BSD-2-Clause	AEAD (XChaCha20-Poly1305)
PQClean	CC0	Post-quantum KEM + signatures
mbedTLS 3.6.3 LTS	Apache-2.0	TLS, WebSocket, certificates
yyjson 0.10.0	MIT	JSON parsing
doctest 2.4.11	MIT	Unit test framework

Full SBOM: docs/sbom.md

Requirements

• C++20 compiler (Clang 15+, GCC 13+, Apple Clang 15+)
• CMake 3.20+
• Docker (optional, for cross-platform and formal verification)

License

BSD-3-Clause — see LICENSE.