cztop 1.3.1 → 2.0.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1347b002694da386afc7249ac227de7ee7f1224bb140564334b20d646336e73a
-  data.tar.gz: faa02a6ba73af47cbff6af9664562e41d359ba4f13eb5813d6e1e5fc992b6aa8
+  metadata.gz: 3381b5cf1edd7c878bb5c26ccc16bf096a354cfab0724a8da61e7f4ce3146272
+  data.tar.gz: c6081e0b22ee66190b3d34eb9d4d6a2d5ecfda537e8cdbfc223cfd23d2b56e9f
 SHA512:
-  metadata.gz: fd22665b89635d5f5a6bbd8326a1de9c13f77a39a253a07316089d9124ec18dadebc67f86b5ec471cc3e09cb0eb6c32d027ad523573fc2b8e502c37b05119cc2
-  data.tar.gz: 1de1565a9d4656e9887958befb29ea0cad66ad90f30d84244f3f60bbcc7069a0cfc20bb1be1c8ff06db34e02546ca9ff8349c01689faa1725e6f8cb069e846db
+  metadata.gz: 8142a5ff3b45d88a3ebfc35b3a002dfb8b9be5937f0c37e1779530229d959b0457a1dfd49c062550b2c46d9389e5c3937272e979e5b703d09f68ed4732925201
+  data.tar.gz: 8591012e556649e6397c16a871f8f892a8b111ec06339e3271d03fd5eca187268363258429a949eb1d03c8245907cfbf30ae00662d9168f47e28aea14592094f

data/CHANGES.md

@@ -1,3 +1,113 @@
+2.0.0.rc2
+-----
+
+### Breaking changes
+
+* **Removed `Socket.new_by_type` factory method** — use type-specific constructors
+  instead (e.g. `Socket::REQ.new`, `Socket::PUB.new`)
+* **`linger` now defaults to 0** on all socket constructors — ZMQ's default of
+  infinite (-1) caused `#close` to block when unsent messages remained. Pass
+  `linger:` to override (e.g. `Socket::REQ.new(endpoint, linger: 1)`)
+
+2.0.0.rc1
+-----
+
+### Breaking changes
+
+* **Removed classes:** Actor, Authenticator, Beacon, Certificate, CertStore, Config,
+  Frame, Message, Metadata, Monitor, Poller, Proxy, Z85, ZAP
+* **Removed modules:** SendReceiveMethods, PolymorphicZsockMethods
+* **Removed socket types (draft API dropped):** SERVER, CLIENT, RADIO, DISH,
+  GATHER, SCATTER
+* **Removed CURVE/PLAIN/GSSAPI security API:**
+    - `Socket#CURVE_server!`, `Socket#CURVE_client!`
+    - CURVE option methods (`#CURVE_server?`, `#CURVE_serverkey`,
+      `#CURVE_secretkey`, `#CURVE_publickey`, etc.)
+    - PLAIN option methods (`#PLAIN_server?`, `#PLAIN_username`,
+      `#PLAIN_password`, etc.)
+    - `#mechanism`, `#zap_domain`
+* **Send/receive API changed:**
+    - `#receive` now returns `Array<String>` (was `CZTop::Message`)
+    - `#<<` accepts `String` or `Array<String>` directly (was `Message.coerce`)
+    - `#send` is the primary method; `#<<` is an alias (note: `#send` shadows
+      `Object#send`; use `__send__` for Ruby dispatch)
+    - `SendReceiveMethods` split into `Socket::Readable`, `Socket::Writable`, and
+      `Socket::FdWait` mixins; socket types include only what they need
+      (e.g. PUB includes only Writable, SUB only Readable)
+* **Time-based options now use seconds** (was milliseconds) — applies to
+    `#recv_timeout`, `#send_timeout`, `#linger`, `#heartbeat_ivl`, `#heartbeat_ttl`,
+    `#heartbeat_timeout`, `#reconnect_ivl`
+* **Sentinel values changed from -1 to nil:**
+    - `#recv_timeout` / `#send_timeout` — returns/accepts `nil` instead
+      of `-1` for "no timeout"
+    - `#linger` — `nil` instead of `-1` for "wait indefinitely"
+    - `#heartbeat_timeout` — `nil` instead of `-1` for "use IVL"
+    - `#reconnect_ivl` — `nil` instead of `-1` for "disabled"
+* **`Socket::SUB#initialize` subscription is now a `prefix:` kwarg** — was a
+    positional parameter; defaults to `EVERYTHING` (`''`), pass `prefix: nil` to
+    skip subscribing
+* **`#set_unbounded` moved from PolymorphicZsockMethods to Socket**
+* **`OptionsAccessor` removed** — all option methods now live directly on
+  `Socket` (e.g. `socket.sndhwm` instead of `socket.options.sndhwm`)
+* **`#rcvtimeo` / `#sndtimeo` removed** — use `#recv_timeout` / `#send_timeout`
+  (aliased as `#read_timeout` / `#write_timeout`). `nil` = no timeout
+  (block forever), `0` = nonblocking, positive = timeout in seconds.
+* **Fuzzy `#[]` / `#[]=` accessors removed**
+* **`czmq-ffi-gen` gem dependency removed** — replaced with handcrafted FFI
+  bindings in `lib/cztop/ffi.rb`
+* **Minimum Ruby version raised to 3.3**
+
+### New features
+
+* **`CZTop::Monitor`** — socket event monitoring via CZMQ's zmonitor actor;
+  detects CONNECTED, LISTENING, ACCEPTED, DISCONNECTED, and other ZMQ events.
+  Returns `Monitor::Event` value objects (`Data.define(:name, :endpoint, :peer_address)`)
+* **`Cztop` module alias** — `Cztop = CZTop` for conventional Ruby naming;
+  both `Cztop::Socket::REQ` and `CZTop::Socket::REQ` work
+* **`.bind` and `.connect` class methods** on all socket types —
+  `REP.bind(endpoint)` and `REQ.connect(endpoint)` as shorthand for
+  `new(nil).tap { |s| s.bind(endpoint) }`; passes through `curve:`,
+  `prefix:` (SUB), and other kwargs
+* **CURVE encryption** with ergonomic `curve:` kwarg on all socket constructors:
+    - `CZTop::CURVE.keypair` — generate keypairs (32-byte binary)
+    - `CZTop::CURVE.public_key(secret_key)` — derive public from secret
+    - `CZTop::CURVE.z85_encode` / `.z85_decode` — Z85 utility for interop
+    - `CZTop::CURVE::Auth` — in-memory ZAP handler (no filesystem, no zauth actor)
+    - Server: `CZTop::Socket::REP.new(endpoint, curve: { secret_key: sk })`
+    - Client: `CZTop::Socket::REQ.new(endpoint, curve: { secret_key: sk, server_key: pk })`
+* **`@`/`>` endpoint prefix convention** supported on all socket constructors
+  (e.g. `PAIR.new("@inproc://ep")` to bind, `PAIR.new(">inproc://ep")` to connect)
+* **New socket options:**
+    - `#reconnect_ivl_max` — max reconnect backoff interval (exponential backoff)
+    - `#max_msg_size` — max inbound message size (DoS protection)
+    - `#immediate?` / `#immediate=` — queue only for completed connections
+    - `#conflate?` / `#conflate=` — keep only last message (last-value-cache)
+    - `#tcp_keepalive` / `#tcp_keepalive_idle` / `#tcp_keepalive_cnt` /
+      `#tcp_keepalive_intvl` — TCP keepalive tuning
+
+### Other changes
+
+* **FFI bindings for zactor, zstr, zsock_wait** — foundational bindings for
+  CZMQ actor-based APIs (used by Monitor, extensible for future actors)
+* replace old examples with numbered `examples/zguide/` pattern files
+  (01–12: req/rep, pub/sub, pipeline, lazy pirate, heartbeat, LVC, clone,
+  majordomo, titanic, binary star, freelance)
+* expand ZGUIDE_SUMMARY.md to ~30 min read with working code excerpts,
+  threading/concurrency guidance, and common mistakes section
+* replace RSpec with Minitest
+* replace `perf/` with `bench/` using benchmark-ips
+* add per-socket-type integration test files for all 13 types
+* add socket combination tests (ROUTER+REQ, ROUTER+ROUTER, pipeline, XPUB+multi SUB)
+* add HWM mute state tests (PUSH/PULL blocking, PUB/SUB dropping, ROUTER mandatory)
+* add REQ/REP reconnection tests (TCP restart, stuck-state demonstration)
+* add STREAM ↔ raw TCP integration tests
+* add CURVE throughput benchmark (`bench/threads/curve_throughput.rb`)
+* add Shannon entropy system tests for CURVE (`test/system/`)
+* split socket creation from connect/bind to support pre-connect option setting
+* tune FD_TIMEOUT (500ms → 250ms) and JIFFY (15ms → 1ms) for better responsiveness
+* fix zmq_errno race condition in `#raise_zmq_err`
+* move CZMQ signal handler disabling into `lib/cztop/ffi.rb`
+
 1.3.2 (1/3/2025)
 -----
 * add 'benchmark' dependency for specs

data/CLAUDE.md

@@ -0,0 +1,39 @@
+# CZTop
+
+Ruby FFI binding for CZMQ/ZMQ. Version 2.0.0.pre1. Requires Ruby >= 3.3.
+
+## Architecture
+
+- `lib/cztop/socket.rb` — Socket base class (connect, bind, etc.)
+- `lib/cztop/socket/fd_wait.rb` — `FdWait` mixin: FD polling infrastructure (`FD_TIMEOUT`, `JIFFY`, `#wait_for_fd_signal`, `#wait_for_socket_state`)
+- `lib/cztop/socket/readable.rb` — `Readable` mixin: `#receive` → `Array<String>`, `#wait_readable`, `#read_timeout`
+- `lib/cztop/socket/writable.rb` — `Writable` mixin: `#send` accepts `String`/`Array<String>`, `#<<`, `#wait_writable`, `#write_timeout`
+- `lib/cztop/socket/types.rb` — `Types` constants + `TypeNames`
+- `lib/cztop/socket/{req,rep,dealer,router,pub,sub,xpub,xsub,push,pull,pair,stream}.rb` — individual socket types
+- `lib/cztop/ffi.rb` — FFI bindings (zsock, zmsg, zframe, zstr) + CZMQ signal handler disabling
+- `bench/` — benchmark-ips scripts (async/threads × throughput/latency)
+
+### ZMQ FD polling
+
+ZMQ uses a single edge-triggered FD for both read/write signaling. `#wait_for_socket_state`
+checks socket readiness first (fast path via `#readable?`/`#writable?`), then polls the FD.
+
+- `FD_TIMEOUT` (250ms) — max time in `IO#wait_readable` per loop iteration; safety net for missed edges
+- `JIFFY` (1ms) — sleep after false wakeup (FD signals but socket not ready)
+- Edge misses are rare (~0.2% of calls in ipc/tcp req/rep), never in inproc throughput
+- `IO#wait_readable` is interruptible by signals — Ctrl-C works immediately
+- `__send__` used instead of `send` to avoid clash with ZMQ `#send` method
+- Socket types include only the mixins they need (e.g. PUB includes only Writable, SUB only Readable)
+
+### Tuning rationale
+
+- JIFFY 15ms→1ms: each edge miss stalls for full JIFFY duration; 1ms reduces impact 15x
+- FD_TIMEOUT 500ms→250ms: halves worst-case stall; no measurable perf impact since FD signals correctly 99.8% of the time
+- Measured with `bench/jiffy_sweep.rb`, `bench/fd_timeout_sweep.rb`, `bench/edge_miss_count.rb`
+
+## Benchmarking
+
+- Uses benchmark-ips with `warmup: 1, time: 3`
+- Run benchmarks sequentially to reduce variance
+- For parameter sweeps: test multiple values in a single script with 3 runs each, report median
+- Sister project **rbnng** (`/home/roadster/dev/oss/rbnng`) has identical bench structure for comparison

data/Gemfile

@@ -1,10 +1,6 @@
 source 'https://rubygems.org'
 gemspec
 
-# useful when working on czmq-ffi-gen in parallel
-# gem "czmq-ffi-gen", path: "../czmq-ffi-gen"
-
 group :development do
-  gem 'codecov', require: false
   gem 'simplecov', require: false
 end

data/README.md

@@ -1,224 +1,139 @@
-![Specs status](https://github.com/paddor/cztop/workflows/STABLE%20API/badge.svg)
-![Specs status](https://github.com/paddor/cztop/workflows/DRAFT%20API%20on%20Ruby%203.3/badge.svg)
-![Specs status](https://github.com/paddor/cztop/workflows/DRAFT%20API%20on%20Ruby%203.4/badge.svg)
-[![codecov](https://codecov.io/gh/paddor/cztop/branch/master/graph/badge.svg?token=TnjOba97R7)](https://codecov.io/gh/paddor/cztop)
-
 # CZTop
 
-CZTop is a CZMQ binding for Ruby. It is based on
-[czmq-ffi-gen](https://github.com/paddor/czmq-ffi-gen), the generated low-level
-FFI binding of [CZMQ](https://github.com/zeromq/czmq) and has a focus on being
-easy to use for Rubyists (POLS) and providing first class support for security
-mechanisms (like CURVE).
-
+[![CI](https://github.com/paddor/cztop/actions/workflows/ci.yml/badge.svg)](https://github.com/paddor/cztop/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/cztop?color=e9573f)](https://rubygems.org/gems/cztop)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
+[![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%203.3-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org)
 
-## Example with Async
+Ruby FFI binding for [CZMQ](http://czmq.zeromq.org/) / [ZeroMQ](https://zeromq.org/) — high-performance asynchronous messaging for distributed systems.
 
-See [this example](https://github.com/paddor/cztop/blob/master/examples/async.rb):
-
-```ruby
-#! /usr/bin/env ruby
+> **353k msg/s** inproc throughput | **49 µs** fiber roundtrip latency | nonblock fast path
 
-require 'bundler/inline'
+---
 
-gemfile do
-  source 'https://rubygems.org'
-  gem 'cztop', path: '../../'
-  gem 'async'
-end
+## Highlights
 
-ENDPOINT = 'inproc://req_rep_example'
-# ENDPOINT = 'ipc:///tmp/req_rep_example0'
-# ENDPOINT = 'tcp://localhost:5556'
+- **All socket types** — req/rep, pub/sub, push/pull, dealer/router, xpub/xsub, pair, stream
+- **Async-first** — first-class [async](https://github.com/socketry/async) fiber support, also works with plain threads
+- **Ruby-idiomatic API** — messages as `Array<String>`, errors as exceptions, timeouts as `IO::TimeoutError`
 
-Async do |task|
-  rep_task = task.async do |t|
-    socket = CZTop::Socket::REP.new ENDPOINT
-
-    loop do
-      msg = socket.receive
-      puts "<<< #{msg.to_a.inspect}"
-      socket << msg.to_a.map(&:upcase)
-    end
-  ensure
-    puts "REP done."
-  end
+## Install
 
-  task.async do
-    socket = CZTop::Socket::REQ.new ENDPOINT
+Install CZMQ on your system:
 
-    10.times do |i|
-      socket << "foobar ##{i}"
-      msg = socket.receive
-      puts ">>> #{msg.to_a.inspect}"
-    end
+```sh
+# Debian/Ubuntu
+sudo apt install libczmq-dev
 
-    puts "REQ done."
-    rep_task.stop
-  end
-end
+# macOS
+brew install czmq
 ```
 
+Then add the gem:
 
-Output:
+```sh
+gem install cztop
+# or in Gemfile
+gem 'cztop'
 ```
-$ cd examples
-$ time ./async.rb
-<<< ["foobar #0"]
->>> ["FOOBAR #0"]
-<<< ["foobar #1"]
->>> ["FOOBAR #1"]
-<<< ["foobar #2"]
->>> ["FOOBAR #2"]
-<<< ["foobar #3"]
->>> ["FOOBAR #3"]
-<<< ["foobar #4"]
->>> ["FOOBAR #4"]
-<<< ["foobar #5"]
->>> ["FOOBAR #5"]
-<<< ["foobar #6"]
->>> ["FOOBAR #6"]
-<<< ["foobar #7"]
->>> ["FOOBAR #7"]
-<<< ["foobar #8"]
->>> ["FOOBAR #8"]
-<<< ["foobar #9"]
->>> ["FOOBAR #9"]
-REQ done.
-REP done.
-
-________________________________________________________
-Executed in  401.51 millis    fish           external
-   usr time  308.44 millis  605.00 micros  307.83 millis
-   sys time   40.08 millis  278.00 micros   39.81 millis
 
-```
+## Learning ZeroMQ
 
-A slightly more complex version (more sockets) is [here](https://github.com/paddor/cztop/blob/master/examples/massive_async.rb).
+New to ZeroMQ? See [ZGUIDE_SUMMARY.md](ZGUIDE_SUMMARY.md) — a ~30 min read covering all major patterns with working CZTop code examples.
 
-## Overview
+## Quick Start
 
-### Features
+### Request / Reply
 
-* Ruby idiomatic API
-* compatible with Fiber Scheduler (only on Ruby >= 3.2)
-* errors as exceptions
-* CURVE security
-* supports CZMQ DRAFT API
-* extensive spec coverage
+```ruby
+require 'cztop'
+require 'async'
 
-## Requirements
+Async do |task|
+  rep = CZTop::Socket::REP.new('inproc://example')
+  req = CZTop::Socket::REQ.new('inproc://example')
 
+  task.async do
+    msg = rep.receive
+    rep << msg.map(&:upcase)
+  end
 
-* CZMQ >= 4.2
-* ZMQ >= 4.3
+  req << 'hello'
+  puts req.receive.inspect  # => ["HELLO"]
+end
+```
 
+### Pub / Sub
 
-On Ubuntu 20.04+:
+```ruby
+Async do |task|
+  pub = CZTop::Socket::PUB.new('inproc://pubsub')
+  sub = CZTop::Socket::SUB.new('inproc://pubsub')
+  sub.subscribe('')  # subscribe to all
 
-    $ sudo apt install libczmq-dev
+  sleep 0.01  # allow connection to establish
 
-On macOS using Homebrew, run:
+  task.async { pub << 'news flash' }
+  puts sub.receive.inspect  # => ["news flash"]
+end
+```
 
-    $ brew install czmq
+### Push / Pull (Pipeline)
 
-### Supported Rubies
+```ruby
+Async do
+  push = CZTop::Socket::PUSH.new('inproc://pipeline')
+  pull = CZTop::Socket::PULL.new('inproc://pipeline')
 
-At least:
+  push << 'work item'
+  puts pull.receive.inspect  # => ["work item"]
+end
+```
 
-* Ruby 3.0, 3.1, 3.2, 3.3
+## Socket Types
 
-## Installation
+| Pattern | Classes | Direction |
+|---------|---------|-----------|
+| Request/Reply | `REQ`, `REP` | bidirectional |
+| Publish/Subscribe | `PUB`, `SUB`, `XPUB`, `XSUB` | unidirectional |
+| Pipeline | `PUSH`, `PULL` | unidirectional |
+| Routing | `DEALER`, `ROUTER` | bidirectional |
+| Exclusive pair | `PAIR` | bidirectional |
+| Raw TCP | `STREAM` | bidirectional |
 
-To use this gem, add this line to your application's Gemfile:
+All classes live under `CZTop::Socket::`.
 
-```ruby
-gem 'cztop'
-```
+## Performance
 
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install cztop
-
-### Class Hierarchy
-
-Here's an overview of the core classes:
-
-* [CZTop](http://www.rubydoc.info/gems/cztop/CZTop)
-  * [Actor](http://www.rubydoc.info/gems/cztop/CZTop)
-  * [Authenticator](http://www.rubydoc.info/gems/cztop/CZTop/Authenticator)
-  * [Beacon](http://www.rubydoc.info/gems/cztop/CZTop/Beacon)
-  * [Certificate](http://www.rubydoc.info/gems/cztop/CZTop/Certificate)
-  * [CertStore](http://www.rubydoc.info/gems/cztop/CZTop/CertStore)
-  * [Config](http://www.rubydoc.info/gems/cztop/CZTop/Config)
-  * [Frame](http://www.rubydoc.info/gems/cztop/CZTop/Frame)
-  * [Message](http://www.rubydoc.info/gems/cztop/CZTop/Message)
-  * [Monitor](http://www.rubydoc.info/gems/cztop/CZTop/Monitor)
-  * [Metadata](http://www.rubydoc.info/gems/cztop/CZTop/Metadata)
-  * [Proxy](http://www.rubydoc.info/gems/cztop/CZTop/Proxy)
-  * [Poller](http://www.rubydoc.info/gems/cztop/CZTop/Poller) (based on `zmq_poller_*()` functions)
-    * [Aggregated](http://www.rubydoc.info/gems/cztop/CZTop/Poller/Aggregated)
-    * [ZPoller](http://www.rubydoc.info/gems/cztop/CZTop/Poller/ZPoller)
-  * [Socket](http://www.rubydoc.info/gems/cztop/CZTop/Socket)
-    * [REQ](http://www.rubydoc.info/gems/cztop/CZTop/Socket/REQ) < Socket
-    * [REP](http://www.rubydoc.info/gems/cztop/CZTop/Socket/REP) < Socket
-    * [ROUTER](http://www.rubydoc.info/gems/cztop/CZTop/Socket/ROUTER) < Socket
-    * [DEALER](http://www.rubydoc.info/gems/cztop/CZTop/Socket/DEALER) < Socket
-    * [PUSH](http://www.rubydoc.info/gems/cztop/CZTop/Socket/PUSH) < Socket
-    * [PULL](http://www.rubydoc.info/gems/cztop/CZTop/Socket/PULL) < Socket
-    * [PUB](http://www.rubydoc.info/gems/cztop/CZTop/Socket/PUB) < Socket
-    * [SUB](http://www.rubydoc.info/gems/cztop/CZTop/Socket/SUB) < Socket
-    * [XPUB](http://www.rubydoc.info/gems/cztop/CZTop/Socket/XPUB) < Socket
-    * [XSUB](http://www.rubydoc.info/gems/cztop/CZTop/Socket/XSUB) < Socket
-    * [PAIR](http://www.rubydoc.info/gems/cztop/CZTop/Socket/PAIR) < Socket
-    * [STREAM](http://www.rubydoc.info/gems/cztop/CZTop/Socket/STREAM) < Socket
-    * [CLIENT](http://www.rubydoc.info/gems/cztop/CZTop/Socket/CLIENT) < Socket
-    * [SERVER](http://www.rubydoc.info/gems/cztop/CZTop/Socket/SERVER) < Socket
-    * [RADIO](http://www.rubydoc.info/gems/cztop/CZTop/Socket/RADIO) < Socket
-    * [DISH](http://www.rubydoc.info/gems/cztop/CZTop/Socket/DISH) < Socket
-    * [SCATTER](http://www.rubydoc.info/gems/cztop/CZTop/Socket/SCATTER) < Socket
-    * [GATHER](http://www.rubydoc.info/gems/cztop/CZTop/Socket/GATHER) < Socket
-  * [Z85](http://www.rubydoc.info/gems/cztop/CZTop/Z85)
-    * [Padded](http://www.rubydoc.info/gems/cztop/CZTop/Z85/Padded) < Z85
-    * [Pipe](http://www.rubydoc.info/gems/cztop/CZTop/Z85/Pipe)
-  * [ZAP](http://www.rubydoc.info/gems/cztop/CZTop/ZAP)
-
-More information in the [API documentation](http://www.rubydoc.info/github/paddor/cztop).
-
-## Documentation
-
-The API should be fairly straight-forward to anyone who is familiar with CZMQ
-and Ruby.  The following API documentation is currently available:
-
-* [YARD API documentation](http://www.rubydoc.info/gems/cztop) (release)
-
-Feel free to start a [wiki](https://github.com/paddor/cztop/wiki) page.
+Benchmarked with benchmark-ips on Linux x86_64 (CZMQ 4.2.1, ZMQ 4.3.5, Ruby 4.0.1 +YJIT):
 
-## Performance
+#### Throughput (push/pull)
 
-CZTop is just a convenience layer on top of the thin czmq-ffi-gen library.
+| | inproc | ipc | tcp |
+|---|--------|-----|-----|
+| **Async** | 284k/s | 17k/s | 14k/s |
+| **Threads** | 353k/s | 25k/s | 21k/s |
 
-Make sure to check out the
-[perf](https://github.com/paddor/cztop/blob/master/perf) directory for latency
-and throughput measurement scripts.
+#### Latency (req/rep roundtrip)
 
-## Usage
+| | inproc | ipc | tcp |
+|---|--------|-----|-----|
+| **Async** | 49 µs | 100 µs | 107 µs |
+| **Threads** | 113 µs | 154 µs | 168 µs |
 
-See the [examples](https://github.com/paddor/cztop/blob/master/examples) directory for some examples.
+Async fibers deliver 2.3x lower inproc latency thanks to cheap context switching. See [`bench/`](bench/) for full results and scripts.
 
+## API Reference
 
-## Contributing
+Full [API documentation](http://www.rubydoc.info/gems/cztop).
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/paddor/cztop.
+## Development
 
-To run the tests before/after you made any changes to the source and have
-created a test case for it, use `rake spec`.
+```sh
+bundle install
+bundle exec rake
+```
 
 ## License
 
-The gem is available as open source under the terms of the [ISC License](http://opensource.org/licenses/ISC).
-See the [LICENSE](https://github.com/paddor/cztop/blob/master/LICENSE) file.
+[ISC](LICENSE)