Concurrency Lab

A SwiftPM CLI project for comparing multiple concurrency primitives in macOS environments. The lab implements three scenarios (numeric counter, file download, aggregated network request) using five techniques arranged from older to newer APIs:

• pthread – raw POSIX threads and mutexes
• NSThread – Foundation threads with condition-based coordination
• GCD – Grand Central Dispatch queues, groups, and semaphores
• Operation / OperationQueue – block operations with dependency management
• Swift Concurrency – structured concurrency (async/await, task groups, actors)

Each scenario exposes the same command-line surface so you can swap implementations and compare correctness, performance, and ease of expression.

Project layout

concurrency-lab/
├─ Package.swift
├─ README.md
├─ Docs/
│  ├─ implementation-notes.md
│  └─ operation-guidelines.md
├─ Reports/
│  ├─ counter.csv
│  ├─ download.csv
│  ├─ network.csv
│  ├─ counter_elapsed.svg
│  ├─ download_elapsed.svg
│  ├─ network_elapsed.svg
│  ├─ metrics.csv
│  └─ summary.md
├─ Reports_limit5/
├─ Reports_limit10/
├─ Sources/
│  └─ lab/
│     ├─ Counter/
│     ├─ Download/
│     ├─ Network/
│     ├─ NSThreadHelpers.swift
│     ├─ Reporting.swift
│     ├─ Utils.swift
│     └─ main.swift
└─ scripts/
      bench.sh, metrics.sh, plot.py, aggregate_reports.py, sort_report.py

See Docs/implementation-notes.md for a walkthrough of the concrete implementations.

CLI usage

swift build
swift run lab <command> --impl <pthread|nsthread|gcd|operation|concurrency> [options]

Available commands and their options:

Command	Required options	Optional options
counter	--n <int> --threads <int> --tasks <int>	--unsafe (disable synchronization)
download	--urls url1,url2,... --limit <int>	–
net	--user <int>	–

Shared options:

• --report csv|json – emit result files under Reports/.
• --report-path <path> – custom destination for the report.
• lab help – print a summary of commands and option tables.

Reporting and automation

• scripts/bench.sh [output_dir] [n] [threads] [tasks] [limit] runs all implementations, writes per-scenario CSVs, aggregates /tmp/lab.csv, and produces a sorted /tmp/lab_sorted.csv (pthread → NSThread → GCD → Operation → Concurrency).
• scripts/metrics.sh [output_csv] collects SLOC and lock-token counts for every Swift source file.
• scripts/plot.py renders SVG bar charts from the CSV data (counter safe/unsafe, download averages, network elapsed).
• Additional download experiments with limits 5 and 10 are stored in Reports_limit5/ and Reports_limit10/.

Reports include ok/notes columns so unsafe variants visibly fail (data races) while safe variants remain correct.

Reference data

• Primary results: Reports/summary.md, Reports/*.csv, /tmp/lab_sorted.csv
• Alternative download limits: Reports_limit5/, Reports_limit10/
• Concurrency guidelines: Docs/operation-guidelines.md

Feel free to adapt the scripts or parameters to match your hardware and workload before drawing comparisons.