Project

cztop

0.02
A long-lived project that still receives updates
cztoppaddor/cztopHomepageDocumentationSource CodeBug TrackerWiki
CZMQ binding with hardcoded FFI bindings, providing a Ruby-like API for ZMQ sockets
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Popularity
Downloads
282,913
Stars
39
Forks
11
Watchers
3
 Releases
Current version
2.0.4
Total releases
50
First release
2016-01-23
Latest release
2026-10-12
 Issues
Open Issues
0
Closed Issues
15
Total Issues
15
Issue Closure Rate
100%
 Pull Requests
Open Pull Requests
0
Closed Pull Requests
0
Merged Pull Requests
8
Pull Request Acceptance Rate
100%
 Development
Primary Language
Ruby
Licenses
ISC
Average date of last 50 commits
2026-04-28
Reverse Dependencies
5

 Dependencies

Development

async
>= 0
bundler
>= 0
minitest
>= 0
pry
>= 0
rake
>= 0
yard
>= 0
benchmark-ips
>= 0
minitest-mock
>= 0

Runtime

ffi
>= 0
 Project Readme

CZTop

CI Gem Version License: ISC Ruby

Ruby FFI binding for CZMQ and ZeroMQ, with support for threads, Fiber Scheduler, and CURVE encryption.

310k msg/s inproc throughput (64 B) | 61 µs Async roundtrip latency

Highlights

  • Socket types: REQ/REP, PUB/SUB, PUSH/PULL, DEALER/ROUTER, XPUB/XSUB, PAIR, STREAM
  • Fibers and threads: works with async and plain threads
  • Ruby 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 add it to your Gemfile:

gem 'cztop'

Learning ZeroMQ

New to ZeroMQ? See ZGUIDE_SUMMARY.md for messaging patterns and working CZTop examples.

Quick Start

REQ / REP

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 unidirectional
Subscription forwarding XPUB, XSUB bidirectional
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.6 +YJIT):

Throughput (PUSH/PULL, 64 B messages)

inproc ipc tcp
Async 278k/s 18.3k/s 15.8k/s
Threads 310k/s 18.3k/s 16.2k/s

Latency (REQ/REP roundtrip)

inproc ipc tcp
Async 60.7 µs 112.6 µs 127.8 µs
Threads 74.9 µs 109.2 µs 119.6 µs

See bench/README.md for full results, measurement details, and scripts.

API Reference

Full API documentation.

Development

bundle install
bundle exec rake

License

ISC