cod 0.3.1 → 0.4.0

data/lib/cod/service.rb

@@ -1,60 +1,73 @@
-
 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' }
+  # Cod::Service abstracts the pattern where you send a request to a central
+  # location (with possibly multiple workers handling requests) and receive an
+  # answer. It solves problems related to timeouts, getting _your_ answer and
+  # not any kind of answer, etc... 
   # 
-  #   # client side
-  #   client = Cod::Client.new(incoming_channel, service_channel)
-  #   client.call('call message') # => 'answer'
+  # Synopsis: 
+  #   # On the server end: 
+  #   service = Cod.service(central_location)
+  #   service.one { |request| :answer }
+  #
+  #   # On the client end: 
+  #   service = Cod.client(central_location, answer_here)
+  #
+  #   # asynchronous, no answer
+  #   service.notify [:a, :request]   # => nil
+  #   # has an answer: 
+  #   service.call [:a, :request]   # => :answer
+  #
+  # Depending on the setup of the channels, this class can be used to
+  # implement intra- and interprocess communication, very close to RPC. There
+  # are two ways to build on this: 
   #
-  # == Topology
+  # * Using method_missing, implement real RPC on top. This is usually rather
+  #   simple (since Cod does a lot of work), see github.com/kschiess/zack for
+  #   an example of this.
   # 
-  # 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. 
+  # * Using the 'case' gem, implement servers in an (erlang) actor like
+  #   fashion. 
   #
   class Service
-    # Incoming channel for requests.
-    attr_reader :incoming
-    
     def initialize(channel)
-      @incoming = channel
+      @channel = channel
     end
     
-    # Calls the given block with the next request and returns the block answer
-    # to the service client. 
+    # Waits until a request arrives on the service channel. Then reads that
+    # request and hands it to the block given. The block return value
+    # will be returned to the service client. 
+    #
+    # Use Cod::Client to perform the service call. This will keep track of 
+    # messages sent and answers received and a couple of other things. 
+    # 
     #
     def one
-      request_id, message, answer_channel, needs_answer = incoming.get      
+      rq, answer_chan = @channel.get
+      res = yield(rq)
+      answer_chan.put res if answer_chan
+    end
+
+    # A service client. 
+    #
+    class Client
+      def initialize(server_chan, answer_chan=nil)
+        @server_chan, @answer_chan = server_chan, answer_chan || server_chan
+      end
       
-      answer = yield(message)
+      def call(rq)
+        @server_chan.put [rq, @answer_chan]
+        @answer_chan.get
+      end
       
-      if needs_answer
-        answer_channel.put [request_id, answer]
+      def notify(rq)
+        @server_chan.put [rq, nil]
       end
-    end
-    
-    # Loops forever, yielding requests to the block given and returning the 
-    # answers to the client.
-    #
-    def each(&block)
-      loop do
-        one(&block)
+      
+      def close
+        @server_chan.close
+        @answer_chan.close
       end
     end
-    
-    # Releases all resources held by the service. 
-    #
-    def close
-      incoming.close
-    end
   end
+  
 end

data/lib/cod/simple_serializer.rb

@@ -0,0 +1,19 @@
+module Cod
+  # The simplest of all serializers, one that uses Marshal.dump and
+  # Marshal.load as a message format. Use this as a template for your own wire
+  # format serializers.
+  #
+  class SimpleSerializer
+    def en(obj)
+      Marshal.dump(obj)
+    end
+    
+    def de(io)
+      if block_given?
+        Marshal.load(io, Proc.new)
+      else
+        Marshal.load(io)
+      end
+    end
+  end
+end

data/lib/cod/tcp_client.rb

@@ -0,0 +1,202 @@
+require 'cod/work_queue'
+
+module Cod
+  # Acts as a channel that connects to a tcp listening socket on the other
+  # end. 
+  #
+  class TcpClient < Channel
+    def initialize(destination, serializer)
+      @serializer = serializer
+      @destination = destination
+
+      # TcpClient handles two cases: Construction via an url (destination is a
+      # string) and construction via a connection that has been
+      # preestablished (destination is a socket):
+      if destination.respond_to?(:read)
+        # destination seems to be a socket, wrap it with Connection
+        @connection = Connection.new(destination)
+      else
+        @connection = RobustConnection.new(destination)
+      end
+
+      @work_queue = WorkQueue.new
+
+      # The predicate for allowing sends: Is the connection up?
+      @work_queue.predicate {
+        # NOTE This will not be called unless we have some messages to send,
+        # so no useless connections are made
+        @connection.try_connect
+        @connection.established?
+      }
+    end
+    
+    # Closes all underlying connections. You should only call this if you
+    # don't want to use the channel again, since it will also stop
+    # reconnection attempts. 
+    #
+    def close
+      @work_queue.shutdown
+      @connection.close
+    end
+
+    # Sends an object to the other end of the channel, if it is connected. 
+    # If it is not connected, objects sent will queue up and once the internal
+    # storage reaches the high watermark, they will be dropped silently. 
+    #
+    # Example: 
+    #   channel.put :object
+    #   # Really, any Ruby object that the current serializer can turn into 
+    #   # a string!
+    #
+    def put(obj)
+      # TODO high watermark check
+      # NOTE: predicate will call #try_connect
+      @work_queue.schedule {
+        send(obj)
+      }
+      
+      @work_queue.try_work
+    end
+    
+    # Receives a message. opts may contain various options, see below. 
+    # Options include: 
+    #
+    def get(opts={})
+      @connection.try_connect
+      @connection.read(@serializer)
+    end
+
+    # --------------------------------------------------------- service/client
+    
+    def service
+      fail "A tcp client cannot be a service."
+    end
+    def client
+      # NOTE: Normally, it doesn't make sense to ask the client channel for
+      # something for a service connection, since the service needs to know
+      # where to send requests in addition to knowing where to receive
+      # answers. In the case of sockets, this is different: The service will
+      # send its answers back the same way it got the requests from, so this
+      # is really ok:
+      #
+      Service::Client.new(self, self)
+    end
+
+    # ---------------------------------------------------------- serialization 
+    
+    # A small structure that is constructed for a serialized tcp client on 
+    # the other end (the deserializing end). What the deserializing code does
+    # with this is his problem. 
+    #
+    OtherEnd = Struct.new(:destination) # :nodoc:
+
+    def _dump(level) # :nodoc:
+      @destination
+    end
+    def self._load(params) # :nodoc:
+      # Instead of a tcp client (no way to construct one at this point), we'll
+      # insert a kind of marker in the object stream that will be replaced 
+      # with a valid client later on. (hopefully)
+      OtherEnd.new(params)
+    end
+  private
+    def send(msg)
+      @connection.write(
+        @serializer.en(msg))
+    end
+
+    # A connection that can be down. This allows elegant handling of
+    # reconnecting and delaying connections. 
+    #
+    # Synopsis: 
+    #   connection = RobustConnection.new('foo:123')
+    #   connection.try_connect
+    #   connection.write('buffer')
+    #   connection.established? # => false
+    #   connection.close
+    #
+    class RobustConnection # :nodoc: 
+      def initialize(destination)
+        @destination = destination
+        @socket = nil
+      end
+      
+      attr_reader :destination
+      attr_reader :socket
+      
+      # Returns true if a connection is currently running. 
+      #
+      def established?
+        !! @socket
+      end
+      
+      # Attempt to establish a connection. If there is already a connection
+      # and it still seems sound, does nothing. 
+      #
+      def try_connect
+        return if established?
+        
+        @socket = TCPSocket.new(*destination.split(':'))
+      rescue Errno::ECONNREFUSED
+        # No one listening? Well.. too bad.
+        @socket = nil
+      end
+      
+      # Writes a buffer to the connection if it is established. Otherwise
+      # fails silently. 
+      #
+      def write(buffer)
+        if @socket
+          @socket.write(buffer)
+        end
+      end
+      
+      # Reads one message from the socket if possible. 
+      #
+      def read(serializer)
+        return serializer.de(@socket) if @socket
+        
+        # assert: @socket is still nil, because no connection could be made. 
+        # Try to make one
+        loop do
+          try_connect
+          return serializer.de(@socket) if @socket
+          sleep 0.01
+        end
+      end
+
+      # Closes the connection and stops reconnection. 
+      #
+      def close
+        @socket.close if @socket
+        @socket = nil
+      end
+    end
+    
+    # Holds a connection that we don't create and therefore don't own. This
+    # is the case where a channel is created to communicate back to one of
+    # the TcpServers clients: the tcp server manages the back channels, so
+    # the created channel is lent its socket only.
+    #
+    class Connection # :nodoc:
+      def initialize(socket)
+        @socket = socket.dup
+      end
+      attr_reader :socket
+      def try_connect
+      end
+      def established?
+        true
+      end
+      def read(serializer)
+        serializer.de(@socket)
+      end
+      def write(buffer)
+        @socket.write(buffer)
+      end
+      def close
+        @socket.close
+      end
+    end
+  end
+end

data/lib/cod/tcp_server.rb

@@ -0,0 +1,124 @@
+module Cod
+  class TcpServer
+    def initialize(bind_to)
+      @socket = TCPServer.new(*bind_to.split(':'))
+      @client_sockets = []
+      @round_robin_index = 0
+      @messages = Array.new
+      @serializer = SimpleSerializer.new
+    end
+    
+    # Receives one object from the channel. 
+    #
+    # Example: 
+    #   channel.get # => object
+    #   
+    def get(opts={})
+      msg, socket = _get(opts)
+      return msg
+    end
+    
+    # Receives one object from the channel. Returns a tuple of
+    # <message,channel> where channel is a tcp channel that links back to the
+    # client that sent message.
+    #
+    # Using this method, the server can communicate back to its clients
+    # individually instead of collectively. 
+    #
+    # Example: 
+    #   msg, chan = server.get_ext
+    #   chan.put :answer
+    def get_ext(opts={})
+      msg, socket = _get(opts)
+      return [
+        msg, 
+        TcpClient.new(socket, @serializer)]
+    end
+    
+    # Closes the channel. 
+    #
+    def close
+      @socket.close
+      @client_sockets.each { |io| io.close }
+    end
+
+    # Returns an array of IOs that Cod.select should select on. 
+    #
+    def to_read_fds
+      @client_sockets
+    end
+
+    # --------------------------------------------------------- service/client
+    
+    def service
+      Service.new(self)
+    end
+    # NOTE: It is really more convenient to just construct a Cod.tcp_client 
+    # and ask that for a client object. In the case of TCP, this is enough. 
+    #
+    def client(answers_to)
+      Service::Client.new(answers_to, answers_to)
+    end
+
+  private
+    def _get(opts)
+      loop do
+        # Check if there are pending connects
+        accept_new_connections
+
+        # shuffle the socket list around, so we don't always read from the
+        # same client.
+        socket_list = round_robin(@client_sockets)
+
+        # select for readiness
+        rr, rw, re = IO.select(socket_list, nil, nil, 0.1)
+        next unless rr
+        
+        rr.each do |io|
+          consume_pending io, opts
+        end
+        
+        return @messages.shift unless @messages.empty?
+      end
+    end
+  
+    def consume_pending(io, opts)
+      until io.eof?
+        @messages << [
+          deserialize(io), 
+          io]
+          
+        # More messages from this socket? 
+        return unless IO.select([io], nil, nil, 0.01)
+      end
+    end
+    
+    def deserialize(io)
+      @serializer.de(io) { |obj|
+        obj.kind_of?(TcpClient::OtherEnd) ? 
+          TcpClient.new(io, @serializer) :
+          obj
+      }
+    end
+    
+    def round_robin(list)
+      @round_robin_index += 1
+      if @round_robin_index >= list.size
+        @round_robin_index = 0
+      end
+      
+      # Create a duplicate of list that has its elements rotated by
+      # @round_robin_index
+      list = list.dup
+      list = list + list.shift(@round_robin_index)
+    end
+    
+    def accept_new_connections
+      loop do
+        @client_sockets << @socket.accept_nonblock
+      end
+    rescue Errno::EAGAIN
+      # This means that there are no sockets to accept. Continue.
+    end
+  end
+end