CZTop
CZTop is a CZMQ binding for Ruby. It is based on czmq-ffi-gen, the generated low-level FFI binding of CZMQ and has a focus on being easy to use for Rubyists (POLS) and providing first class support for security mechanisms (like CURVE).
Example with Async
See this example:
#! /usr/bin/env ruby
require 'bundler/inline'
gemfile do
source 'https://rubygems.org'
gem 'cztop', path: '../../'
gem 'async'
end
ENDPOINT = 'inproc://req_rep_example'
# ENDPOINT = 'ipc:///tmp/req_rep_example0'
# ENDPOINT = 'tcp://localhost:5556'
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
task.async do
socket = CZTop::Socket::REQ.new ENDPOINT
10.times do |i|
socket << "foobar ##{i}"
msg = socket.receive
puts ">>> #{msg.to_a.inspect}"
end
puts "REQ done."
rep_task.stop
end
end
Output:
$ 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
A slightly more complex version (more sockets) is here.
Overview
Features
- Ruby idiomatic API
- Fiber Scheduler aware
- errors as exceptions
- CURVE security
- supports CZMQ DRAFT API
- extensive spec coverage
Requirements
- CZMQ >= 4.2
- ZMQ >= 4.3
On Ubuntu 20.04+:
$ sudo apt install libczmq-dev
On macOS using Homebrew, run:
$ brew install czmq
Supported Rubies
At least:
- Ruby 3.0, 3.1, 3.2, 3.3
Installation
To use this gem, add this line to your application's Gemfile:
gem 'cztop'
And then execute:
$ bundle
Or install it yourself as:
$ gem install cztop
Class Hierarchy
Here's an overview of the core classes:
- CZTop
- Actor
- Authenticator
- Beacon
- Certificate
- CertStore
- Config
- Frame
- Message
- Monitor
- Metadata
- Proxy
- Poller (based on
zmq_poller_*()
functions) - Aggregated
- ZPoller
- Socket
- REQ < Socket
- REP < Socket
- ROUTER < Socket
- DEALER < Socket
- PUSH < Socket
- PULL < Socket
- PUB < Socket
- SUB < Socket
- XPUB < Socket
- XSUB < Socket
- PAIR < Socket
- STREAM < Socket
- CLIENT < Socket
- SERVER < Socket
- RADIO < Socket
- DISH < Socket
- SCATTER < Socket
- GATHER < Socket
- Z85
- Padded < Z85
- Pipe
- ZAP
More information in the API documentation.
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 (release)
Feel free to start a wiki page.
Performance
CZTop is just a convenience layer on top of the thin czmq-ffi-gen library.
Make sure to check out the perf directory for latency and throughput measurement scripts.
Usage
See the examples directory for some examples.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/paddor/cztop.
To run the tests before/after you made any changes to the source and have
created a test case for it, use rake spec
.
License
The gem is available as open source under the terms of the ISC License. See the LICENSE file.