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 as IO::TimeoutError

Install

Install CZMQ on your system:

# Debian/Ubuntu
sudo apt install libczmq-dev

# macOS
brew install czmq

Then add the gem:

gem install cztop
# or in Gemfile
gem 'cztop'

Learning ZeroMQ

New to ZeroMQ? See ZGUIDE_SUMMARY.md — a ~30 min read covering all major patterns with working CZTop code examples.

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"]
end

Pub / 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"]
end

Push / 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"]
end

Socket 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

License

ISC