cod 0.2.0 → 0.3.0

data/Gemfile

@@ -7,6 +7,10 @@ group :test do
   gem 'flexmock'
   
   gem 'guard'
+  gem 'guard-rspec'
+  
+  gem 'sdoc'
+  
   gem 'growl'
   gem 'rb-fsevent'
 end

data/HISTORY.txt

@@ -1,4 +1,13 @@
 
+== 0.3 / 20Jul2011
+
+  + Cod.tcpserver and Cod.tcp channels. Allows direct connection via 
+    TCP/IP with the same semantics.
+  
+  - You will now need to always provide a name for beanstalk channels. There
+    is currently no reliable way to generate unique names at the library 
+    level.
+
 == 0.2 / 2011-04-27
 
   * Cod::Client now allows both synchronous (with answer) and asynchronous

data/README

@@ -6,7 +6,7 @@ SYNOPSIS
 
   # Cod's basic elements are channels, unidirectional communication links. 
   pipe = Cod.pipe
-  beanstalk = Cod.beanstalk('localhost:11300')
+  beanstalk = Cod.beanstalk('localhost:11300', 'a_channel')
   
   # You can use those either directly: 
   pipe.put :some_ruby_object        # Process A
@@ -28,6 +28,6 @@ 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)
+At version 0.3 
 
 (c) 2011 Kaspar Schiess

data/Rakefile

@@ -1,7 +1,8 @@
+require 'psych'
 require "rubygems"
 require "rake/rdoctask"
 require 'rspec/core/rake_task'
-require "rake/gempackagetask"
+require 'rubygems/package_task'
 
 desc "Run all tests: Exhaustive."
 RSpec::Core::RakeTask.new
@@ -29,7 +30,6 @@ task :gem => :spec
 spec = eval(File.read('cod.gemspec'))
 
 desc "Generate the gem package."
-Rake::GemPackageTask.new(spec) do |pkg|
-  pkg.gem_spec = spec
+Gem::PackageTask.new(spec) do |pkg|
+  # pkg.need_tar = true
 end
-

data/examples/example_scaffold.rb

@@ -0,0 +1,15 @@
+def server
+  fork do
+    yield
+  end
+end
+
+def client
+  fork do
+    yield
+  end
+end
+
+def run
+  Process.waitall
+end

data/examples/ping.rb

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

data/examples/pong.rb

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

data/examples/tcp.rb

@@ -0,0 +1,21 @@
+$:.unshift File.expand_path(File.dirname(__FILE__) + "/../lib")
+$:.unshift File.expand_path(File.dirname(__FILE__))
+require 'cod'
+
+require 'example_scaffold'
+
+server {
+  channel = Cod.tcpserver('127.0.0.1:5454')
+  
+  client = channel.get
+  client.put 'heiho from server'
+}
+
+client {
+  channel = Cod.tcp('127.0.0.1:5454')
+  
+  channel.put channel
+  puts channel.get
+}
+
+run

data/lib/at_fork.rb

@@ -1,26 +1,50 @@
 # Extends the Kernel module with an at_fork method for installing at_fork
 # handlers. 
-
+#
+# NOTE: at_fork handlers are executed in the thread that does the forking and
+# that survives the process fork. 
+#
+# Usage: 
+# 
+#   at_fork do 
+#     # Do something on fork (in the forking process)
+#   end
+#   at_fork(:child) { ... }  # do something in the forked process 
+#   at_fork(:parent) { ... } # do something in the forking process
+# 
 module Kernel
-  class << self
-    def at_fork_handler
-      @at_fork_handler ||= proc {}
-    end
-    def at_fork_handler=(handler)
-      @at_fork_handler = handler
-    end
+  # Child at_fork handlers
+  #
+  def self.at_fork_child
+    @at_fork_child ||= []
   end
   
-  def at_fork(&block)
-    old_handler = Kernel.at_fork_handler
-    Kernel.at_fork_handler = lambda { block.call(old_handler) }
+  # Parent at_fork handlers
+  #
+  def self.at_fork_parent
+    @at_fork_parent ||= []
+  end
+  
+  def at_fork(type=:parent,&block)
+    raise ArgumentError, "Must provide a handler block." unless block
+    
+    handler_array = (type == :child) ? 
+      Kernel.at_fork_child : Kernel.at_fork_parent
+      
+    handler_array << block
   end
   
   def fork_with_at_fork(&block)
-    Kernel.at_fork_handler.call()
+    Kernel.at_fork_parent.each(&:call)
     
     fork_without_at_fork do
-      Kernel.at_fork_handler = nil
+      # From this point on, operation is single threaded.
+      
+      Kernel.at_fork_child.each(&:call)
+      
+      Kernel.at_fork_parent.replace([])
+      Kernel.at_fork_child.replace([])
+      
       block.call
     end
   end

data/lib/cod.rb

@@ -1,5 +1,32 @@
 require 'at_fork'
 
+# The core concept of Cod are 'channels'. (Cod::Channel::Base) You can create
+# such channels on top of the various transport layers. Once you have such a
+# channel, you #put messages into it and you #get messages out of it. Messages
+# are retrieved in FIFO manner, making channels look like a communication pipe
+# most of the time. 
+#
+# Cod also brings a few abstractions layered on top of channels: You can use
+# channels to present 'services' (Cod::Service) to the network: A service is a
+# simple one or two way RPC call. (one way = asynchronous) You can also use
+# channels to run a 'directory' (Cod::Directory) where processes subscribe to
+# information using a filter. They then get information that matches their
+# filter written to their inbound channel. (also called pub/sub)
+#
+# Cod channels are serializable whereever possible. If you want to tell
+# somebody where to write his answers and/or questions to, send him the
+# channel! This is really powerful and used extensively in constructing the
+# higher order primitives. 
+#
+# The goal of Cod is that you have to know only very few things about the
+# network (the various transports) to be able to construct complex things. It
+# handles reconnection and reliability for you. It also translates cryptic OS
+# errors into plain text messages where it can't just handle them. This should
+# give you a clear place to look at if things go wrong. Note that this can
+# only be ever as good as the sum of situations Cod has been tested in.
+# Contribute your observations and we'll come up with a way of dealing with
+# most of the tricky stuff!
+#
 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
@@ -8,24 +35,59 @@ module Cod
   #
   class InvalidIdentifier < StandardError; end
   
-  def beanstalk(url, name=nil)
+  # Creates a beanstalkd based channel. Messages are written to a tube and 
+  # read from it. This channel is read/write. Multiple readers will obtain
+  # messages in a round-robin fashion from the beanstalk server. 
+  #
+  # Returns an instance of the Cod::Channel::Beanstalk class.
+  #
+  # Example: 
+  #   chan = Cod.beanstalk('localhost:11300', 'my_tube')
+  #
+  def beanstalk(url, name)
     context.beanstalk(url, name)
   end
   module_function :beanstalk
   
+  # Creates a IO.pipe based channel. Messages are written to one end of the 
+  # pipe and come out on the other end. This channel can have only one reader, 
+  # but of course multiple writers. Also, once you either write or read from 
+  # such a channel, it will not be available for the other operation anymore. 
+  #
+  # A common trick is to #dup the channel before using it to either read or
+  # write, so that the copy can still be used for both operations. 
+  #
+  # Note that Cod.pipe channels are usable from process childs (#fork) as 
+  # well. As such, they are ideally suited for process control. 
+  #
+  # Returns an instance of the Cod::Channel::Pipe class.
+  #
+  # Example: 
+  #   chan = Cod.pipe
+  # 
   def pipe(name=nil)
     context.pipe(name)
   end
   module_function :pipe
   
-  def context
+  def tcp(destination)
+    context.tcp(destination)
+  end
+  module_function :tcp
+  
+  def tcpserver(bind_to)
+    context.tcpserver(bind_to)
+  end
+  module_function :tcpserver
+  
+  def context # :nodoc: 
     @convenience_context ||= Context.new
   end
   module_function :context
   
   # For testing mainly
   #
-  def reset
+  def reset # :nodoc: 
     @convenience_context = nil
   end
   module_function :reset
@@ -34,10 +96,14 @@ end
 module Cod::Connection; end
 require 'cod/connection/beanstalk'
 
+require 'cod/object_io'
+
 require 'cod/channel'
 require 'cod/channel/base'
 require 'cod/channel/pipe'
 require 'cod/channel/beanstalk'
+require 'cod/channel/tcpconnection'
+require 'cod/channel/tcpserver'
 
 require 'cod/context'
 require 'cod/client'

data/lib/cod/channel/abstract.rb

@@ -0,0 +1,32 @@
+module Cod
+  # This is mostly documentation: Use it as a template for new channels.
+  class Channel::Abstract < Channel::Base
+    def initialize(destination)
+      not_implemented
+    end
+    
+    def initialize_copy(from)
+      not_implemented
+    end
+    
+    def put(message)
+      not_implemented
+    end
+    
+    def get(opts={})
+      not_implemented
+    end
+    
+    def waiting?
+      not_implemented
+    end
+    
+    def close
+      not_implemented
+    end
+    
+    def identifier
+      not_implemented
+    end
+  end
+end

data/lib/cod/channel/base.rb

@@ -1,13 +1,49 @@
 
 module Cod
-  # TODO document write/read semantics
-  # TODO document dup behaviour
-  # TODO document object serialisation
+  # Channels are the communication primitives you've always wanted (secretly).
+  # They are simple to use, abstract most of the OS away and allow direct 
+  # communication using language objects, not just strings. (Although you can
+  # fall back to just strings if you want to)
+  #
+  # == Construction
+  #
+  # The simplest way to obtain a new channel is through the Module Cod. It 
+  # provides the following channel types: 
+  #
+  # Cod.beanstalk(url, name)  :: connects to beanstalkd daemon
+  # Cod.pipe                  :: abstracts IO.pipe
+  # Cod.tcp(url)              :: connects to a tcp socket somewhere
+  # Cod.tcpserver(url)        :: the counterpart to Cod.tcp
+  #
+  # Please refer to the documentation of these methods for more information. 
+  #
+  # == Basic Interaction
+  #
+  # You can #put messages (Ruby objects) into a channel on one side: 
+  #
+  #   channel.put("some message")
+  #
+  # and #get messages on the other side: 
+  #
+  #   channel.get # => "some message"
+  #
+  # == Querying
+  #
+  # Are there messages waiting to be read from the channel? Use #waiting?: 
+  # 
+  #   channel.waiting? # => true or false
+  #
+  # == Cleaning up
+  #
+  # Be sure to #close the channel once you're done with it.
+  #
+  #   channel.close
+  #
   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. 
+    # Issuing a #put may also close the channel instance for subsequent #get's. 
     #
     # Example: 
     #   chan.put 'test'
@@ -21,7 +57,7 @@ module Cod
     # 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.
+    # <code>:timeout</code> :: Time to wait before throwing Cod::Channel::TimeoutError.
     #
     def get(opts={})
       not_implemented
@@ -37,50 +73,77 @@ module Cod
       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
+    def identifier_class # :nodoc: 
       self.class.const_get(:Identifier)
     end
-    
-    def marshal_dump
-      identifier
+
+    # Something to put into the data stream that is transmitted through a 
+    # channel that allows reconstitution of the channel at the other end. 
+    # The invariant is this: 
+    #
+    #   # channel1 and channel2 are abstract channels that illustrate my 
+    #   # meaning
+    #   channel1.put channel2
+    #   channel2a = channel1.get
+    #   channel2a.put 'foo'
+    #   channel2.get # => 'foo'
+    #   
+    # Note that this should also work if channel1 and channel2 are the same. 
+    #
+    def identifier # :nodoc: 
+      identifier_class.new(self)
     end
     
-    def marshal_load(identifier)
-      temp = identifier.resolve
-      initialize_copy(temp)
+    # ------------------------------------------------------------ marshalling
+
+    # Makes sure that we don't marshal this object, but the memento object
+    # returned by identifier. 
+    #
+    def _dump(d) # :nodoc: 
+      wire_data = to_wire_data
+      Marshal.dump(wire_data)
     end
-    
-  private
-    def serialize(message)
-      Marshal.dump(message)
+     
+    # Loads the object from string. This doesn't always return the same kind
+    # of object that was serialized. 
+    #
+    def self._load(string) # :nodoc: 
+      wire_data = Marshal.load(string)
+      from_wire_data(wire_data)
     end
     
-    def deserialize(buffer)
-      Marshal.load(buffer)
-    end
+  private
   
-    # Turns the object into a buffer (simple transport layer that prefixes a
-    # size)
+    # Returns the objects that need to be transmitted in order to reconstruct
+    # this object after transmission through the wire. 
+    #
+    # If you're using a serialisation method other than the Ruby built in 
+    # one, use this to obtain something in lieu of a channel that can be sent
+    # through the wire and reinterpreted at the other end. 
     #
-    def transport_pack(message)
-      serialized = serialize(message)
-      buffer = [serialized.size].pack('l') + serialized
+    # Example: 
+    #
+    #   # this should work: 
+    #   obj = channel.to_wire_data
+    #   channel_equiv = Cod::Channel::Base.from_wire_data(obj)
+    #
+    def to_wire_data
+      identifier
     end
     
-    # Slices one message from the front of buffer
+    # Using an object previously returned by #to_wire_data, reconstitute the
+    # original channel or something that is alike it. What you send to this
+    # second channel (#put) you should be able to #get from this copy returned
+    # here. 
     #
-    def transport_unpack(buffer)
-      size = buffer.slice!(0...4).unpack('l').first
-      serialized = buffer.slice!(0...size)
-      deserialize(serialized)
+    def self.from_wire_data(obj)
+      obj.resolve
     end
+    
+    # ---------------------------------------------------------- error raising
    
     def direction_error(msg)
       raise Cod::Channel::DirectionError, msg