CZTop
Ruby FFI binding for CZMQ / ZeroMQ — high-performance asynchronous messaging for distributed systems.
353k msg/s inproc throughput | 49 µs fiber roundtrip latency | nonblock fast path
Highlights
- All socket types — req/rep, pub/sub, push/pull, dealer/router, xpub/xsub, pair, stream
- Async-first — first-class async fiber support, also works with plain threads
-
Ruby-idiomatic API — messages as
Array<String>, errors as exceptions, timeouts asIO::TimeoutError
Install
Install CZMQ on your system:
# Debian/Ubuntu
sudo apt install libczmq-dev
# macOS
brew install czmqThen add the gem:
gem install cztop
# or in Gemfile
gem 'cztop'Quick Start
Request / Reply
require 'cztop'
require 'async'
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
req << 'hello'
puts req.receive.inspect # => ["HELLO"]
endPub / Sub
Async do |task|
pub = CZTop::Socket::PUB.new('inproc://pubsub')
sub = CZTop::Socket::SUB.new('inproc://pubsub')
sub.subscribe('') # subscribe to all
sleep 0.01 # allow connection to establish
task.async { pub << 'news flash' }
puts sub.receive.inspect # => ["news flash"]
endPush / Pull (Pipeline)
Async do
push = CZTop::Socket::PUSH.new('inproc://pipeline')
pull = CZTop::Socket::PULL.new('inproc://pipeline')
push << 'work item'
puts pull.receive.inspect # => ["work item"]
endSocket Types
| 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 |
All classes live under CZTop::Socket::.
Performance
Benchmarked with benchmark-ips on Linux x86_64 (CZMQ 4.2.1, ZMQ 4.3.5, Ruby 4.0.1 +YJIT):
Throughput (push/pull)
| inproc | ipc | tcp | |
|---|---|---|---|
| Async | 284k/s | 17k/s | 14k/s |
| Threads | 353k/s | 25k/s | 21k/s |
Latency (req/rep roundtrip)
| inproc | ipc | tcp | |
|---|---|---|---|
| Async | 49 µs | 100 µs | 107 µs |
| Threads | 113 µs | 154 µs | 168 µs |
Async fibers deliver 2.3x lower inproc latency thanks to cheap context switching. See bench/ for full results and scripts.
API Reference
Full API documentation.
Development
bundle install
bundle exec rake