Awesome Concurrency

A C++ concurrency learning repository with implementations of various synchronization primitives and concurrent data structures.

Project Structure

awesome-concurrency/
├── src/
│   ├── os/
│   │   └── futex/         # Linux futex (fast userspace mutex) system calls
│   ├── thread/
│   │   ├── sync/          # Synchronization primitives (spinlocks, mutexes, etc.)
│   │   └── util/          # Utility functions (spin wait hints, etc.)
│   └── common/
│       └── common/
│           └── containers/ # Concurrent data structures
├── examples/
│   └── sync/              # Examples demonstrating synchronization primitives
├── tests/
│   ├── sync/              # Synchronization primitive tests
│   └── containers/        # Concurrent data structure tests
└── .vscode/               # VS Code tasks and shortcuts

Requirements

• CMake 3.14 or higher
• C++23 compatible compiler (GCC 12+, Clang 15+)
• pthread support
• clang-format (optional, for code formatting)

Building

# Configure
cmake -B build -S .

# Build
cmake --build build

# Run tests
cmake --build build --target run-tests

# Format code
cmake --build build --target format

Current Implementations

OS Primitives

• Futex - Linux futex (fast userspace mutex) wrapper for efficient kernel-level blocking

Synchronization Primitives

See src/thread/sync/ for detailed documentation.

• Three-State Mutex - Efficient mutex with fast-path (no syscall) lock/unlock and futex-based blocking
• MCS Spinlock - Scalable queue-based spinlock with FIFO ordering and minimal cache traffic
• Ticket Lock - Simple fair spinlock using ticket-based FIFO ordering
• TTAS Spinlock - Test-and-Test-and-Set spinlock with reduced cache coherence traffic

Concurrent Data Structures

See src/common/common/containers/ for detailed documentation.

• RingBuffer - Lock-free SPSC ring buffer with atomic operations
• FastRingBuffer - Cache-optimized SPSC ring buffer with local index caching

Utilities

• SpinLoopHint - Platform-specific CPU hints for busy-waiting

Running Tests

# Run all tests with CTest
cd build && ctest --output-on-failure

# Run specific test suite
./build/tests/sync/mcs_test

# Run with gtest filters
./build/tests/sync/mcs_test --gtest_filter=MCSSpinlockTest.MutualExclusion

Running Examples

# Run MCS spinlock example
./build/examples/sync/mcs_example

License

This is an educational project. Feel free to use and modify as needed for learning purposes.