brb 0.2.2 → 0.3.0

data/CHANGELOG.rdoc

@@ -1,3 +1,9 @@
+0.3.0 (May 21, 2010)
+
+* Added Callback functionality through block
+* Added Callback example
+* Little spec refactoring
+
 0.2.2 (Apr 21, 2010)
 
 * Change silent option to verbose

data/README.rdoc

@@ -1,17 +1,16 @@
 = BrB - Easy and Fast distributed ruby
 
-BrB is a simple, fully transparent and extremely fast interface for doing simple distributed ruby.
-The main power of the architecture is provided by EventMachine (Fast and reliable IO event library).
+BrB is a simple, fully transparent and extremely fast interface for doing simple distributed Ruby.
+The core of the architecture is provided by EventMachine  (a fast and reliable IO event library).
 
-BrB was build in order to achieve these 4 main goals :
-* Simple and fast message passing between distant ruby process.
-* Message passing with handling of return value when needed.
-* Being extremely fast in order to handle more than a few thousand messages per seconds.
+BrB was built in order to achieve these 4 main goals :
+* Simple and fast message passing between distant Ruby processes.
+* Message passing with of return values when needed.
+* Being extremely fast in order to handle more than a few thousand messages per second.
 * Being completely transparent for developer.
 
-The principle is simple and inspired from Drb (Original distributed ruby library) :
-A process want to expose an object on the network, and want other ruby processes calling directly method on it.
-BrB handle all that part, it's fully transparent in the ruby code.
+The principle is simple and inspired from Drb (standard distributed ruby library) :
+A process exposes an object over the network and any ruby process (after having established a connection tunnel) can directly call a method on the exposed object. BrB handles that part, so it’s fully transparent in the Ruby code.
 
 BrB only support message passing with Marshable dumpable object : String, symbol, Array, hash, Number, Object etc...
 That mean you can not send file descriptor, Thread or another funky things like that :)
@@ -21,7 +20,8 @@ That mean you can not send file descriptor, Thread or another funky things like
 * Unlimited objects exposed
 * Processes can expose object and be client to exposed object too at the same time
 * Do not wait for return by default : just do simple message passing
-* Wait for return if needed by simply adding <em>_block</em> at the end of the function name
+* Handle return values without blocking with the usage of a simple block
+* Blocking wait for return if needed by simply adding <em>_block</em> at the end of the method name
 * Transmission of Exception when blocking call
 * Thread safe if used correctly with Event Machine
 
@@ -31,7 +31,7 @@ First of all, a process declare himself as a sever and expose any object on a gi
 Then, any number of distant processes can create a <em>Tunnel</em> with that server and can expose an object in exchange too.
 After connection are ready, just call method on the tunnel. It will just act like normal method calling on the exposed object !
 
-== What BrB is usable for ?
+== What BrB is designed for ?
 
 * Doing Simple message passing between ruby process.
 * Connecting hundred of ruby process transparently.

data/Rakefile

@@ -7,7 +7,7 @@ spec_files = Rake::FileList["spec/**/*_spec.rb"]
 desc "Run specs for current Rails version"
 Spec::Rake::SpecTask.new do |t|
   t.spec_files = spec_files
-  t.spec_opts = ["-c"]
+  t.spec_opts = ["-c --format specdoc"]
 end
 
 task :default => :spec

data/examples/simple_client.rb

@@ -26,6 +26,14 @@ puts " >> Calling long call, and wait for response..."
 r = core.simple_long_api_method_block
 puts " > Api long response : #{r}"
 
+## Calling method with a callback block for handling the return value
+core.simple_api_method do |r|
+  puts " > Get the callback response : #{r}"
+end
+
+puts " >> Callback method has been called continue .."
+sleep 2
+
 core.stop_service
 
 # Our job is over, close event machine :

data/examples/simple_core.rb

@@ -4,6 +4,7 @@ class ExposedCoreObject
   
   def simple_api_method
     puts "#{Thread.current} > In simple api method, now sleeping"
+    yield if block_given?
     sleep 1
     puts "#{Thread.current} > Done sleeping in simple api method, return"
     return 'OK'

data/lib/brb/exception.rb

@@ -1 +1,9 @@
-# Future BrB custom exceptions will come here
+# Future BrB custom exceptions will come here
+class BrBException < Exception
+end
+
+class BrBCallbackWithBlockingMethodException < BrBException
+  def initialize
+    super('Out request can not be blocking and have a callback at the same time !')
+  end
+end

data/lib/brb/request.rb

@@ -1,5 +1,9 @@
 module BrB
   module Request
+    
+    MessageRequestCode  = :s
+    CallbackRequestCode = :c
+    ReturnCode          = :r
 
     def is_brb_request_blocking?(meth)
       if m = meth.to_s and m.rindex('_block') == (m.size - 6)
@@ -9,23 +13,34 @@ module BrB
     end
 
     # Execute a request on a distant object
-    def new_brb_out_request(meth, *args)
+    def new_brb_out_request(meth, *args, &blck)
       Thread.current[:brb_nb_out] ||= 0
       Thread.current[:brb_nb_out] += 1
 
-      block = is_brb_request_blocking?(meth) ? Thread.current.to_s.to_sym : nil
+      raise BrBCallbackWithBlockingMethodException.new if is_brb_request_blocking?(meth) and block_given?
+
+      block = (is_brb_request_blocking?(meth) or block_given?) ? Thread.current.to_s.to_sym : nil
       if block
         args << block 
         args << Thread.current[:brb_nb_out]
       end
+      
+      if block_given?
+        # Simulate a method with _block in order to make BrB send the answer
+        meth = "#{meth}_block".to_sym
+      end
 
-      args.size > 0 ? brb_send([:s, meth, args]) : brb_send([:s, meth])
+      args.size > 0 ? brb_send([MessageRequestCode, meth, args]) : brb_send([MessageRequestCode, meth])
+
+      if block_given?
+        # Declare the callback
+        declare_callback(block, Thread.current[:brb_nb_out], &blck)
+
+      elsif block # Block until the request return
 
-      # Block jusqu'au retour de la requete
-      if block
         #TimeMonitor.instance.watch_thread!(@timeout_rcv_value || 45)
         begin
-          r = recv(block, Thread.current[:brb_nb_out])
+          r = recv(block, Thread.current[:brb_nb_out], &blck)
         rescue Exception => e
           raise e
         ensure
@@ -52,9 +67,9 @@ module BrB
         thread = args.pop
         begin
           r = ((args.size > 0) ? @object.send(m, *args) : @object.send(m))
-          brb_send([:r, r, thread, idrequest])
+          brb_send([ReturnCode, r, thread, idrequest])
         rescue Exception => e
-          brb_send([:r, e, thread, idrequest])
+          brb_send([ReturnCode, e, thread, idrequest])
           tputs e.to_s
           tputs e.backtrace.join("\n")
           #raise e

data/lib/brb/tunnel.rb

@@ -33,6 +33,10 @@ module BrB
         
         @queue = Queue.new
         @buffer = ''
+        
+        # Callbacks handling :
+        @callbacks = {}
+        @callbacks_mutex = Mutex.new
       end
 
       # EventMachine Callback, called after connection has been initialized
@@ -78,9 +82,9 @@ module BrB
       end
 
       # When no method is found on tunnel interface, create an brb out request
-      def method_missing(meth, *args)
+      def method_missing(meth, *args, &block)
         return nil if !@active
-        new_brb_out_request(meth, *args)
+        new_brb_out_request(meth, *args, &block)
       end
     end
   end

data/lib/brb/tunnel/shared.rb

@@ -54,13 +54,17 @@ module BrB
         @buffer << data
         
         while obj = load_request
-          if obj[0] == :r
+          if obj[0] == BrB::Request::ReturnCode
+
+            # Return if we have a callback handling the return :
+            next if treat_callback_return(obj[1], obj[2], obj[3])
+
+            # No callback, so blocking thread is waiting :
             @replock.lock
             @responses[obj[2]] ||= Queue.new
             @replock.unlock
             @responses[obj[2]] << [obj[1], obj[3]]
           else
-
             @queue << obj
 
             EM.defer do
@@ -79,6 +83,51 @@ module BrB
         end
       end
 
+      # Declare a new callback to call for a given request
+      # Thread safe code
+      def declare_callback(key, nb_out, &block)
+        @callbacks_mutex.lock
+
+        @callbacks[key] ||= {}
+        @callbacks[key][nb_out] = block
+
+      ensure
+        @callbacks_mutex.unlock
+      end
+      
+      # Return associated callback if present
+      # And if present, delete the associate callback from the table
+      # Thread safe code
+      def get_callback(key, nb_out)
+        @callbacks_mutex.lock
+        
+        if @callbacks[key] and b = @callbacks[key].delete(nb_out)
+          return b
+        end
+
+      ensure
+        @callbacks_mutex.unlock
+      end
+      
+      # Call a callback if present, return true if exists
+      # Non blocking action, use EM.defer
+      def treat_callback_return(ret, key, nb_out)
+
+        if b = get_callback(key, nb_out)
+          EM.defer do
+            # With arity, handle multiple block arguments or no arguments
+            b.arity == 1 ? b.call(ret) : (b.arity == 0 ? b.call : b.call(*ret)) 
+          end
+
+          # A callback has been found and called, return true
+          return true
+        end
+        
+        # No callback, do nothing
+        return nil
+      end
+
+      # Blocking method that wait on the @responses table an answer
       def recv(key, nb_out)
         begin
           @replock.lock
@@ -86,6 +135,12 @@ module BrB
           @replock.unlock
           while rep = r.pop
             if rep[1] == nb_out # On check ke c'est bien la réponse que l'on attend
+              
+              # Call the callback
+              if block_given?
+                yield(rep[0])
+              end
+
               return rep[0]
             end
             if rep[1] > nb_out

data/spec/brb/brb_massive_usage_spec.rb

@@ -1,6 +1,6 @@
-require File.dirname(__FILE__) + '/../spec_helper'
+require 'spec_helper'
 
-describe :brb_service do
+describe :brb_massive_usage do
   before(:all) do
     @brb = BrB::Service
     @brb.stop_service
@@ -13,6 +13,10 @@ describe :brb_service do
     end
   end
   
+  def random_client
+    @clients[rand(@clients.size)]
+  end
+  
   # Start the service
   it "should the service be started" do
      @clients.each do |cl|
@@ -23,26 +27,42 @@ describe :brb_service do
   end
   
   it "should works with massive simple messaging" do
-    nb_call_before = @brb_test.nb_call || 0
-    nb_call_to_do = 500
+     nb_call_before = @brb_test.nb_call || 0
+     nb_call_to_do = 500
+  
+     @clients.each do |cl|
+       nb_call_to_do.times do
+         cl.noarg
+       end
+     end
+  
+     sleep 5
+     # Wait a little in order to be sure all the stack is processed
+     @brb_test.last_call.should == :noarg
+     @brb_test.nb_call.should == (nb_call_to_do * @clients.size) + nb_call_before
+   end
 
-    @clients.each do |cl|
-      nb_call_to_do.times do
-        cl.noarg
+  it "should works with massive callbacks" do
+    block_called = 0
+    nb_callbacks = 1000
+    nb_callbacks.times do |i|
+      random_client.return_same_value(i) do |callback_return_value|
+        callback_return_value.should == i
+        block_called += 1
       end
     end
 
-    sleep 6
-    # Wait a little in order to be sure all the stack is processed
-    @brb_test.last_call.should == :noarg
-    @brb_test.nb_call.should == (nb_call_to_do * @clients.size) + nb_call_before
+    sleep 2
+    # Wait a little in order to be sure the method is called
+    @brb_test.last_call.should == :return_same_value
+    block_called.should == nb_callbacks
   end
-
-  it "should works with massive simple messaging including blocking messaging" do
+  
+  it "should works with massive simple messaging including blocking messaging and callbacks" do
     nb_call_before = @brb_test.nb_call || 0
     nb_call_to_do = 500
     nb_call_blocking_to_do = 50
-
+  
     t = Thread.new do
       @clients.each do |cl|
         nb_call_blocking_to_do.times do
@@ -51,17 +71,28 @@ describe :brb_service do
         end
       end      
     end
-
+    
+    block_called = 0
+    nb_callbacks = 1000
+    nb_callbacks.times do |i|
+      random_client.return_same_value(i) do |callback_return_value|
+        callback_return_value.should == i
+        block_called += 1
+      end
+    end
+  
+  
     @clients.each do |cl|
       nb_call_to_do.times do
         cl.noarg
       end
     end
-
-    sleep 6
+  
+    sleep 5
+    block_called.should == nb_callbacks
     t.join
     # Wait a little in order to be sure all the stack is processed
-    @brb_test.nb_call.should == (nb_call_to_do * @clients.size + nb_call_blocking_to_do * @clients.size) + nb_call_before
+    @brb_test.nb_call.should == nb_callbacks + (nb_call_to_do * @clients.size + nb_call_blocking_to_do * @clients.size) + nb_call_before
   end
 
   # Finally, stop the service

data/spec/brb/brb_service_spec.rb

@@ -1,4 +1,4 @@
-require File.dirname(__FILE__) + '/../spec_helper'
+require 'spec_helper'
 
 describe :brb_service do
   before(:all) do

data/spec/brb/brb_tunnel_spec.rb

@@ -1,9 +1,9 @@
-require File.dirname(__FILE__) + '/../spec_helper'
+require 'spec_helper'
 
 $last_unregistered = nil
 $last_registered = nil
 
-describe :brb_service do
+describe :brb_tunnel do
   before(:all) do
     @brb = BrB::Service
     @brb.stop_service
@@ -90,6 +90,12 @@ describe :brb_service do
     @client.one_arg_with_return_block(h).should == h
   end
   
+  it "should correctly return multiple values" do
+    r1, r2 = @client.return_same_value_twice_block(:ret, :ret2)
+    r1.should == :ret
+    r2.should == :ret2
+  end
+  
   it "should dump to symbol undumpable value by using the proxy" do
     @client.return_same_value_block(Thread.current).class.should == Symbol
     @client.return_same_value_block(Thread.current).should == Thread.current.to_s.to_sym
@@ -103,6 +109,52 @@ describe :brb_service do
     end
     e.should be_a NameError
   end
+  
+  it "should use block as non blocking callback with return value" do
+    block_called = nil
+    @client.return_same_value(:arg) do |v|
+      v.should == :arg
+      block_called = true
+    end
+    sleep 0.2
+    # Wait a little in order to be sure the method is called
+    @brb_test.last_call.should == :return_same_value
+    block_called.should == true
+  end
+  
+  it "should correctly handle multiple values return with callbacks" do
+    block_called = nil
+    @client.return_same_value_twice(:ret, :ret2) do |r1, r2|
+      r1.should == :ret
+      r2.should == :ret2
+      block_called = true
+    end
+    sleep 0.2
+    # Wait a little in order to be sure the method is called
+    @brb_test.last_call.should == :return_same_value_twice
+    block_called.should == true
+  end
+  
+  it "should correctly handle no block args return with callbacks" do
+    block_called = nil
+    @client.return_same_value_twice(:ret, :ret2) do
+      block_called = true
+    end
+    sleep 0.2
+    # Wait a little in order to be sure the method is called
+    @brb_test.last_call.should == :return_same_value_twice
+    block_called.should == true
+  end
+  
+  it "should raise an exception when calling a blocking method with a callback" do
+    e = nil
+    begin
+      @client.return_same_value_block(:arg) do |v|
+      end
+    rescue Exception => e
+    end
+    e.should_not be_nil
+  end
 
   # Finally, stop the service
   it "should stop the service after usage" do
@@ -110,7 +162,7 @@ describe :brb_service do
     @brb.uri.should be_nil
   end
 
-  # Finally, stop the service
+  # Finally, stop the client tunnel
   it "should stop the tunnel after usage" do
     @client.stop_service
     @client.active?.should_not be_true

data/spec/spec_helper.rb

@@ -46,4 +46,9 @@ class BrBTest
     increment_nb_call(:return_same_value)
     return val
   end
+  
+  def return_same_value_twice(val, val2)
+    increment_nb_call(:return_same_value_twice)
+    return val, val2
+  end
 end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 2
-  - 2
-  version: 0.2.2
+  - 3
+  - 0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Guillaume Luccisano
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-21 00:00:00 +02:00
+date: 2010-05-21 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency