em-rserve 0.1.1 → 0.1.2

data/TODO

@@ -8,7 +8,6 @@
 * login command
   support crypt and store salt from connection setup
 * better attach method
-* write doc
 * more spec once the RServe spec is better understood/have enough examples
 * subclass Request for each commmand instead of current quick'n dirty mechanism
 * better test requests stacking/unstacking

data/em-rserve.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |s|
   s.version     = EM::Rserve::VERSION
   s.authors     = ["crapooze"]
   s.email       = ["crapooze@gmail.com"]
-  s.homepage    = ""
+  s.homepage    = "https://github.com/crapooze/em-rserve"
   s.summary     = %q{An EventMachine client for RServe}
   s.description = %q{Do evented stats with EventMachine and RServe}
 

data/lib/em-rserve/backend.rb

@@ -0,0 +1,44 @@
+
+module EM::Rserve
+  # A Backend is a way to specify connection parameters.
+  # The Pooler rely on a Backend to feed him the list of places to connect.
+  class Backend
+    include Enumerable
+
+    # A Server just holds an host and a port.
+    Server = Struct.new(:host, :port)
+
+    def initialize
+      yield self if block_given?
+    end
+
+    def next
+      raise NotImplementedError, "you should use subclasses of Backend"
+    end
+  end
+
+  # The default backend: an RServe running on localhost and default port (6311)
+  class DefaultBackend < Backend
+    def initialize
+      super
+      @server = Server.new('127.0.0.1', 6311).freeze
+    end
+
+    def next
+      @server
+    end
+  end
+
+  # Round-robin looping on servers
+  class RoundRobinBackend < Backend
+    def initialize(servers)
+      super()
+      raise ArgumentError, "need at least one server" if servers.empty?
+      @servers = servers
+    end
+
+    def next
+      @servers.unshift(@servers.pop).first
+    end
+  end
+end

data/lib/em-rserve/connection.rb

@@ -7,10 +7,18 @@ require "em-rserve/qap1/header"
 require "em-rserve/qap1/message"
 
 module EM::Rserve
+  # A Connection speaks to RServe using the methods in Protocol::Connector
+  # In addition, a Connection implements helper methods to call RServe commands.
   class Connection < EM::Connection
     include Protocol::Connector
     include QAP1
 
+    # Asks the server to close the connection.
+    # Note that this does not close the TCP connection yet because you will
+    # receive an acknowledgement first.
+    #
+    # Returns and pass to the optional block a new Request instance. See
+    # Protocol::Connector#request.
     def shutdown!(&blk)
       header = Header.new(Constants::CMD_shutdown,0,0,0)
       send_data header.to_bin
@@ -18,6 +26,10 @@ module EM::Rserve
       request(&blk) 
     end
 
+    # Evaluates a R-code string in the R session
+    #
+    # Returns and pass to the optional block a new Request instance. See
+    # Protocol::Connector#request.
     def r_eval(string, void=false,&blk)
       data = Message.encode_string(string)
       if void
@@ -31,7 +43,11 @@ module EM::Rserve
       request(&blk)
     end
 
-    def login(user,pwd, crypted=true, &blk)
+    # Logs-in if the RServe connection asks for a user/password pair
+    #
+    # Returns and pass to the optional block a new Request instance. See
+    # Protocol::Connector#request.
+    def login(user, pwd, crypted=true, &blk)
       raise NotImplementedError, "will come later"
       #XXX need to read the salt during connection setup
       cifer = crypted ? pwd : crypt(pwd, salt)
@@ -43,6 +59,11 @@ module EM::Rserve
       request(&blk)
     end
 
+    # Detaches current session, the response will hold a key to later re-attach
+    # the session.
+    #
+    # Returns and pass to the optional block a new Request instance. See
+    # Protocol::Connector#request.
     def detach(&blk)
       header = Header.new(Constants::CMD_detachSession, 0, 0, 0)
       send_data header.to_bin #port, key of 20 bytes
@@ -50,16 +71,28 @@ module EM::Rserve
       request(&blk)
     end
 
+    # Attaches to the session using the secret key.
+    #
+    # Returns and pass to the optional block a new Request instance. See
+    # Protocol::Connector#request.
     def attach(key, &blk)
-      #XXX it seems that there is no need to send a Header + Message, and
-      #raw_writing because the server does a read of 32 bytes on newly accepted
-      #connections
-      raise ArgumentError, "wrong key length, Rserve wants 32bytes" unless key.size == 32
+      #XXX it seems that there is no need to send a Header + Message. We can
+      #just write the key because the RServe code does a read of 32 bytes on newly
+      #accepted connections and tests the key.
+      raise ArgumentError, "wrong key length, Rserve wants 32bytes" unless key.size == 32 
       send_data key
 
       request(&blk)
     end
 
+    # Assign an R object (represented by a Ruby instance of Sexp) to a symbol
+    # within the context of the connection.  symbol must respond to :to_s, this
+    # value will be the symbol name in R.
+    # If parse_symbol_name is true, RServe will verify whether the R symbol is
+    # a legal symbol.
+    #
+    # Returns and pass to the optional block a new Request instance. See
+    # Protocol::Connector#request.
     def assign(symbol, sexp_node, parse_symbol_name=true, &blk)
       data = Message.new([symbol.to_s, sexp_node]).to_bin
       data << "\xFF" * data.length % 4

data/lib/em-rserve/fibered_connection.rb

@@ -3,20 +3,48 @@ require "fiber"
 require "em-rserve/connection"
 
 module EM::Rserve
+# A FiberedConnection is a type of EM::RServe::Connection but it handles every
+# connection in a Ruby Fiber.
+# This class also implements many high-level methods such that you don't have to understand the in and out of Ruby Fiber.
+#
+# It is usually enough to use the connection this way:
+# EM.run do
+#    Fiber.new do
+#      conn = FiberedConnection.new
+#      conn[:foo] = [1, 2, 3, 4]
+#      conn[:bar] = [1, 2, 3, 4]
+#      puts conn.call('cor(foo, bar)')
+#    end.resume
+#  end
+#
+# For some context, please read http://www.igvita.com/2010/03/22/untangling-evented-code-with-ruby-fibers/
 class FiberedConnection < EM::Rserve::Connection
+
+  # The Fiber holding the context for this connection
   attr_accessor :fiber
 
+  # Starts a new connection, the first parameter is a Fiber to hold the context
+  # of the connection, defaults to current fiber.
+  # This fiber cannot be the root Fiber.
+  # Remaining parameters are the same than in EM::Rserve::Connection.start
   def self.start(fiber=Fiber.current, *args)
     conn = super(*args)
     conn.fiber = fiber
     Fiber.yield 
   end
 
+  # Called when ready, resume the Fiber execution
   def ready
     super
     fiber.resume self if fiber
   end
 
+  # Evaluates a piece of R script and returns:
+  # - script is a string (or an object that we'll transform to a string with :to_s)
+  # - nil if the script doesn't return anything (it often does but not on)
+  # - a Ruby object coming from the translation of a Sexp which represents an R object 
+  # - WARNING: current version also return nil on error 
+  # Blocks the Fiber but not the event loop.
   def call(script, *args)
     r_eval(script.to_s, *args) do |req|
       req.errback do |err|
@@ -40,6 +68,10 @@ class FiberedConnection < EM::Rserve::Connection
     Fiber.yield
   end
 
+  # Sets a symbol to a val in the R context.
+  # sym will be passed verbatim to EM::Rserve::Connection#assign
+  # val is a Ruby object that will get translated to a Sexp which represents an R object
+  # Blocks the Fiber but not the event loop.
   def set(sym, val)
     root = EM::Rserve::R::RubytoR::Translator.ruby_to_r val
 
@@ -55,7 +87,15 @@ class FiberedConnection < EM::Rserve::Connection
     Fiber.yield
   end
 
-  # *WARNING* this method is unsafe always check your input parameter
+  # Same thing as call, RServe doesn't provide a way to read the value of a
+  # symbol although it provides a way of writing a symbol. Hence, we just
+  # evaluate a script with the name of the symbol.
+  # A sad side effect is the following warning:
+  #
+  # *WARNING* this method is unsafe because it evaluates arbitrary R Code.
+  # Always check that your input parameter looks like an R symbol. 
+  #
+  # Blocks the Fiber but not the event loop.
   def get(sym)
     call(sym)
   end

data/lib/em-rserve/pooler.rb

@@ -1,13 +1,21 @@
 
 require "em-rserve/fibered_connection"
+require "em-rserve/backend"
 
 module EM::Rserve
+  # A Pooler is a pool of already ready FiberedConnections as new RServe
+  # connections are requested, new fibers/connections are added.
+  # There is currently no limitation on the maximum number of establish
+  # connections, but just a limit on the minimum pre-established connections
   class Pooler
     class << self
-      def r(klass=FiberedConnection)
+      # Immediately creates and yields a new connection of class klass.
+      # Shorthand method to create one connection wrapped in a Fiber.
+      def r(klass=FiberedConnection, backend=DefaultBackend.new)
         Fiber.new do
           begin
-            conn = klass.start 
+            server = backend.next
+            conn = klass.start(Fiber.current, server.host, server.port)
             yield conn
           ensure
             conn.close_connection
@@ -16,29 +24,50 @@ module EM::Rserve
       end
     end
 
-    attr_reader :connections, :size, :connection_class
-    def initialize(size=10, klass=FiberedConnection)
+    # An array of pending connections
+    attr_reader :connections
+    # The minimum number of connections to maintain
+    attr_reader :size
+    # The klass to use when instanciating new connections
+    attr_reader :connection_class
+    # The backend, which says on which host/port to connect to
+    attr_reader :backend
+
+    # Initializes and pre-establish size connections of class klass
+    def initialize(size=10, klass=FiberedConnection, backend=DefaultBackend.new)
       @connections = []
       @size = size
       @connection_class = klass
+      @backend = backend
       fill size
     end
 
+    # True if there are no connections left in the pool
     def empty?
       connections.empty?
     end
 
+    # True if there are at least size connections in the pool
     def full?
       connections.size >= size
     end
 
+    # Creates and yields a new connection in a Fiber
     def connection
       #XXX duplicated code from Pooler.r to avoid proc-ing the blk
       Fiber.new do
-        yield connection_class.start
+        server = backend.next
+        yield connection_class.start(Fiber.current, server.host, server.port)
       end.resume
     end
 
+    # Pick and yield a new connection from the connections pool.
+    # If the pool, yield a new connection.
+    #
+    # This method also ensure that the TCP connection is closed once the work
+    # is finished.
+    #
+    # It also re-establish new connections, trying to maintain the pool filled.
     def r
       conn = connections.shift
       if conn
@@ -63,6 +92,8 @@ module EM::Rserve
       end
     end
 
+    # Preconnect a connection, once the connection is ready, it is added to the
+    # connections pool.
     def preconnect!
       connection do |conn|
         conn.fiber = nil
@@ -70,6 +101,7 @@ module EM::Rserve
       end
     end
 
+    # Shorthand to preconnect n connections in parallel.
     def fill(n=size)
       n.times{preconnect!}
     end

data/lib/em-rserve/protocol/connector.rb

@@ -10,6 +10,7 @@ module EM::Rserve
       end
 
       module ClassMethods
+        # Starts a new TCP connection to the server/port parameters
         def start(server='127.0.0.1', port=6311)
           EM.connect(server, port, self)
         end
@@ -17,8 +18,16 @@ module EM::Rserve
 
       extend ClassMethods
 
+      # FIFO for pending requests.
+      #
+      # RServe protocol implements a synchronous request/response scheme over a
+      # single TCP stream. Thus we can hold contexts in a FIFO array of requests
+      # to the same server 
       attr_accessor :request_queue
 
+      # Implements EM::Connection post_init hook:
+      # - sets the parser to parse IDs
+      # - create a request_queue
       def post_init
         super
         #type of parser carries the state, no need to carry it internally and do
@@ -28,6 +37,17 @@ module EM::Rserve
         @request_queue = []
       end
 
+      # Creates and appends a new request to the request_queue
+      # If a block is given, it will be called and the new request will be
+      # passed as argument.  
+      # Also returns the newly created request.
+      #
+      # r = connector.request
+      # r.success{ p 'good' }
+      #
+      # connector.request do |r|
+      #   r.success{p 'good'}
+      # end
       def request
         r = Request.new
         yield r if block_given?
@@ -35,6 +55,16 @@ module EM::Rserve
         r
       end
 
+      # Replaces current Parser by a new Parser.
+      # The klass parameter gives the class to instanciate.
+      # Instanciation of the new parser will receive self as only parameter.
+      # If the hold parser holds data in its buffer, we may lose this data, hence
+      # we call Parser#replace to correctly hand-over the parsing.
+      # Note that this complication comes from the RServe protocol which has an
+      # initialization phase.
+      # Rather than holding the state and testing whether the connection is
+      # initialized or not each time we receive a byte, once the initialization
+      # phase is done, we just change the parser.
       def replace_parser!(klass)
         new_parser = klass.new(self)
         if @parser
@@ -43,10 +73,12 @@ module EM::Rserve
         @parser = new_parser
       end
 
+      # Implements EM::Connection receive_data hook, just forwarding to the parser.
       def receive_data(dat)
         @parser << dat
       end
 
+      # Implements IDParser's receive_id callback.
       def receive_id(id)
         # on last line, the messaging can start
         if id.last_one?
@@ -60,9 +92,16 @@ module EM::Rserve
 
       # HOOKS TO OVERRIDE, PLEASE CALL SUPER
 
+      # This method gets called whenever the connection is started and initialized.
+      # By default, it does nothing, you don't need to call super when
+      # overriding this method.
       def ready
       end
 
+      # Implements MessageParser's callback.
+      # This method gets called whenever the server start answering with a
+      # message header.  
+      # If you override this method, call super first.
       def receive_message_header(head)
         if head.error?
           receive_error_message_header(head)
@@ -73,14 +112,28 @@ module EM::Rserve
         end
       end
 
+      # This method gets called by receive_message_header if the header is an
+      # error.  It dequeues the request_queue FIFO and calls its error method
+      # with the header as only parameter.
+      # If you override this method, call super first.
       def receive_error_message_header(head)
         request_queue.shift.error(head)
       end
 
+      # This method gets called by receive_message_header if the header is an error.
+      # If the header tells us there is no more data to answer this request
+      # (i.e., there will be no body data), dequeues the request_queue FIFO and
+      # calls the success method with "nil" as only parameter.
+      # If you override this method, call super first.
       def receive_success_message_header(head)
         request_queue.shift.success(nil) unless head.body?
       end
 
+      # Implements MessageParser's callback.
+      # This methods gets called whenever a message was completely received.
+      # Dequeues the request_queue FIFO and calls the success method with the
+      # message as only parameter.
+      # If you override this method, call super first.
       def receive_message(msg)
         request_queue.shift.success(msg)
       end

data/lib/em-rserve/protocol/parser.rb

@@ -6,24 +6,38 @@ require 'em-rserve/r/sexp'
 
 module EM::Rserve
   module Protocol
+    # Top class for parsers.
     class Parser
-      attr_reader :handler, :buffer
+      # A handler is an object which will receive method calls from parsers on
+      # specific events.
+      attr_reader :handler
 
+      # A buffer holding data.
+      attr_reader :buffer
+
+      # Initializes a new Parser and stores the handler.
       def initialize(handler)
         @handler = handler
         @buffer  = ''
       end
 
+      # Replaces current buffer with other's parser's buffer.
+      # This is useful when handing-over from one type of parsing to another.
       def replace(other)
         @buffer.replace(other.buffer)
         self
       end
 
+      # Input some data to the parser. As there is new data, will start a
+      # parsing loop by calling parse_loop!
       def << data
         buffer << data if data
         parse_loop!
       end
 
+      # Infinitely calls the parse! method (to override in subclasses of parsers).
+      # To get out of the loop (e.g., when we realize that there is not enough
+      # data in the buffer to complete a message), one must throw :stop .
       def parse_loop!
         catch :stop do
           loop do
@@ -42,6 +56,8 @@ module EM::Rserve
     # This parser is useful only at the beginning.
     # Instead of carrying its dynamic all the time (e.g., keeping a state).
     # We pop-it out as another parser.
+    #
+    # This parser's handler must respond_to :receive_id
     class IDParser < Parser
       def parse!
         if buffer.size >= 4
@@ -55,6 +71,8 @@ module EM::Rserve
     end
 
     # This message parser will parse qap1 headers and associated qap1 data.
+    #
+    # This parser's handler must respond_to :receive_message and :receive_message_header
     class MessageParser < Parser
       def initialize(handler)
         super(handler)

data/lib/em-rserve/protocol/request.rb

@@ -1,19 +1,24 @@
 
 module EM::Rserve
   module Protocol
+    # Simple Request structure holding a references to a callback and an errback
     Request = Struct.new(:callback_blk, :errback_blk) do
+      # sets the async callback with a block argument
       def callback(&blk)
         self.callback_blk = blk
       end
 
+      # sets the async errback with a block argument
       def errback(&blk)
         self.errback_blk = blk
       end
 
+      # calls the errback 
       def error(val)
         errback_blk.call(val) if errback_blk
       end
 
+      # calls the callback
       def success(val)
         callback_blk.call(val) if callback_blk
       end

data/lib/em-rserve/version.rb

@@ -1,5 +1,5 @@
 module EM
   module Rserve
-    VERSION = "0.1.1"
+    VERSION = "0.1.2"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: em-rserve
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-10-21 00:00:00.000000000Z
+date: 2011-10-22 00:00:00.000000000Z
 dependencies: []
 description: Do evented stats with EventMachine and RServe
 email:
@@ -25,6 +25,7 @@ files:
 - TODO
 - em-rserve.gemspec
 - lib/em-rserve.rb
+- lib/em-rserve/backend.rb
 - lib/em-rserve/connection.rb
 - lib/em-rserve/fibered_connection.rb
 - lib/em-rserve/pooler.rb
@@ -52,7 +53,7 @@ files:
 - specs/parser_spec.rb
 - specs/ruby_to_r_translator_spec.rb
 - specs/spec_helper.rb
-homepage: ''
+homepage: https://github.com/crapooze/em-rserve
 licenses: []
 post_install_message: 
 rdoc_options: []