OVERVIEW

Project ichannel
Homepage https://github.com/robgleeson/ichannel
Documentation http://rubydoc.info/github/robgleeson/ichannel/frames
Metrics Code Climate
CI Build Status
Author Robert Gleeson

DESCRIPTION

ichannel is a channel for interprocess communication between ruby processes on the same machine or network. The basic premise is that you can "put" a ruby object onto the channel and on the other end(maybe in a different process, or maybe on a different machine) you can "get" the object from the channel. A unix socket (local to a single machine) or redis can be used for transport.

A channel depends on a serializer when reading and writing from the underlying socket(e.g: redis or a unix socket) but you can use any serializer that implements the dump and load methods. The default is set to be Marshal since it is a core ruby module but you could also use JSON, YAML, MessagePack, or <insert your serializer here>.

EXAMPLES

1.

A demo of how to pass ruby objects through a channel and also between processes. Marshal is the serializer of choice, and a streamed UNIXSocket is used for transport:

channel = IChannel.unix Marshal
pid = fork do
  channel.put Process.pid
  channel.put 'Hello!'
end
Process.wait pid
channel.get # => Fixnum
channel.get # => 'Hello!'

2.

A demo of a channel sending messages between machines by using redis for transport:

channel = IChannel.redis Marshal, host: "10.0.0.1", key: "readme-example"
channel.put %w(a)

# In another process, on another machine, far away…
channel = IChannel.redis Marshal, host: "10.0.0.1", key: "readme-example"
channel.get # => ["a"]

3.

Knowing when a channel is readable can be useful so that you can avoid a blocking read on the underlying UNIXSocket. This (bad) example demonstrates how to do that:

channel = IChannel.unix Marshal
pid = fork do
  sleep 3
  channel.put 42
end
until channel.readable?
  # do something else
end
channel.get # => 42
Process.wait pid

4.

MessagePack doesn't implement dump or load but a wrapper can be easily written:

module MyMessagePack
  def self.dump(msg)
    MessagePack.pack(msg)
  end

  def self.load(msg)
    MessagePack.unpack(msg)
  end
end
channel = IChannel.unix MyMessagePack

PLATFORM SUPPORT

supported

  • CRuby (1.9+)
  • Rubinius (1.9+)
  • JRuby (1.9+ - some tests skipped)
    JRuby is supported and passes the test suite but it has a few skips.
    Three skips are because jruby does not implement Kernel.fork.
    The other tests pass on jruby, & those tests cover both unix sockets & redis.

unsupported

  • Any 1.8 implementation
  • MacRuby

INSTALL

If you plan on using redis you'll need to install the 'redis' gem. It's optional:

$ gem install redis

And to finish:

$ gem install ichannel

SEE ALSO

  • ifuture futures built on process forks and ichannel.

LICENSE

MIT. See LICENSE.txt.