cod 0.2.0

data/Gemfile

@@ -0,0 +1,12 @@
+source "http://rubygems.org"
+
+gem 'beanstalk-client'
+
+group :test do
+  gem 'rspec'
+  gem 'flexmock'
+  
+  gem 'guard'
+  gem 'growl'
+  gem 'rb-fsevent'
+end

data/HISTORY.txt

@@ -0,0 +1,11 @@
+
+== 0.2 / 2011-04-27
+
+  * Cod::Client now allows both synchronous (with answer) and asynchronous
+    calls (#call vs. #notify).
+
+== 0.1 / 2011-04-20
+
+  * Basic communication via Beanstalk and IO.pipe. 
+  * Client-Service communication
+  * Publish-Subscribe communication

data/LICENSE

@@ -0,0 +1,23 @@
+
+ Copyright (c) 2011 Kaspar Schiess
+
+ Permission is hereby granted, free of charge, to any person
+ obtaining a copy of this software and associated documentation
+ files (the "Software"), to deal in the Software without
+ restriction, including without limitation the rights to use,
+ copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following
+ conditions:
+
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,33 @@
+
+cod is a simple ipc abstraction layer. It allows you to focus on interaction 
+between processes instead of having to think about interaction with the OS. 
+
+SYNOPSIS
+
+  # Cod's basic elements are channels, unidirectional communication links. 
+  pipe = Cod.pipe
+  beanstalk = Cod.beanstalk('localhost:11300')
+  
+  # You can use those either directly: 
+  pipe.put :some_ruby_object        # Process A
+  pipe.get # => :some_ruby_object   # Process B
+  
+  # Or use them as bricks for more: 
+  service = Cod::Service.new(beanstalk)
+  client = Cod::Client.new(beanstalk, pipe)
+  
+  service.one { |msg| :response }               # Process A
+  client.call :ruby_object    # => :response    # Process B
+  
+  # And more: Publish/Subscribe, easy construction of more advanced distributed
+  # communication.
+  
+STATUS
+
+Becoming more useful by the day. Most things will work nicely already,
+although error handling is not production quality. Toy around with it now
+and give me feedback!
+
+At version 0.1 (unreleased)
+
+(c) 2011 Kaspar Schiess

data/Rakefile

@@ -0,0 +1,35 @@
+require "rubygems"
+require "rake/rdoctask"
+require 'rspec/core/rake_task'
+require "rake/gempackagetask"
+
+desc "Run all tests: Exhaustive."
+RSpec::Core::RakeTask.new
+
+task :default => :spec
+
+require 'sdoc'
+
+# Generate documentation
+Rake::RDocTask.new do |rdoc|
+  rdoc.title    = "parslet - construction of parsers made easy"
+  rdoc.options << '--line-numbers'
+  rdoc.options << '--fmt' << 'shtml' # explictly set shtml generator
+  rdoc.template = 'direct' # lighter template used on railsapi.com
+  rdoc.main = "README"
+  rdoc.rdoc_files.include("README", "lib/**/*.rb")
+  rdoc.rdoc_dir = "rdoc"
+end
+
+desc 'Clear out RDoc'
+task :clean => [:clobber_rdoc, :clobber_package]
+
+# This task actually builds the gem. 
+task :gem => :spec
+spec = eval(File.read('cod.gemspec'))
+
+desc "Generate the gem package."
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+

data/examples/master_child.rb

@@ -0,0 +1,16 @@
+$:.unshift File.expand_path(File.dirname(__FILE__) + "/../lib")
+require 'cod'
+
+pipe = Cod.pipe
+
+child_pid = fork do
+  pipe.put 'test'
+  pipe.put Process.pid
+end
+
+begin
+  p pipe.get
+  p pipe.get
+ensure
+  Process.wait(child_pid)
+end

data/examples/ping.rb

@@ -0,0 +1,9 @@
+$:.unshift File.expand_path(File.dirname(__FILE__) + "/../lib")
+require 'cod'
+
+pipe = Cod::Channel::Beanstalk.new('localhost:11300', 'pingpong')
+
+loop do
+  pipe.put Time.now
+  sleep 1
+end

data/examples/pong.rb

@@ -0,0 +1,9 @@
+$:.unshift File.expand_path(File.dirname(__FILE__) + "/../lib")
+require 'cod'
+
+pipe = Cod::Channel::Beanstalk.new('localhost:11300', "pingpong")
+
+loop do
+  puts "Received: "+pipe.get.inspect
+end
+  

data/examples/service.rb

@@ -0,0 +1,26 @@
+# This example spawns a small worker process that will provide a simple
+# service to its parent process. This is just one way of structuring this; the
+# important part here is the client/service code. 
+
+$:.unshift File.expand_path(File.dirname(__FILE__) + "/../lib")
+require 'cod'
+
+service_channel = Cod.pipe
+answer_channel = Cod.pipe
+
+child_pid = fork do
+  service = Cod::Service.new(service_channel)
+  service.one { |call| 
+    puts "Service got called with #{call.inspect}" 
+    time = Time.now
+    puts "Answering with current time: #{time}"
+    time }
+end
+
+client = Cod::Client.new(service_channel, answer_channel)
+puts "Calling service..."
+answer = client.call('42')
+
+puts "Service answered with #{answer}."
+
+Process.wait(child_pid)

data/examples/service_directory.rb

@@ -0,0 +1,32 @@
+$:.unshift File.expand_path(File.dirname(__FILE__) + "/../lib")
+require 'cod'
+
+announce = Cod.pipe
+directory = Cod::Directory.new(announce)
+
+pipes = []
+pids = ['foo.bar', /^foo\..+/].map { |match_expr| 
+  # Creates a communication channel that both the parent and the child know
+  # about. After the fork, they will own unique ends to that channel. 
+  pipes << pipe = Cod.pipe  # store in pipes as well to prevent GC
+  
+  # Create a child that will receive messages that match match_expr.
+  fork do
+    puts "Spawned child: #{Process.pid}"
+    topic = Cod::Topic.new(match_expr, announce, pipe)
+    
+    sleep 0.1
+    loop do
+      message = topic.get
+      puts "#{Process.pid}: received #{message.inspect}."
+      
+      break if message == :shutdown
+    end
+  end }
+  
+directory.publish 'foo.bar', 'Hi everyone!'   # to both childs
+directory.publish 'foo.baz', 'Hi you!'        # only second child matches this
+directory.publish 'no.one', 'echo?'           # no one matches this
+
+directory.publish 'foo.bar', :shutdown        # shutdown children in orderly fashion
+Process.waitall

data/lib/at_fork.rb

@@ -0,0 +1,29 @@
+# Extends the Kernel module with an at_fork method for installing at_fork
+# handlers. 
+
+module Kernel
+  class << self
+    def at_fork_handler
+      @at_fork_handler ||= proc {}
+    end
+    def at_fork_handler=(handler)
+      @at_fork_handler = handler
+    end
+  end
+  
+  def at_fork(&block)
+    old_handler = Kernel.at_fork_handler
+    Kernel.at_fork_handler = lambda { block.call(old_handler) }
+  end
+  
+  def fork_with_at_fork(&block)
+    Kernel.at_fork_handler.call()
+    
+    fork_without_at_fork do
+      Kernel.at_fork_handler = nil
+      block.call
+    end
+  end
+  alias fork_without_at_fork  fork
+  alias fork                  fork_with_at_fork
+end

data/lib/cod.rb

@@ -0,0 +1,49 @@
+require 'at_fork'
+
+module Cod
+  # This gets raised in #create_reference when the identifier passed in is
+  # either invalid (has never existed) or when it cannot be turned into an
+  # object instance. (Because it might have been garbage collected or other
+  # such reasons)
+  #
+  class InvalidIdentifier < StandardError; end
+  
+  def beanstalk(url, name=nil)
+    context.beanstalk(url, name)
+  end
+  module_function :beanstalk
+  
+  def pipe(name=nil)
+    context.pipe(name)
+  end
+  module_function :pipe
+  
+  def context
+    @convenience_context ||= Context.new
+  end
+  module_function :context
+  
+  # For testing mainly
+  #
+  def reset
+    @convenience_context = nil
+  end
+  module_function :reset
+end
+
+module Cod::Connection; end
+require 'cod/connection/beanstalk'
+
+require 'cod/channel'
+require 'cod/channel/base'
+require 'cod/channel/pipe'
+require 'cod/channel/beanstalk'
+
+require 'cod/context'
+require 'cod/client'
+
+require 'cod/service'
+
+require 'cod/directory'
+require 'cod/directory/subscription'
+require 'cod/topic'

data/lib/cod/channel.rb

@@ -0,0 +1,19 @@
+module Cod
+  module Channel
+    # This is raised when you try to read from a channel you've already
+    # written to or write to a channel that you've already read from. 
+    #
+    class DirectionError < StandardError; end
+    
+    # This is raised when a fatal communication error has occurred that 
+    # Cod cannot recover from. 
+    #
+    class CommunicationError < StandardError; end
+
+    # When calling #get on a channel with a timeout (see :timeout option), 
+    # this may be raised. It means that the channel isn't ready for delivering
+    # a message in timeout seconds. 
+    #
+    class TimeoutError < StandardError; end
+  end
+end

data/lib/cod/channel/base.rb

@@ -0,0 +1,99 @@
+
+module Cod
+  # TODO document write/read semantics
+  # TODO document dup behaviour
+  # TODO document object serialisation
+  class Channel::Base
+    # Writes a Ruby object (the 'message') to the channel. This object will 
+    # be queued in the channel and become available for #get in a FIFO manner.
+    #
+    # Issuing a #put also closes the channel instance for subsequent #get's. 
+    #
+    # Example: 
+    #   chan.put 'test'
+    #   chan.put true
+    #   chan.put :symbol
+    #
+    def put(message)
+      not_implemented
+    end
+    
+    # Reads a Ruby object (a message) from the channel. Some channels may not
+    # allow reading after you've written to it once. Options that work: 
+    #
+    #   :timeout :: Time to wait before throwing a Cod::Channel::TimeoutError.
+    #
+    def get(opts={})
+      not_implemented
+    end
+    
+    # Returns true if there are messages waiting in the channel. 
+    #
+    def waiting?
+      not_implemented
+    end
+    
+    def close
+      not_implemented
+    end
+    
+    def identifier
+      not_implemented
+    end
+    
+    # Returns the Identifier class below the current channel class. This is 
+    # a helper function that should only be used by subclasses. 
+    #
+    def identifier_class
+      self.class.const_get(:Identifier)
+    end
+    
+    def marshal_dump
+      identifier
+    end
+    
+    def marshal_load(identifier)
+      temp = identifier.resolve
+      initialize_copy(temp)
+    end
+    
+  private
+    def serialize(message)
+      Marshal.dump(message)
+    end
+    
+    def deserialize(buffer)
+      Marshal.load(buffer)
+    end
+  
+    # Turns the object into a buffer (simple transport layer that prefixes a
+    # size)
+    #
+    def transport_pack(message)
+      serialized = serialize(message)
+      buffer = [serialized.size].pack('l') + serialized
+    end
+    
+    # Slices one message from the front of buffer
+    #
+    def transport_unpack(buffer)
+      size = buffer.slice!(0...4).unpack('l').first
+      serialized = buffer.slice!(0...size)
+      deserialize(serialized)
+    end
+   
+    def direction_error(msg)
+      raise Cod::Channel::DirectionError, msg
+    end
+
+    def communication_error(msg)
+      raise Cod::Channel::CommunicationError, msg
+    end
+    
+    def not_implemented
+      raise NotImplementedError, 
+        "You called a method in Cod::Channel::Base. Missing implementation in "+
+        "the subclass!"
+    end
+  end
+end

data/lib/cod/channel/beanstalk.rb

@@ -0,0 +1,70 @@
+
+begin
+  require 'beanstalk-client'
+rescue LoadError
+  fail "You should install the gem 'beanstalk-client' to use Cod::Channel::Beanstalk."
+end
+
+module Cod
+  class Channel::Beanstalk < Channel::Base
+    NONBLOCK_TIMEOUT = 0.01
+    
+    # Connection instance that is in use for this channel.
+    attr_reader :connection
+
+    # Name of the queue on the beanstalk server
+    attr_reader :tube_name
+    
+    def initialize(connection, name=nil)
+      @connection = connection
+      @tube_name = (name || gen_anonymous_name('beanstalk')).freeze
+    end
+    
+    def initialize_copy(from)
+      @connection = from.connection
+      @tube_name = from.tube_name
+    end
+    
+    def put(message)
+      buffer = serialize(message)
+      connection.put(tube_name, buffer)
+    end
+    
+    def waiting?
+      connection.waiting?(tube_name)
+    end
+    
+    def get(opts={})
+      message = connection.get(tube_name, 
+        :timeout => opts[:timeout])
+      return deserialize(message)
+    rescue Beanstalk::TimedOut
+      raise Channel::TimeoutError, "No messages waiting in #{tube_name}."
+    end
+    
+    def close
+      @connection = @reference = nil
+    end
+
+    def identifier
+      identifier_class.new(connection.url, tube_name)
+    end
+  private
+    def gen_anonymous_name(base)
+      base + ".anonymous"
+    end
+  end
+
+  class Channel::Beanstalk::Identifier
+    def initialize(url, tube_name)
+      @url, @tube_name = url, tube_name
+    end
+    
+    def resolve(ctxt=nil)
+      raise NotImplementedError, "Explicit context not yet implemented." \
+        if ctxt
+          
+      Cod.beanstalk(@url, @tube_name)
+    end
+  end
+end

data/lib/cod/channel/pipe.rb

@@ -0,0 +1,135 @@
+module Cod
+  # A channel that uses IO.pipe as its transport mechanism. This means that
+  # you can only communicate within a single process hierarchy using this, 
+  # since the file descriptors are not visible to the outside world. 
+  #
+  class Channel::Pipe < Channel::Base
+    # A tuple storing the read and the write end of a IO.pipe. 
+    #
+    Fds = Struct.new(:r, :w)
+    
+    attr_reader :fds
+    
+    def initialize(name=nil)
+      @fds = Fds.new(*IO.pipe)
+      @waiting_messages = []
+    end
+
+    def initialize_copy(old)
+      old_fds = old.fds
+
+      raise ArgumentError, 
+        "Dupping a pipe channel only makes sense if it is still unused." \
+          unless old_fds.r && old_fds.w
+
+      @fds = Fds.new(
+        old_fds.r.dup, 
+        old_fds.w.dup)
+      
+      @waiting_messages = []
+    end
+    
+    def put(message)
+      close_read
+      
+      unless fds.w
+        direction_error 'Cannot put data to pipe. Already closed that end?'
+      end
+            
+      buffer = transport_pack(message)
+      fds.w.write(buffer)
+    rescue Errno::EPIPE
+      direction_error "You should #dup before writing; Looks like no other copy exists currently."
+    end
+    
+    def waiting?
+      process_inbound_nonblock
+      queued?
+    rescue Cod::Channel::CommunicationError
+      # Gets raised whenever communication fails permanently. This means that
+      # we probably wont be able to return any more messages. The only messages
+      # remaining in such a situation would be those queued.
+      return queued?
+    end
+    
+    def get(opts={})
+      close_write
+      
+      return @waiting_messages.shift if queued?
+
+      start_time = Time.now
+      loop do
+        IO.select([fds.r], nil, [fds.r], 0.1)
+        process_inbound_nonblock
+        return @waiting_messages.shift if queued?
+        
+        if opts[:timeout] && (Time.now-start_time) > opts[:timeout]
+          raise Cod::Channel::TimeoutError, 
+            "No messages waiting in pipe."
+        end
+      end
+      # NEVER REACHED
+
+    rescue Errno::EPIPE
+      direction_error 'Cannot get data from pipe. Already closed that end?'
+    end
+    
+    def close
+      close_write
+      close_read
+    end
+
+    def identifier
+      identifier_class.new(self)
+    end
+  private
+    def queued?
+      not @waiting_messages.empty?
+    end
+    
+    def close_write
+      return unless fds.w
+      fds.w.close
+      fds.w = nil
+    end
+    
+    def close_read
+      return unless fds.r
+      fds.r.close
+      fds.r = nil
+    end
+  
+    # Tries hard to empty the pipe and to store incoming messages in 
+    # @waiting_messages.
+    #
+    def process_inbound_nonblock
+      buffer = fds.r.read_nonblock(1024*1024*1024)
+
+      while buffer.size > 0
+        @waiting_messages << transport_unpack(buffer)
+      end
+    rescue EOFError
+      # We've just hit end of file in the pipe. That means that all write 
+      # ends have been closed. 
+      communication_error "All write ends for this pipe have been closed. "+
+        "Further #get's would block forever." \
+        unless queued?
+    rescue Errno::EAGAIN
+      # Catch and ignore this: fds.r is not ready and read would block.
+    end
+  end
+  
+  class Channel::Pipe::Identifier
+    def initialize(channel)
+      @objid = channel.object_id
+    end
+    
+    def resolve
+      ObjectSpace._id2ref(@objid)
+    rescue RangeError
+      raise Cod::InvalidIdentifier, 
+        "Could not reference channel. Either it was garbage collected "+
+        "or it never existed in this process."
+    end
+  end
+end

data/lib/cod/client.rb

@@ -0,0 +1,81 @@
+
+module Cod
+  # A client that consumes a service (Cod::Service).
+  #
+  class Client
+    attr_reader :incoming
+    attr_reader :outgoing
+    
+    # Create a new client and tie it to an answer channel. The answer channel
+    # will often be anonymous - no one except the service needs to write
+    # there. 
+    #
+    def initialize(requests, answers, timeout=1)
+      @timeout = timeout
+      @incoming = answers
+      @outgoing = requests
+      @request_id = 0
+    end
+
+    # Calls the service in a synchronous fashion. Returns the message the
+    # server sends back. 
+    #
+    def call(message=nil)
+      expected_id = next_request_id
+      outgoing.put envelope(expected_id, message, incoming, true)
+      
+      start_time = Time.now
+      loop do
+        received_id, answer = incoming.get(:timeout => @timeout)
+        return answer if received_id == expected_id
+        
+        # We're receiving answers with request_ids that are outside the 
+        # window that we would expect. Something is seriously amiss. 
+        raise Cod::Channel::CommunicationError, 
+          "Missed request." unless earlier?(expected_id, received_id)
+          
+        # We've been waiting (and consuming answers) for too long - overall
+        # timeout has elapsed. 
+        raise Cod::Channel::TimeoutError, 
+          "Timed out while waiting for service request answer." \
+            if (Time.now-start_time) > @timeout
+      end
+    end
+    
+    # This sends the server a message without waiting for an answer. The
+    # server will throw away the answer produced. 
+    #
+    def notify(message=nil)
+      outgoing.put envelope(next_request_id, message, incoming, false)
+      nil
+    end
+    
+    # Closes all resources that are held in the client. 
+    #
+    def close
+      incoming.close
+      outgoing.close
+    end
+    
+  private
+  
+    # Creates a message to send to the service. 
+    #
+    def envelope(id, message, incoming_channel, needs_answer)
+      [id, message, incoming_channel, needs_answer]
+    end
+  
+    # Returns a sequence of request ids.
+    #
+    def next_request_id
+      @request_id += 1
+    end
+    
+    # True if the received request id answers a request that has been 
+    # earlier than the expected request id.
+    #
+    def earlier?(expected, received)
+      expected > received
+    end
+  end
+end

data/lib/cod/connection/beanstalk.rb

@@ -0,0 +1,56 @@
+module Cod
+  # Wraps the lower level beanstalk connection and exposes only methods that
+  # we need; also makes tube handling a bit more predictable. 
+  #
+  class Connection::Beanstalk
+    # The url that was used to connect to the beanstalk server. 
+    attr_reader :url
+    
+    # Connection to the beanstalk server. 
+    attr_reader :connection
+    
+    def initialize(url)
+      @url = url
+      @connection = Beanstalk::Connection.new(url)
+    end
+    
+    # Writes a raw message as a job to the tube given by name. 
+    #
+    def put(name, message)
+      connection.use name
+      connection.put message
+    end
+    
+    # Returns true if there are jobs waiting in the tube given by 'name'
+    def waiting?(name)
+      watch(name) do  
+        !! connection.peek_ready
+      end
+    end
+    
+    # Removes and returns the next message waiting in the tube given by name.
+    #
+    def get(name, opts={})
+      watch(name) do
+        job = connection.reserve(opts[:timeout])
+        job.delete
+        
+        job.body
+      end
+    end
+    
+    # Closes the connection
+    #
+    def close
+      @connection = nil
+    end
+    
+  private
+    def watch(name)
+      connection.watch(name)
+      yield
+    ensure
+      connection.ignore(name)
+    end
+  end
+end

data/lib/cod/context.rb

@@ -0,0 +1,72 @@
+require 'weakref'
+
+module Cod
+  # Channels inside a context know each other and can be looked up by their
+  # identifier. Context is also responsible for holding connections and for
+  # doing background work. For most purposes, you will only need one context; 
+  # by using methods on the Cod module directly, you implicitly hold a context
+  # and call methods there. 
+  #
+  class Context
+    
+    def self.install_at_fork(ref)
+      at_fork do |old_handler|
+        old_handler.call rescue nil
+        
+        begin
+          ref.reset
+        rescue WeakRef::RefError
+          # IGNORED EXCEPTION
+        end
+      end
+    end
+    
+    def initialize
+      @connections = {}
+      
+      self.class.install_at_fork(WeakRef.new(self))
+    end
+    
+    def pipe(name=nil)
+      Cod::Channel::Pipe.new(name)
+    end
+    
+    def beanstalk(url, name=nil)
+      Cod::Channel::Beanstalk.new(
+        connection(:beanstalk, url), name)
+    end
+    
+    def reset
+      @connections = {}
+    end
+    
+  private
+    # Returns a connection to a system identified by type and url. Currently, 
+    # connections are never released or closed. This is only a minor drawback
+    # since there will be few of them. (considering we only use this for 
+    # beanstalk) 
+    #
+    def connection(type, url)
+      key = connection_key(type, url)
+      
+      connection = @connections[key]
+      return connection if connection
+    
+      produce_connection(type, url).tap { |connection|
+        @connections.store(key, connection) }
+    end
+    
+    def connection_key(type, url)
+      [type, url]
+    end
+    
+    def produce_connection(type, url)
+      case type
+        when :beanstalk
+          return Connection::Beanstalk.new(url)
+      end
+      
+      fail "Tried to produce a connection of unknown type #{type.inspect}."
+    end
+  end
+end

data/lib/cod/directory.rb

@@ -0,0 +1,44 @@
+module Cod
+  # A directory where one can publish messages given a topic string. 
+  #
+  # The channel given will be where people should subscribe.
+  #
+  class Directory
+    # The channel the directory receives subscription messages on. 
+    #
+    attr_reader :channel
+    
+    def initialize(channel)
+      @channel = channel
+      @subscriptions = []
+    end
+    
+    # Sends the message to all subscribers that listen to this topic. 
+    #
+    def publish(topic, message)
+      handle_subscriptions
+      
+      for subscription in @subscriptions
+        subscription.put message if subscription === topic
+      end
+    end
+    
+    # Closes all resources used by the directory. 
+    #
+    def close
+      channel.close
+    end
+    
+  private
+  
+    def handle_subscriptions
+      while channel.waiting?
+        subscribe channel.get
+      end
+    end
+    
+    def subscribe(subscription)
+      @subscriptions << subscription
+    end
+  end
+end

data/lib/cod/directory/subscription.rb

@@ -0,0 +1,21 @@
+module Cod
+  # Represents a subscription to a directory. 
+  #
+  class Directory::Subscription
+    attr_reader :matcher
+    attr_reader :channel
+    
+    def initialize(matcher, channel)
+      @matcher = matcher
+      @channel = channel
+    end
+    
+    def ===(other)
+      matcher === other
+    end
+    
+    def put(msg)
+      channel.put msg
+    end
+  end
+end

data/lib/cod/service.rb

@@ -0,0 +1,60 @@
+
+module Cod
+  # A service that receives requests and answers. A service has always at
+  # least one provider that creates an instance of this class and waits in
+  # #one or #each. Clients then instantiate Cod::Client and #call the service.
+  #
+  # Example: 
+  #   # service side
+  #   service = Cod::Service.new(incoming_channel)
+  #   service.one { |msg| 'answer' }
+  # 
+  #   # client side
+  #   client = Cod::Client.new(incoming_channel, service_channel)
+  #   client.call('call message') # => 'answer'
+  #
+  # == Topology
+  # 
+  # A service always has (potentially) multiple clients and depending on the
+  # transport layer used, one or more workers handling the clients request.
+  # They will always receive the messages in a round robin fashion; the
+  # service corresponds in this case to the channel address; clients need not
+  # know the workers involved. 
+  #
+  class Service
+    # Incoming channel for requests.
+    attr_reader :incoming
+    
+    def initialize(channel)
+      @incoming = channel
+    end
+    
+    # Calls the given block with the next request and returns the block answer
+    # to the service client. 
+    #
+    def one
+      request_id, message, answer_channel, needs_answer = incoming.get      
+      
+      answer = yield(message)
+      
+      if needs_answer
+        answer_channel.put [request_id, answer]
+      end
+    end
+    
+    # Loops forever, yielding requests to the block given and returning the 
+    # answers to the client.
+    #
+    def each(&block)
+      loop do
+        one(&block)
+      end
+    end
+    
+    # Releases all resources held by the service. 
+    #
+    def close
+      incoming.close
+    end
+  end
+end

data/lib/cod/topic.rb

@@ -0,0 +1,34 @@
+module Cod
+  # A topic in a directory. 
+  #
+  class Topic
+    attr_reader :answers, :directory
+    attr_reader :match_expr
+    def initialize(match_expr, directory_channel, answer_channel)
+      @directory, @answers = directory_channel, answer_channel
+      @match_expr = match_expr
+      
+      subscribe
+    end
+    
+    # Subscribes this topic to the directory's messages. This gets called upon
+    # initialization and must not be called again. 
+    #
+    def subscribe
+      directory.put Directory::Subscription.new(match_expr, answers)
+    end
+
+    # Reads the next message from the directory that matches this topic. 
+    #
+    def get
+      answers.get
+    end
+    
+    # Closes all resources used by the topic. 
+    #
+    def close
+      directory.close
+      answers.close
+    end
+  end
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification 
+name: cod
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.2.0
+platform: ruby
+authors: 
+- Kaspar Schiess
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-04-27 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: flexmock
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: sdoc
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id003
+description: 
+email: kaspar.schiess@absurd.li
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- Gemfile
+- HISTORY.txt
+- LICENSE
+- Rakefile
+- README
+- lib/at_fork.rb
+- lib/cod/channel/base.rb
+- lib/cod/channel/beanstalk.rb
+- lib/cod/channel/pipe.rb
+- lib/cod/channel.rb
+- lib/cod/client.rb
+- lib/cod/connection/beanstalk.rb
+- lib/cod/context.rb
+- lib/cod/directory/subscription.rb
+- lib/cod/directory.rb
+- lib/cod/service.rb
+- lib/cod/topic.rb
+- lib/cod.rb
+- examples/master_child.rb
+- examples/ping.rb
+- examples/pong.rb
+- examples/service.rb
+- examples/service_directory.rb
+has_rdoc: true
+homepage: http://kschiess.github.com/cod
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.5.2
+signing_key: 
+specification_version: 3
+summary: Really simple IPC.
+test_files: []
+