https://github.com/codenimja/nimsync
https://github.com/codenimja/nimsync
actors async async-runtime channels concurrency high-performance lock-free nim structured-concurrency
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/codenimja/nimsync
- Owner: codenimja
- License: mit
- Created: 2025-10-28T22:11:58.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-10-28T23:47:44.000Z (5 months ago)
- Last Synced: 2025-10-29T00:27:07.512Z (5 months ago)
- Topics: actors, async, async-runtime, channels, concurrency, high-performance, lock-free, nim, structured-concurrency
- Language: Nim
- Size: 3.99 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# nimsync
[](https://github.com/codenimja/nimsync/actions/workflows/ci.yml)
[](https://github.com/codenimja/nimsync/actions/workflows/benchmark.yml)
[](https://nimble.directory/pkg/nimsync)
[](LICENSE)
[](https://nim-lang.org)
**Lock-free SPSC channels for Nim with production-grade performance validation**
nimsync v1.0.0 is production-ready for SPSC channels with comprehensive benchmarking following industry standards (Tokio, Go, LMAX Disruptor, Redis). Performance: 615M ops/sec peak throughput, 31ns P99 latency, stable under burst loads. This is verified, tested, real code.
## Features
- **High throughput**: 615M ops/sec (raw), 512K ops/sec (async) - [See all 7 benchmarks](#performance)
- **Production-validated**: Comprehensive benchmark suite (throughput, latency, burst, stress, sustained)
- **Industry-standard testing**: Following Tokio, Go, Rust Criterion, LMAX Disruptor methodologies
- Lock-free ring buffer with atomic operations
- Zero GC pressure with ORC memory management
- Cache-line aligned (64 bytes) to prevent false sharing
- Power-of-2 sizing for efficient operations
- Non-blocking `trySend`/`tryReceive`
- Async `send`/`recv` wrappers for Chronos
## Installation
### Requirements
- Nim 2.0.0+ (required)
- Chronos 4.0.0+
### Via Nimble
```bash
nimble install nimsync
```
### From Source
```bash
git clone https://github.com/codenimja/nimsync.git
cd nimsync
nimble install
```
## Quick Start
### Basic Usage
```nim
import nimsync
# Create SPSC channel with 16 slots
let chan = newChannel[int](16, ChannelMode.SPSC)
# Non-blocking operations
if chan.trySend(42):
echo "Sent successfully"
var value: int
if chan.tryReceive(value):
echo "Received: ", value
```
### Async Operations
```nim
import nimsync
import chronos
proc producer(ch: Channel[int]) {.async.} =
for i in 1..10:
await ch.send(i)
proc consumer(ch: Channel[int]) {.async.} =
for i in 1..10:
let value = await ch.recv()
echo "Received: ", value
proc main() {.async.} =
let ch = newChannel[int](16, ChannelMode.SPSC)
await allFutures([producer(ch), consumer(ch)])
waitFor main()
```
## API Reference
### Channel Creation
```nim
proc newChannel[T](size: int, mode: ChannelMode): Channel[T]
```
Creates a channel with specified size (rounded to next power of 2).
Only `ChannelMode.SPSC` is implemented.
### Non-Blocking Operations
```nim
proc trySend[T](channel: Channel[T], value: T): bool
proc tryReceive[T](channel: Channel[T], value: var T): bool
```
Returns `true` on success, `false` if channel is full/empty.
**Use these for maximum performance** (sub-100ns operations).
### Async Operations
```nim
proc send[T](channel: Channel[T], value: T): Future[void] {.async.}
proc recv[T](channel: Channel[T]): Future[T] {.async.}
```
Async wrappers using Chronos. **Note**: Uses 1ms polling internally.
### Utilities
```nim
proc isEmpty[T](channel: Channel[T]): bool
proc isFull[T](channel: Channel[T]): bool
```
## Performance
### Comprehensive Benchmark Suite
nimsync includes 7 official benchmarks following industry best practices:
| Benchmark | Metric | Result | Industry Reference |
|-----------|--------|--------|--------------------|
| **Throughput** | Peak ops/sec | 615M | Go channels benchmarking |
| **Latency** | p50/p99/p99.9 | 30ns/31ns/31ns | Tokio/Cassandra percentiles |
| **Burst Load** | Stability | 300M ops/sec, 21% variance | Redis burst testing |
| **Buffer Sizing** | Optimal size | 2048 slots, 559M ops/sec | LMAX Disruptor |
| **Stress Test** | Contention | 0% at 500K ops | JMeter/Gatling |
| **Sustained** | Long-duration | Stable over 10s | Cassandra/ScyllaDB |
| **Async** | Overhead | 512K ops/sec | Standard async benchmarking |
### Quick Run
```bash
# Run complete benchmark suite (~18 seconds)
./tests/performance/run_all_benchmarks.sh
# Run individual benchmarks
nim c -d:danger --opt:speed --mm:orc tests/performance/benchmark_latency.nim
./tests/performance/benchmark_latency
```
**Full Documentation**: See [`tests/performance/README.md`](tests/performance/README.md) for detailed explanations of each benchmark.
```
### Third-Party Verification
Want to verify these claims yourself?
- **Reproduction Guide**: See [BENCHMARKS.md](BENCHMARKS.md) and [tests/performance/README.md](tests/performance/README.md)
- **CI Benchmarks**: Automatic benchmarks on every commit → [GitHub Actions](https://github.com/codenimja/nimsync/actions/workflows/benchmark.yml)
- **Expected Range**: 20M-600M ops/sec depending on CPU, benchmark type, and system load
## Limitations
1. **SPSC Only** - Single Producer Single Consumer only
- Each channel: ONE sender, ONE receiver
- MPSC/SPMC/MPMC will raise `ValueError`
2. **No close()** - Channels don't have close operation
- Use sentinel values for shutdown signaling
3. **Power-of-2 sizing** - Size rounded up
- `newChannel[int](10, SPSC)` creates 16-slot channel
4. **Async polling** - `send`/`recv` use exponential backoff polling
- Starts at 1ms, backs off to 100ms max
- Use `trySend`/`tryReceive` for zero-latency
## Development
### Testing
```bash
nim c -r tests/unit/test_channel.nim # Basic tests
nim c -r tests/unit/test_basic.nim # Version check
```
### Benchmarking
```bash
nimble bench # Run all benchmarks
```
### Code Quality
```bash
nimble fmt # Format code
nimble lint # Static analysis
nimble ci # Full CI checks
```
## Internal/Experimental Code
This repository contains experimental implementations of:
- TaskGroups (structured concurrency)
- Actors (with supervision)
- Streams (backpressure-aware)
- Work-stealing scheduler
- NUMA optimizations
**These are NOT production-ready** and not exported in the public API. They exist as research code for future releases. See internal modules in `src/nimsync/` if interested.
## Roadmap
- ✅ **v1.0.0**: Production SPSC channels (DONE!)
- **v1.1.0**: MPSC channels + TaskGroup fixes
- **v1.2.0**: Production-ready Streams
- **v2.0.0**: Full async runtime with actors
## Known Issues
See [GitHub Issues](.github/) for experimental features and known limitations:
- **Async wrappers use polling** - exponential backoff (1ms-100ms), use `trySend`/`tryReceive` for zero-latency
- **TaskGroup has bugs** - nested async macros fail (not exported) - [See issue template](.github/ISSUE_TASKGROUP_BUG.md)
- **MPSC not implemented** - multi-producer channels needed for actors - [See issue template](.github/ISSUE_MPSC_CHANNELS.md)
- **NUMA untested** - cross-socket performance unknown - [See issue template](.github/ISSUE_NUMA_VALIDATION.md)
**These are documented limitations, not intentional behavior.** Contributions to fix welcome!
## Contributing
Contributions welcome! Priority areas:
1. Fix TaskGroup nested async bug (blocking v0.3.0) - [Details](.github/ISSUE_TASKGROUP_BUG.md)
2. Implement MPSC channels (enables actors) - [Details](.github/ISSUE_MPSC_CHANNELS.md)
3. Validate NUMA performance - [Details](.github/ISSUE_NUMA_VALIDATION.md)
4. Cross-platform support (macOS/Windows)
See [issue templates](.github/) for detailed specifications and acceptance criteria.
## License
MIT License - see LICENSE for details.
---
**Status**: Production-ready SPSC channels with comprehensive validation. Other features (TaskGroup, MPSC, actors) are experimental - see [GitHub Issues](.github/) for contributor opportunities.
---
## Disclaimer
**nimsync v1.0.0 is production-ready for SPSC channels.**
✅ **SPSC channels verified** - 615M ops/sec peak, 31ns P99 latency, 7-benchmark suite validation
⚠️ **Experimental features** - TaskGroup, MPSC, actors not yet production-ready ([help wanted](.github/))
We document performance honestly. We benchmark rigorously. We're transparent about limitations.
**Open source async runtime built with Nim.** Contributions welcome - see issues for high-impact areas.