cod 0.3.1 → 0.4.0

data/lib/cod/beanstalk/serializer.rb

@@ -0,0 +1,80 @@
+module Cod::Beanstalk
+  # This is a kind of beanstalk message middleware: It generates and parses
+  # beanstalk messages from a ruby format into raw bytes. The raw bytes go
+  # directly into the tcp channel that underlies the beanstalk channel. 
+  #
+  # Messages are represented as simple Ruby arrays, specifying first the
+  # beanstalkd command, then arguments. Examples: 
+  #   [:use, 'a_tube']
+  #   [:delete, 123]
+  #
+  # One exception: The commands that have a body attached will be described
+  # like so in protocol.txt: 
+  #   put <pri> <delay> <ttr> <bytes>\r\n
+  #   <data>\r\n
+  #
+  # To generate this message, just put the data where the bytes would be and
+  # the serializer will do the right thing. 
+  #   [:put, pri, delay, ttr, "my_small_data"]
+  #
+  # Results come back in the same way, except that the answers take the place
+  # of the commands. Answers are always in upper case.
+  #
+  # Also see https://raw.github.com/kr/beanstalkd/master/doc/protocol.txt.
+  #
+  class Serializer
+    def en(msg)
+      cmd = msg.first
+      
+      if cmd == :put
+        body = msg.last
+        format(*msg[0..-2], body.bytesize) << format(body)
+      else
+        format(*msg)
+      end
+    end
+    
+    def de(io)
+      str = io.gets("\r\n")
+      raw = str.split
+      
+      cmd = convert_cmd(raw.first)
+      msg = [cmd, *convert_args(raw[1..-1])]
+
+      if [:ok, :reserved].include?(cmd)
+        # More data to read:
+        size = msg.last
+        data = io.read(size+2)
+
+        fail "No crlf at end of data?" unless data[-2..-1] == "\r\n"
+        msg[-1] = data[0..-3]
+      end
+      
+      msg
+    end
+    
+  private
+    # Joins the arguments with a space and appends a \r\n
+    #
+    def format(*args)
+      args.join(' ') << "\r\n"
+    end
+    
+    # Converts a beanstalkd answer like INSERTED to :inserted
+    # 
+    def convert_cmd(cmd)
+      cmd.downcase.to_sym
+    end
+    
+    # Converts an argument to either a number or a string, depending on
+    # what it looks like. 
+    # 
+    # Example:
+    #   convert_args(['1', 'a string']) # => [1, 'a string']
+    #
+    def convert_args(args)
+      args.map { |e| 
+        /^\d+$/.match(e) ? Integer(e) : e }
+    end
+  end
+end

data/lib/cod/beanstalk/service.rb

@@ -0,0 +1,53 @@
+module Cod::Beanstalk
+  class Service < Cod::Service
+    def one(&block)
+      @channel.try_get { |(rq, answer_chan), control| 
+        result = if block.arity == 2
+          block.call(rq, Control.new(control))
+        else
+          block.call(rq)
+        end
+        
+        unless control.command_given?
+          # The only way to respond to the caller is by exiting the block 
+          # without giving metacommands.
+          answer_chan.put result if answer_chan
+        end
+      }
+    end
+    
+    class Control
+      def initialize(channel_control)
+        @channel_control = channel_control
+      end
+      
+      def retry_in(seconds)
+        fail ArgumentError, 
+          "#retry_in accepts only an integer number of seconds." \
+          unless seconds.floor == seconds
+            
+        @channel_control.release_with_delay(seconds)
+      end
+      def retry
+        @channel_control.release
+      end
+      def bury
+        @channel_control.bury
+      end
+      def delete
+        @channel_control.delete
+      end
+      
+      def command_issued?
+        @channel_control.command_given?
+      end
+      
+      def msg_id
+        @channel_control.msg_id
+      end
+    end
+    
+    class Client < Cod::Service::Client
+    end
+  end
+end

data/lib/cod/channel.rb

@@ -1,19 +1,61 @@
 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. 
+  # Channels transport ruby objects from one end to the other. The
+  # communication setup varies a bit depending on the transport used for the
+  # channel, but the interface you interact with doesn't vary. You can #put
+  # messages into a channel and you then #get them out of it. 
+  #
+  # Synopsis: 
+  #   channel.put [:a, :ruby, :object]
+  #   channel.get # => [:a, :ruby, :object]
+  #
+  # By default, channels will serialize the messages you give them using
+  # Marshal.dump and Marshal.load. You can change this by passing your own
+  # serializer to the channel upon construction; see SimpleSerializer for a
+  # description of the interface such a serializer needs to implement. 
+  # 
+  # This class (Cod::Channel) is the abstract superclass of all Cod channels.
+  # It doesn't have a transport by its own, but implements the whole interface
+  # for documentation purposes.
+  #
+  class Channel
+    # Obtains one message from the channel. If the channel is empty, but
+    # theoretically able to receive more messages, blocks forever. But if the
+    # channel is somehow broken, an exception is raised. 
     #
-    class DirectionError < StandardError; end
+    def get
+      abstract_method_error
+    end
     
-    # This is raised when a fatal communication error has occurred that 
-    # Cod cannot recover from. 
+    # Puts one message into a channel. 
     #
-    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. 
+    def put(msg)
+      abstract_method_error
+    end
+    
+    # Interact with a channel by first writing msg to it, then reading back 
+    # the other ends answer. 
+    #
+    def interact(msg)
+      put msg
+      get
+    end
+    
+    # Produces a service that has this channel as communication point. 
     #
-    class TimeoutError < StandardError; end
+    def service
+      abstract_method_error
+    end
+    
+    # Produces a service client that connects to this channel and receives
+    # service answers to the channel indicated by answers_to.
+    #
+    def client(answers_to)
+      abstract_method_error
+    end
+    
+  private 
+    def abstract_method_error
+      fail "Abstract method called"
+    end
   end
 end

data/lib/cod/pipe.rb

@@ -0,0 +1,188 @@
+
+module Cod
+  # A cod channel based on IO.pipe. 
+  #
+  # NOTE: If you embed Cod::Pipe channels into your messages, Cod will insert
+  # the object id of that channel into the byte stream that is transmitted. On
+  # receiving such an object id (a machine pointer), Cod will try to
+  # reconstruct the channel that was at the origin of the id. This can
+  # obviously only work if you have such an object in your address space.
+  # There are multiple ways to construct such a situation. Say you want to
+  # send a pipe channel to one of your (forked) childs: This will work if you
+  # create the channel before forking the child, since master and child will
+  # share all objects that were available before the fork. 
+  #
+  class Pipe
+    attr_reader :pipe
+    attr_reader :serializer
+    
+    IOPair = Struct.new(:r, :w) do
+      # Performs a deep copy of the structure. 
+      def initialize_copy(other)
+        super
+        self.r = other.r.dup if other.r
+        self.w = other.w.dup if other.w
+      end
+      def write(buf)
+        close_r
+        raise Cod::ReadOnlyChannel unless w
+        w.write(buf)
+      end
+      def close
+        close_r
+        close_w
+      end
+      def close_r
+        r.close if r
+        self.r = nil
+      end
+      def close_w
+        w.close if w
+        self.w = nil
+      end
+    end
+
+    # A few methods that a pipe split must answer to. The split itself is 
+    # basically an array instance; these methods add some calling safety and
+    # convenience. 
+    #
+    module SplitMethods # :nodoc:
+      def read; first; end
+      def write; last; end
+    end
+
+    def initialize(serializer=nil)
+      super
+      @serializer = serializer || SimpleSerializer.new
+      @pipe = IOPair.new(*IO.pipe)
+    end
+    
+    # Creates a copy of this pipe channel. This performs a shallow #dup except
+    # for the file descriptors stored in the pipe, so that a #close affects
+    # only one copy. 
+    #
+    def initialize_copy(other)
+      super
+      @serializer = other.serializer
+      @pipe = other.pipe.dup
+    end
+    
+    # Makes this pipe readonly. Calls to #put will error out. This closes the
+    # write end permanently and provokes end of file on the read end once all
+    # processes that posses a link to the write end do so. 
+    # 
+    # Returns self so that you can write for example: 
+    #   read_end = pipe.dup.readonly
+    #
+    def readonly
+      pipe.close_w
+      self
+    end
+    
+    # Makes this pipe writeonly. Calls to #get will error out. See #readonly. 
+    #
+    # Returns self so that you can write for example: 
+    #   write_end = pipe.dup.writeonly
+    #
+    def writeonly
+      pipe.close_r
+      self
+    end
+    
+    # Actively splits this pipe into two ends, a read end and a write end. The
+    # original pipe is closed, leaving only the two ends to work with. The 
+    # read end can only be read from (#get) and the write end can only be 
+    # written to (#put).
+    #
+    def split
+      [self.dup.readonly, self.dup.writeonly].tap { |split|
+        self.close
+        
+        split.extend(SplitMethods)
+      }
+    end
+    
+    # Using #put on a pipe instance will close the other pipe end. Subsequent
+    # #get will raise a Cod::InvalidOperation. 
+    #
+    # Example: 
+    #   pipe.put [:a, :message]
+    #
+    def put(obj)
+      raise Cod::ReadOnlyChannel unless can_write?
+      
+      pipe.write(
+        serializer.en(obj))
+    end
+    
+    # Using #get on a pipe instance will close the other pipe end. Subsequent
+    # #put will receive a Cod::InvalidOperation.
+    #
+    # Example: 
+    #   pipe.get # => obj
+    #
+    def get(opts={})
+      raise Cod::WriteOnlyChannel unless can_read?
+      pipe.close_w
+      
+      loop do
+        ready = Cod.select(nil, self)
+        return deserialize_one if ready
+      end
+    rescue EOFError
+      fail "All pipe ends seem to be closed. Reading from this pipe will not "+
+        "return any data."
+    end
+    
+    # Closes the pipe completely. All active ends are closed. Note that you
+    # can call this function on a closed pipe without getting an error raised.
+    #
+    def close
+      pipe.close
+    end
+
+    # Returns if this pipe is ready for reading. 
+    #
+    def select(timeout=nil)
+      result = Cod.select(timeout, self)
+      not result.nil?
+    end
+    def to_read_fds
+      pipe.r
+    end
+    
+    # Returns true if you can read from this pipe. 
+    #
+    def can_read?
+      not pipe.r.nil?
+    end
+    
+    # Returns true if you can write to this pipe. 
+    #
+    def can_write?
+      not pipe.w.nil?
+    end
+
+    # --------------------------------------------------------- service/client
+    
+    def service
+      Service.new(self)
+    end
+    def client(answers_to)
+      Service::Client.new(self, answers_to)
+    end
+
+    # ---------------------------------------------------------- serialization
+    def _dump(depth) # :nodoc:
+      object_id.to_s
+    end
+    def self._load(string) # :nodoc:
+      ObjectSpace._id2ref(Integer(string))
+    end
+  private
+    def deserialize_one
+      # Now deserialize one message from the buffer in io
+      serializer.de(pipe.r)
+    end
+  end
+end

data/lib/cod/select.rb

@@ -0,0 +1,47 @@
+module Cod
+  def select(timeout, groups)
+    Select.new(timeout, groups).do
+  end
+  module_function :select
+  
+  # Performs an IO.select on a list of file descriptors and Cod channels. 
+  # Construct this like so: 
+  #   Select.new(
+  #     0.1,                    # timeout
+  #     foo: single_fd,         # a single named FD
+  #     bar: [one, two, three], # a group of FDs.
+  #   )
+  #
+  class Select
+    attr_reader :timeout
+    attr_reader :groups
+    
+    def initialize(timeout, groups)
+      @timeout = timeout
+      @groups = SelectGroup.new(groups)
+    end
+    
+    # Performs the IO.select and returns a thinned out version of that initial
+    # groups, containing only FDs and channels that are ready for reading. 
+    #
+    def do
+      fds = groups.values { |e| to_read_fd(e) }
+      
+      # Perform select  
+      r,w,e = IO.select(fds, nil, nil, timeout)
+
+      # Nothing is ready if r is nil
+      return groups.empty unless r
+      
+      # Prepare a return value: The original hash, where the fds are ready.
+      groups.
+        keep_if { |e| r.include?(to_read_fd(e)) }.
+        unpack
+    end
+  private
+    def to_read_fd(single)
+      return single.to_read_fds if single.respond_to?(:to_read_fds)
+      return single
+    end
+  end
+end

data/lib/cod/select_group.rb

@@ -0,0 +1,87 @@
+module Cod
+  # A select group is a special kind of hash, basically. It contains group
+  # names as keys (probably symbols) and has either array values or single 
+  # object instances. 
+  # 
+  # A number of operations is defined to make it easier to filter such 
+  # hashes during IO.select. The API user only ever gets to see the resulting
+  # hash.
+  #
+  class SelectGroup # :nodoc:
+    def initialize(hash_or_value)
+      if hash_or_value.respond_to?(:each)
+        @h = hash_or_value
+        @unpack = false
+      else
+        @h = {box: hash_or_value}
+        @unpack = true
+      end
+    end
+    
+    # Returns all values as a single flat array. NOT like Hash#values.
+    #
+    def values(&block)
+      values = []
+      block ||= lambda { |e| e } # identity
+      
+      @h.each do |_,v|
+        if v.respond_to?(:to_ary)
+          values << v.map(&block)
+        else
+          values << block.call(v)
+        end
+      end
+      values.flatten
+    end
+    
+    # Keeps values around with their respective keys if block returns true
+    # for the values. Deletes everything else. NOT like Hash#keep_if.
+    #
+    def keep_if(&block)
+      old_hash = @h
+      @h = Hash.new
+      old_hash.each do |key, values|
+        # Now values is either an Array like structure that we iterate 
+        # on or it is a single value. 
+        if values.respond_to?(:to_ary)
+          ary = values.select { |e| block.call(e) }
+          @h[key] = ary unless ary.empty?
+        else
+          value = values
+          @h[key] = value if block.call(value)
+        end
+      end
+      
+      self
+    end
+    
+    # EXACTLY like Hash#keys.
+    def keys
+      @h.keys
+    end
+
+    # Converts this to a result value. If this instance was constructed with a 
+    # simple ruby object, return the object. Otherwise return the resulting
+    # hash.
+    #
+    def unpack
+      if @unpack
+        @h[:box]
+      else
+        @h
+      end
+    end
+    
+    # Returns something that will represent the empty result to our client. 
+    # If this class was constructed with just a single object, the empty 
+    # result is nil. Otherwise the empty result is an empty hash. 
+    #
+    def empty
+      if @unpack
+        nil
+      else
+        {}
+      end
+    end
+  end
+end