{"id":32713413,"url":"https://github.com/codenimja/nimsync","last_synced_at":"2025-11-02T11:01:47.745Z","repository":{"id":321303618,"uuid":"1085324472","full_name":"codenimja/nimsync","owner":"codenimja","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-28T23:47:44.000Z","size":4181,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-29T00:27:07.512Z","etag":null,"topics":["actors","async","async-runtime","channels","concurrency","high-performance","lock-free","nim","structured-concurrency"],"latest_commit_sha":null,"homepage":null,"language":"Nim","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codenimja.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-28T22:11:58.000Z","updated_at":"2025-10-28T23:48:32.000Z","dependencies_parsed_at":"2025-10-29T00:27:19.436Z","dependency_job_id":null,"html_url":"https://github.com/codenimja/nimsync","commit_stats":null,"previous_names":["b0onzy/nimsync"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/codenimja/nimsync","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenimja%2Fnimsync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenimja%2Fnimsync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenimja%2Fnimsync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenimja%2Fnimsync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codenimja","download_url":"https://codeload.github.com/codenimja/nimsync/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenimja%2Fnimsync/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":282271384,"owners_count":26642101,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-02T02:00:06.609Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actors","async","async-runtime","channels","concurrency","high-performance","lock-free","nim","structured-concurrency"],"created_at":"2025-11-02T11:00:37.801Z","updated_at":"2025-11-02T11:01:47.739Z","avatar_url":"https://github.com/codenimja.png","language":"Nim","readme":"# nimsync\n\n[![CI](https://github.com/codenimja/nimsync/actions/workflows/ci.yml/badge.svg)](https://github.com/codenimja/nimsync/actions/workflows/ci.yml)\n[![Benchmark](https://github.com/codenimja/nimsync/actions/workflows/benchmark.yml/badge.svg)](https://github.com/codenimja/nimsync/actions/workflows/benchmark.yml)\n[![Nimble](https://img.shields.io/badge/nimble-v1.0.0-orange.svg)](https://nimble.directory/pkg/nimsync)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Nim](https://img.shields.io/badge/nim-2.0.0%2B-yellow.svg?style=flat\u0026logo=nim)](https://nim-lang.org)\n![Peak](https://img.shields.io/badge/peak-615M_ops/sec-success)\n![P99](https://img.shields.io/badge/p99_latency-31ns-blue)\n![Contention](https://img.shields.io/badge/contention-0%25-brightgreen)\n\n**Lock-free SPSC channels for Nim with production-grade performance validation**\n\nnimsync 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.\n\n## Features\n\n- **High throughput**: 615M ops/sec (raw), 512K ops/sec (async) - [See all 7 benchmarks](#performance)\n- **Production-validated**: Comprehensive benchmark suite (throughput, latency, burst, stress, sustained)\n- **Industry-standard testing**: Following Tokio, Go, Rust Criterion, LMAX Disruptor methodologies\n- Lock-free ring buffer with atomic operations\n- Zero GC pressure with ORC memory management\n- Cache-line aligned (64 bytes) to prevent false sharing\n- Power-of-2 sizing for efficient operations\n- Non-blocking `trySend`/`tryReceive`\n- Async `send`/`recv` wrappers for Chronos\n\n## Installation\n\n### Requirements\n- Nim 2.0.0+ (required)\n- Chronos 4.0.0+\n\n### Via Nimble\n```bash\nnimble install nimsync\n```\n\n### From Source\n```bash\ngit clone https://github.com/codenimja/nimsync.git\ncd nimsync\nnimble install\n```\n\n## Quick Start\n\n### Basic Usage\n```nim\nimport nimsync\n\n# Create SPSC channel with 16 slots\nlet chan = newChannel[int](16, ChannelMode.SPSC)\n\n# Non-blocking operations\nif chan.trySend(42):\n  echo \"Sent successfully\"\n\nvar value: int\nif chan.tryReceive(value):\n  echo \"Received: \", value\n```\n\n### Async Operations\n```nim\nimport nimsync\nimport chronos\n\nproc producer(ch: Channel[int]) {.async.} =\n  for i in 1..10:\n    await ch.send(i)\n\nproc consumer(ch: Channel[int]) {.async.} =\n  for i in 1..10:\n    let value = await ch.recv()\n    echo \"Received: \", value\n\nproc main() {.async.} =\n  let ch = newChannel[int](16, ChannelMode.SPSC)\n  await allFutures([producer(ch), consumer(ch)])\n\nwaitFor main()\n```\n\n## API Reference\n\n### Channel Creation\n```nim\nproc newChannel[T](size: int, mode: ChannelMode): Channel[T]\n```\nCreates a channel with specified size (rounded to next power of 2).\nOnly `ChannelMode.SPSC` is implemented.\n\n### Non-Blocking Operations\n```nim\nproc trySend[T](channel: Channel[T], value: T): bool\nproc tryReceive[T](channel: Channel[T], value: var T): bool\n```\nReturns `true` on success, `false` if channel is full/empty.\n**Use these for maximum performance** (sub-100ns operations).\n\n### Async Operations\n```nim\nproc send[T](channel: Channel[T], value: T): Future[void] {.async.}\nproc recv[T](channel: Channel[T]): Future[T] {.async.}\n```\nAsync wrappers using Chronos. **Note**: Uses 1ms polling internally.\n\n### Utilities\n```nim\nproc isEmpty[T](channel: Channel[T]): bool\nproc isFull[T](channel: Channel[T]): bool\n```\n## Performance\n\n### Comprehensive Benchmark Suite\n\nnimsync includes 7 official benchmarks following industry best practices:\n\n| Benchmark | Metric | Result | Industry Reference |\n|-----------|--------|--------|--------------------|\n| **Throughput** | Peak ops/sec | 615M | Go channels benchmarking |\n| **Latency** | p50/p99/p99.9 | 30ns/31ns/31ns | Tokio/Cassandra percentiles |\n| **Burst Load** | Stability | 300M ops/sec, 21% variance | Redis burst testing |\n| **Buffer Sizing** | Optimal size | 2048 slots, 559M ops/sec | LMAX Disruptor |\n| **Stress Test** | Contention | 0% at 500K ops | JMeter/Gatling |\n| **Sustained** | Long-duration | Stable over 10s | Cassandra/ScyllaDB |\n| **Async** | Overhead | 512K ops/sec | Standard async benchmarking |\n\n### Quick Run\n```bash\n# Run complete benchmark suite (~18 seconds)\n./tests/performance/run_all_benchmarks.sh\n\n# Run individual benchmarks\nnim c -d:danger --opt:speed --mm:orc tests/performance/benchmark_latency.nim\n./tests/performance/benchmark_latency\n```\n\n**Full Documentation**: See [`tests/performance/README.md`](tests/performance/README.md) for detailed explanations of each benchmark.\n```\n\n### Third-Party Verification\n\nWant to verify these claims yourself?\n\n- **Reproduction Guide**: See [BENCHMARKS.md](BENCHMARKS.md) and [tests/performance/README.md](tests/performance/README.md)\n- **CI Benchmarks**: Automatic benchmarks on every commit → [GitHub Actions](https://github.com/codenimja/nimsync/actions/workflows/benchmark.yml)\n- **Expected Range**: 20M-600M ops/sec depending on CPU, benchmark type, and system load\n\n## Limitations\n\n1. **SPSC Only** - Single Producer Single Consumer only\n   - Each channel: ONE sender, ONE receiver\n   - MPSC/SPMC/MPMC will raise `ValueError`\n\n2. **No close()** - Channels don't have close operation\n   - Use sentinel values for shutdown signaling\n\n3. **Power-of-2 sizing** - Size rounded up\n   - `newChannel[int](10, SPSC)` creates 16-slot channel\n\n4. **Async polling** - `send`/`recv` use exponential backoff polling\n   - Starts at 1ms, backs off to 100ms max\n   - Use `trySend`/`tryReceive` for zero-latency\n\n## Development\n\n### Testing\n```bash\nnim c -r tests/unit/test_channel.nim  # Basic tests\nnim c -r tests/unit/test_basic.nim    # Version check\n```\n\n### Benchmarking\n```bash\nnimble bench  # Run all benchmarks\n```\n\n### Code Quality\n```bash\nnimble fmt   # Format code\nnimble lint  # Static analysis\nnimble ci    # Full CI checks\n```\n\n## Internal/Experimental Code\n\nThis repository contains experimental implementations of:\n- TaskGroups (structured concurrency)\n- Actors (with supervision)\n- Streams (backpressure-aware)\n- Work-stealing scheduler\n- NUMA optimizations\n\n**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.\n\n## Roadmap\n\n- ✅ **v1.0.0**: Production SPSC channels (DONE!)\n- **v1.1.0**: MPSC channels + TaskGroup fixes\n- **v1.2.0**: Production-ready Streams\n- **v2.0.0**: Full async runtime with actors\n\n## Known Issues\n\nSee [GitHub Issues](.github/) for experimental features and known limitations:\n\n- **Async wrappers use polling** - exponential backoff (1ms-100ms), use `trySend`/`tryReceive` for zero-latency\n- **TaskGroup has bugs** - nested async macros fail (not exported) - [See issue template](.github/ISSUE_TASKGROUP_BUG.md)\n- **MPSC not implemented** - multi-producer channels needed for actors - [See issue template](.github/ISSUE_MPSC_CHANNELS.md)\n- **NUMA untested** - cross-socket performance unknown - [See issue template](.github/ISSUE_NUMA_VALIDATION.md)\n\n**These are documented limitations, not intentional behavior.** Contributions to fix welcome!\n\n## Contributing\n\nContributions welcome! Priority areas:\n1. Fix TaskGroup nested async bug (blocking v0.3.0) - [Details](.github/ISSUE_TASKGROUP_BUG.md)\n2. Implement MPSC channels (enables actors) - [Details](.github/ISSUE_MPSC_CHANNELS.md)\n3. Validate NUMA performance - [Details](.github/ISSUE_NUMA_VALIDATION.md)\n4. Cross-platform support (macOS/Windows)\n\nSee [issue templates](.github/) for detailed specifications and acceptance criteria.\n\n## License\n\nMIT License - see LICENSE for details.\n\n---\n\n**Status**: Production-ready SPSC channels with comprehensive validation. Other features (TaskGroup, MPSC, actors) are experimental - see [GitHub Issues](.github/) for contributor opportunities.\n\n---\n\n## Disclaimer\n\n**nimsync v1.0.0 is production-ready for SPSC channels.**\n\n✅ **SPSC channels verified** - 615M ops/sec peak, 31ns P99 latency, 7-benchmark suite validation  \n⚠️ **Experimental features** - TaskGroup, MPSC, actors not yet production-ready ([help wanted](.github/))\n\nWe document performance honestly. We benchmark rigorously. We're transparent about limitations.\n\n**Open source async runtime built with Nim.** Contributions welcome - see issues for high-impact areas.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodenimja%2Fnimsync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodenimja%2Fnimsync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodenimja%2Fnimsync/lists"}