# synchro

**Repository Path**: stkid/synchro

## Basic Information

- **Project Name**: synchro
- **Description**: synchro is an operating system lock strategy research project
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-17
- **Last Updated**: 2026-04-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**synchro** is an operating system lock strategy research project consisting of three components:
- **libsynchro** - Lock strategy implementation library (7 lock types implemented)
- **synchro-bench** - Benchmarking framework (implemented)
- **synchro-picker** - Lock strategy decision assistance tool (implemented)

**Target Environment**: Userspace POSIX threads
**Language**: C (C11 + GCC atomics fallback)
**Build System**: GNU Automake

## Build Commands

```bash
# Build library only
./configure && make && make install

# Build library + benchmark tool
./configure --enable-bench && make

# Build all components (library + bench + picker)
./configure --enable-bench --enable-picker && make

# Run all tests
make check

# Clean rebuild
git clean -fdx && autoreconf -i && ./configure --enable-bench --enable-picker && make
```

## Architecture

### Lock Library Interface

All lock types use unified naming: `lock_xxx_t` with `lock_xxx_config_t` for configuration.
- Return values: success 0, failure negative error code
- NULL config uses defaults
- MCS/CLH locks require caller-provided node (typically on thread stack)

### Implemented Lock Types

| Type | Use Case | Key Features |
|------|----------|--------------|
| spin | Extremely short critical sections | Configurable backoff (none/linear/exponential) |
| mutex | Longer critical sections | pthread wrapper, errorcheck/recursive types |
| ticket | FIFO fairness | Simple queue-based, no starvation |
| rwlock | Read-heavy workloads | Reader-pref/writer-pref policies |
| mcs | High contention with fairness | Queue-based, local spinning, FIFO |
| clh | Similar to MCS | Different queue structure, local spinning |
| adaptive | Variable critical sections | Spin-then-sleep hybrid, configurable threshold |

### Key Design Decisions

1. **No external dependencies** - Only pthread + atomics
2. **Unified interface** - All locks follow the same init/lock/unlock/destroy pattern
3. **Configurable backoff** - Spin locks support none, linear, exponential backoff
4. **Fairness options** - MCS/CLH/ticket provide FIFO guarantees; rwlock has reader-pref/writer-pref/fair policies
5. **Atomic abstraction** - `SYNCHRO_ATOMIC(T)` macro supports C11 atomics with GCC atomics fallback

## synchro-bench CLI Usage

```bash
# Basic usage - single lock
./bench/synchro-bench --lock spin --threads 4 --iterations 10000

# Run all supported lock types (spin, mutex, ticket, rwlock, adaptive)
./bench/synchro-bench --all --threads 8

# With workload (critical section cycles)
./bench/synchro-bench --lock mutex --threads 4 --cycles 100

# JSON output
./bench/synchro-bench --all --json

# Note: mcs and clh require per-thread nodes, not supported in generic bench
./bench/synchro-bench --help
```

### Benchmark Metrics

- **throughput_ops_per_sec** - Operations per second
- **fairness_index** - Jain's fairness index (0-1, 1=perfect)
- **max_wait_ns** / **avg_wait_ns** / **p99_wait_ns** - Latency metrics

## synchro-picker CLI Usage

```bash
# Get recommendation for read-heavy workload
./picker/synchro-picker --cs-cycles 100-5000 --read-ratio 0.8 --threads 16 --contention high

# Get recommendation for small critical section
./picker/synchro-picker --cs-cycles 50-100 --threads 8 --contention high

# Require FIFO fairness
./picker/synchro-picker --contention high --fairness

# JSON output
./picker/synchro-picker --cs-cycles 100-500 --read-ratio 0.75 --json

# Full options
./picker/synchro-picker --help
```

### Recommendation Rules

Picker evaluates scenarios based on:
- Critical section size (small <100, large >10000 cycles)
- Read ratio (>0.7 = read-heavy)
- Contention level (low/medium/high)
- Special requirements (fairness, realtime)

Output includes primary/secondary recommendations with confidence level and configuration suggestions.

## Testing

Uses **Cmocka** framework. Test programs:

| Component | Tests |
|-----------|-------|
| lib/test_spin | 7 tests (init, config, lock/unlock, trylock, backoff) |
| lib/test_mutex | 5 tests (init, config, lock/unlock, trylock) |
| lib/test_ticket | 3 tests (init, lock/unlock) |
| lib/test_rwlock | 7 tests (init, rdlock, wrlock, concurrent readers) |
| lib/test_mcs | 5 tests (init, lock/unlock, FIFO order) |
| lib/test_clh | 5 tests (init, lock/unlock, sequential) |
| lib/test_adaptive | 6 tests (init, threshold, concurrent) |
| lib/test_concurrent | 3 tests (multi-threaded correctness) |
| bench/test_workload | 4 tests (workload generation) |
| bench/test_metrics | 5 tests (metrics collection, fairness) |
| bench/test_benchmark | 3 tests (benchmark runner) |

Run single test:
```bash
cd lib && ./test_spin
cd lib && ./test_rwlock
cd bench && ./test_benchmark
```

## Project Status

**All components implemented:**
- libsynchro: spin, mutex, ticket, rwlock, mcs, clh, adaptive locks
- synchro-bench: workload generation, metrics collection, CLI
- synchro-picker: scenario analysis, rule-based recommendations, CLI

## Documentation

Design specification: `docs/superpowers/specs/2026-04-16-synchro-design.md`
Implementation plans: `docs/superpowers/plans/`