Name: cztop
Owner: Particle
Description: CZMQ binding for Ruby, based on the generated FFI binding
Forked from: paddor/cztop
Created: 2016-03-27 19:15:45.0
Updated: 2016-03-27 19:15:45.0
Pushed: 2018-01-03 18:22:15.0
Size: 454
Language: Ruby
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
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).
Why another CZMQ Ruby binding? Here is a list of existing projects I found and the issues with them, from my point of view:
Furthermore, I knew about the generated low-level Ruby FFI binding in the zeromq/czmq repository. I wanted to make use of it because I love that it's generated (and thus, most likely correct and up-to-date). Unfortunately, it was in pretty bad shape and missing a few CZMQ classes.
So I decided to improve the quality and usability of the binding and add the missing classes. The result is czmq-ffi-gen which provides a solid foundation for CZTop.
Here are some some of the goals I have/had in mind for this library:
Here's an overview of the core classes:
More information in the API documentation.
Socket#<<socket << "simple message"socket << ["multi", "frame", "message"]#x= methods instead of #set_x (e.g. socket options)#[] where it makes sense (e.g. on a Message, Config, or Certificate)Socket#CURVE_server!(cert) on the serverSocket#CURVE_client!(client_cert, server_cert) on the clientCZTop::Socket.new_by_type(:REP)#subscribe only exists on CZTop::Socket::SUB#routing_id and #routing_id= on the following classes:socket.options.heartbeat_ivl = 2000socket.options.heartbeat_timeout = 8000You'll need:
For security mechanisms like CURVE, you'll need:
To install on OSX using homebrew, run:
$ brew install libsodium
$ brew install zmq --with-libsodium
$ brew install czmq --HEAD
If you're running Linux, go check this page to get more help. Make sure to install CZMQ, not only ZMQ.
Warning: To make use of the full feature set of CZTop (including CLIENT/SERVER sockets and ZMTP 3.1 heartbeats), you'll need to install both ZMQ and CZMQ from master, like this:
# instead of the last two commands from above
$ brew install zmq --with-libsodium --HEAD
$ brew install czmq --HEAD
See next section.
When using ZMQ 4.1/4.0:
See .travis.yml for a list of Ruby versions against which CZTop is tested.
At the time of writing, these include:
To use this gem, add this line to your application's Gemfile:
'cztop'
And then execute:
$ bundle
Or install it yourself as:
$ gem install cztop
The API should be fairly straight-forward to anyone who is familiar with CZMQ and Ruby. The following API documentation is currently available:
Feel free to start a wiki page.
Performance should be pretty okay since this is based on czmq-ffi-gen, which is reasonably thin. CZTop is basically only a convenience layer on top, with some nice error checking. But hey, it's Ruby. Don't expect 5M messages per second with a latency of 3us.
The measured latency on my laptop ranges from ~20us to ~60us per message for 1kb messages, depending on whether transport is inproc, IPC, or TCP/IP.
Make sure you check out the perf directory for latency and throughput measurement scripts.
See the examples directory for some examples. Here's a very simple one:
sr/bin/env ruby
ire 'cztop'
eate and bind socket
et = CZTop::Socket::REP.new("ipc:///tmp/req_rep_example")
"<<< Socket bound to #{socket.last_endpoint.inspect}"
mply echo every message, with every frame String#upcase'd.
e msg = socket.receive
ts "<<< #{msg.to_a.inspect}"
cket << msg.to_a.map(&:upcase)
sr/bin/env ruby
ire 'cztop'
nnect
et = CZTop::Socket::REQ.new("ipc:///tmp/req_rep_example")
">>> Socket connected."
mple string
et << "foobar"
= socket.receive
">>> #{msg.to_a.inspect}"
lti frame message as array
et << %w[foo bar baz]
= socket.receive
">>> #{msg.to_a.inspect}"
nually instantiating a Message
= CZTop::Message.new("bla")
<< "another frame" # append a frame
et << msg
= socket.receive
">>> #{msg.to_a.inspect}"
is will send 20 additional messages:
$ ./req.rb 20
RGV.first
GV.first.to_i.times do
socket << ["fooooooooo", "baaaaaar"]
puts ">>> " + socket.receive.to_a.inspect
d
rep.rb & ./req.rb 3
35321
Socket connected.
Socket bound to "ipc:///tmp/req_rep_example"
["foobar"]
["FOOBAR"]
["foo", "bar", "baz"]
["FOO", "BAR", "BAZ"]
["bla", "another frame"]
["BLA", "ANOTHER FRAME"]
["fooooooooo", "baaaaaar"]
["FOOOOOOOOO", "BAAAAAAR"]
["fooooooooo", "baaaaaar"]
["FOOOOOOOOO", "BAAAAAAR"]
["fooooooooo", "baaaaaar"]
["FOOOOOOOOO", "BAAAAAAR"]
zcert_meta_unset() (zeromq/czmq#1246)attach_functionzproc(especially no zproc_has_curve())attach_function, attach zsys_has_curve() instead (under same name)zmq_poll()#add_reader, #add_writer, #wait behave the same)#readables and #writables which return arrays of socketsMessage#to_sz85encode and z85decode utilitiesZ85::PipeBug 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.
The gem is available as open source under the terms of the ISC License. See the LICENSE file.