README.md in celluloid-zmq-0.9.0 vs README.md in celluloid-zmq-0.10.0
- old
+ new
@@ -1,56 +1,102 @@
-Celluloid::ZMQ
-==============
+
+=================
+[](http://travis-ci.org/celluloid/celluloid-zmq)
-This gem uses the ffi-rzmq library to provide Celluloid actors that can
-interact with 0MQ sockets.
+Celluloid::ZMQ provides Celluloid actors that can interact with [0MQ sockets][0mq].
+Underneath, it's built on the [ffi-rzmq][ffi-rzmq] library. Celluloid::ZMQ was
+primarily created for the purpose of writing [DCell][dcell], distributed Celluloid
+over 0MQ, so before you go building your own distributed Celluloid systems with
+Celluloid::ZMQ, be sure to give DCell a look and decide if it fits your purposes.
-Celluloid::ZMQ provides two methods for multiplexing 0MQ sockets with
-receiving messages over Celluloid's actor protocol:
+[0mq]: http://www.zeromq.org/
+[ffi-rzmq]: https://github.com/chuckremes/ffi-rzmq
+[dcell]: https://github.com/celluloid/dcell
-* Celluloid::ZMQ#wait_readable(socket): wait until a message is available to
- read from the given 0MQ socket
-* Celluloid::ZMQ#wait_writeable(socket): waits until there's space in the
- given socket's message buffer to send another message
+It provides different `Celluloid::ZMQ::Socket` classes which can be initialized
+then sent `bind` or `connect`. Once bound or connected, the socket can
+`read` or `send` depending on whether it's readable or writable.
-Example Usage:
+## Supported Platforms
- require 'celluloid-zmq'
+Celluloid::IO requires Ruby 1.9 support on all Ruby VMs. You will also need
+the ZeroMQ library installed as it's accessed via FFI.
- ZMQ_CONTEXT = ZMQ::Context.new(1)
+Supported VMs are Ruby 1.9.3, JRuby 1.6, and Rubinius 2.0.
- class MyZmqCell
- include Celluloid::ZMQ
+To use JRuby in 1.9 mode, you'll need to pass the "--1.9" command line option
+to the JRuby executable, or set the "JRUBY_OPTS=--1.9" environment variable.
- def initialize(addr)
- @socket = ZMQ_CONTEXT.socket(ZMQ::PUSH)
+## 0MQ Socket Types
- unless ZMQ::Util.resultcode_ok? @socket.connect addr
- @socket.close
- raise "error connecting to #{addr}: #{ZMQ::Util.error_string}"
- end
- end
+The following 0MQ socket types are supported (see [sockets.rb][socketsrb] for more info)
- def write(message)
- wait_writeable @socket
- unless ZMQ::Util.resultcode_ok? @socket.send_string message
- raise "error sending 0MQ message: #{ZMQ::Util.error_string}"
- end
- end
+[socketsrb]: https://github.com/celluloid/celluloid-zmq/blob/master/lib/celluloid/zmq/sockets.rb
- def read
- wait_readable @socket
- message = ''
+* ReqSocket / RepSocket
+* PushSocket / PullSocket
+* PubSocket / SubSocket
- rc = @socket.recv_string message
- if ZMQ::Util.resultcode_ok? rc
- handle_message message
- else
- raise "error receiving ZMQ string: #{ZMQ::Util.error_string}"
- end
- end
+## Usage
+
+```ruby
+require 'celluloid/zmq'
+
+Celluloid::ZMQ.init
+
+class Server
+ include Celluloid::ZMQ
+
+ def initialize(address)
+ @socket = PullSocket.new
+
+ begin
+ @socket.bind(address)
+ rescue IOError
+ @socket.close
+ raise
end
+ end
+ def run
+ while true; handle_message! @socket.read; end
+ end
+
+ def handle_message(message)
+ puts "got message: #{message}"
+ end
+end
+
+class Client
+ include Celluloid::ZMQ
+
+ def initialize(address)
+ @socket = PushSocket.new
+
+ begin
+ @socket.connect(address)
+ rescue IOError
+ @socket.close
+ raise
+ end
+ end
+
+ def write(message)
+ @socket.send(message)
+
+ nil
+ end
+end
+
+addr = 'tcp://127.0.0.1:3435'
+
+server = Server.new(addr)
+client = Client.new(addr)
+
+server.run!
+client.write('hi')
+```
+
Copyright
---------
-Copyright (c) 2011 Tony Arcieri. See LICENSE.txt for further details.
\ No newline at end of file
+Copyright (c) 2012 Tony Arcieri. See LICENSE.txt for further details.