edoors-ruby 0.0.6 → 0.0.7

data/lib/edoors/room.rb

@@ -28,6 +28,11 @@ module Edoors
     ERROR_ROUTE_SND     = 'routing error: system no destination'.freeze
     #
     class Room < Iota
+        #
+        # creates a Room object from the arguments.
+        #
+        # @param [String] n the name of this Room
+        # @param [Iota] p the parent
         #
         def initialize n, p
             super n, p
@@ -35,6 +40,10 @@ module Edoors
             @links = {}
         end
         #
+        # called by JSON#generate to serialize the Room object into JSON data
+        #
+        # @param [Array] a belongs to JSON generator
+        #
         def to_json *a
             {
                 'kls'   => self.class.name,
@@ -44,6 +53,12 @@ module Edoors
             }.to_json *a
         end
         #
+        # creates a Room object from a JSON data
+        #
+        # @param [Hash] o belongs to JSON parser
+        #
+        # @raise Edoors::Exception if the json kls attribute is wrong
+        #
         def self.json_create o
             raise Edoors::Exception.new "JSON #{o['kls']} != #{self.name}" if o['kls'] != self.name
             room = self.new o['name'], o['parent']
@@ -58,29 +73,65 @@ module Edoors
             room
         end
         #
-        def add_iota s
-            raise Edoors::Exception.new "Iota #{s.name} already has #{s.parent.name} as parent" if not s.parent.nil? and s.parent!=self
-            raise Edoors::Exception.new "Iota #{s.name} already exists in #{path}" if @iotas.has_key? s.name
-            s.parent = self if s.parent.nil?
-            @iotas[s.name]=s
+        # creates a Room object from the data of a particle
+        #
+        # @param [Particle] p the Particle to get Room attributes from
+        #
+        def self.from_particle p, s
+            Edoors::Room.new(p.get_data(Edoors::IOTA_NAME), s)
         end
         #
+        # adds the given Iota to this Room
+        #
+        # @param [Iota] i the Iota to add
+        #
+        # @raise Edoors::Exception if i already has a parent or if a Iota with the same name already exists
+        #
+        def add_iota i
+            raise Edoors::Exception.new "Iota #{i.name} already has #{i.parent.name} as parent" if not i.parent.nil? and i.parent!=self
+            raise Edoors::Exception.new "Iota #{i.name} already exists in #{path}" if @iotas.has_key? i.name
+            i.parent = self if i.parent.nil?
+            @iotas[i.name]=i
+        end
+        #
+        # adds the given Link to this Room
+        #
+        # @param [Link] l the Link to add
+        #
+        # @raise Edoors::Exception if the link source can't be found in this Room
+        #
         def add_link l
             l.door = @iotas[l.src]
             raise Edoors::Exception.new "Link source #{l.src} does not exist in #{path}" if l.door.nil?
             (@links[l.src] ||= [])<< l
         end
         #
+        # forward the call to each children
+        #
+        # @see Spin#spin! called on system bootup
+        #
         def start!
             puts " * start #{path}" if @spin.debug_routing
             @iotas.values.each do |iota| iota.start! end
         end
         #
+        # forward the call to each children
+        #
+        # @see Spin#spin! called on system shutdown
+        #
         def stop!
             puts " * stop #{path}" if @spin.debug_routing
             @iotas.values.each do |iota| iota.stop! end
         end
         #
+        # search through all children for a matching Iota
+        #
+        # @param [String] spath the full path of the earch Iota
+        #
+        # @return [Iota] if found
+        #
+        # @see Particle#initialize used to transform @src and @dst JSON data into refrences
+        #
         def search_down spath
             return self if spath==path
             return nil if (spath=~/^#{path}\/(\w+)\/?/)!=0
@@ -91,21 +142,21 @@ module Edoors
             nil
         end
         #
+        # search for a matching link
+        #
+        # @param [Particle] p the Particle searching for a matching link
+        #
         def _try_links p
             puts "   -> try_links ..." if @spin.debug_routing
             links = @links[p.src.name]
             return false if links.nil?
             pending_link = nil
-            apply_link = false
             links.each do |link|
-                apply_link = link.cond_fields.nil?  # unconditional link
-                p.set_link_fields link.cond_fields if not apply_link
-                if apply_link or (p.link_value==link.cond_value)
-                    # link matches !
+                if p.link_with? link
                     if pending_link
                         p2 = @spin.require_p p.class
                         p2.clone_data p
-                        p2.apply_link! link
+                        p2.apply_link! pending_link
                         send_p p2
                     end
                     pending_link = link
@@ -113,12 +164,16 @@ module Edoors
             end
             if pending_link
                 p.apply_link! pending_link
-                _send false, p
+                _send p
             end
             pending_link
         end
         private :_try_links
         #
+        # route the given Particle
+        #
+        # @param [Particle] p the Particle to be routed
+        #
         def _route p
             if p.room.nil? or p.room==path
                 if door = @iotas[p.door]
@@ -134,7 +189,12 @@ module Edoors
         end
         private :_route
         #
-        def _send sys, p
+        # send the given Particle
+        #
+        # @param [Particle] p the Particle to send
+        # @param [Boolean] sys if true send to system Particle fifo
+        #
+        def _send p, sys=false
             if not sys and p.src.nil?
                 # do not route non system orphan particles !!
                 p.error! Edoors::ERROR_ROUTE_NS, @spin
@@ -162,23 +222,39 @@ module Edoors
         end
         private :_send
         #
+        # send the given Particle to application Particle fifo
+        #
+        # @param [Particle] p the Particle to send
+        #
         def send_p p
             puts " * send_p #{(p.next_dst.nil? ? 'no dst' : p.next_dst)} ..." if @spin.debug_routing
-            _send false, p
+            _send p
             puts "   -> #{p.dst.path}#{Edoors::ACT_SEP}#{p.action}" if @spin.debug_routing
             @spin.post_p p
         end
         #
+        # send the given Particle to system Particle fifo
+        #
+        # @param [Particle] p the Particle to send
+        #
         def send_sys_p p
             puts " * send_sys_p #{(p.next_dst.nil? ? 'no dst' : p.next_dst)} ..." if @spin.debug_routing
-            _send true, p
+            _send p, true
             puts "   -> #{p.dst.path}#{Edoors::ACT_SEP}#{p.action}" if @spin.debug_routing
             @spin.post_sys_p p
         end
         #
+        # process the given system Particle
+        #
+        # @param [Particle] p the Particle to be processed
+        #
+        # @note the Particle is automatically released
+        #
         def process_sys_p p
             if p.action==Edoors::SYS_ACT_ADD_LINK
-                add_link Edoors::Link.from_particle_data p
+                add_link Edoors::Link.from_particle p
+            elsif p.action==Edoors::SYS_ACT_ADD_ROOM
+                Edoors::Room.from_particle p, self
             end
             @spin.release_p p
         end

data/lib/edoors/spin.rb

@@ -22,6 +22,25 @@
 module Edoors
     #
     class Spin < Room
+        #
+        # creates a Spin object from the arguments.
+        #
+        # @param [String] n the name of this Spin
+        # @param [Hash] o a customizable set of options
+        #
+        # @option o 'debug_garbage' [String Symbol]
+        #   output debug information about automatic garbage
+        # @option o 'debug_routing' [String Symbol]
+        #   output debug information about routing
+        # @option o 'hibernation' [Boolean]
+        #   if set to true Iota#start! won't be called within Spin#spin!
+        # @option o 'inner_room' [Hash]
+        #   composed of 2 keys, 'iotas' and 'links' use to repopulate the super class Room
+        # @option o 'app_fifo' [Array]
+        #   list of Particle to feed @app_fifo
+        # @option o 'sys_fifo' [Array]
+        #   list of Particle to feed @sys_fifo
+        #
         #
         def initialize n, o={}
             super n, nil
@@ -34,7 +53,7 @@ module Edoors
             @run = false
             @hibernation    = o['hibernation']||false
             @hibernate_path = 'edoors-hibernate-'+n+'.json'
-            @debug_errors   = o[:debug_errors]||o['debug_errors']||false
+            @debug_garbage  = o[:debug_garbage]||o['debug_garbage']||false
             @debug_routing  = o[:debug_routing]||o['debug_routing']||false
             #
             if not o.empty?
@@ -58,7 +77,11 @@ module Edoors
             end
         end
         #
-        attr_accessor :run, :hibernate_path, :debug_errors, :debug_routing
+        attr_accessor :run, :hibernate_path, :debug_garbage, :debug_routing
+        #
+        # called by JSON#generate to serialize the Spin object into JSON data
+        #
+        # @param [Array] a belongs to JSON generator
         #
         def to_json *a
             {
@@ -69,25 +92,46 @@ module Edoors
                 'inner_room'    => { :iotas=>@iotas, :links=>@links },
                 'sys_fifo'      => @sys_fifo,
                 'app_fifo'      => @app_fifo,
-                'debug_errors'  => @debug_errors,
+                'debug_garbage' => @debug_garbage,
                 'debug_routing' => @debug_routing
             }.to_json(*a)
         end
         #
+        # creates a Spin object from a JSON data
+        #
+        # @param [Hash] o belongs to JSON parser
+        #
+        # @raise Edoors::Exception if the json kls attribute is wrong
+        #
         def self.json_create o
             raise Edoors::Exception.new "JSON #{o['kls']} != #{self.name}" if o['kls'] != self.name
             self.new o['name'], o
         end
         #
+        # add the given Iota to the global Hash
+        #
+        # @param [Iota] iota the Iota to register
+        #
+        # @see Room#_route @world hash is used for routing
+        #
         def add_to_world iota
             @world[iota.path] = iota
         end
         #
+        # search the global Hash for the matching Iota
+        #
+        # @param [String] path the path to the desired Iota
+        #
+        # @see Room#_route @world hash is used for routing
+        #
         def search_world path
             @world[path]
         end
         #
+        # clears all the structures
+        #
         def clear!
+            @links.clear
             @iotas.clear
             @world.clear
             @pool.clear
@@ -95,6 +139,13 @@ module Edoors
             @app_fifo.clear
         end
         #
+        # releases the given Particle
+        #
+        # @parama [Particle] p the Particle to be released
+        #
+        # @note the Particle is stored into Hash @pool to be reused as soon as needed
+        #
+        # @see Particle#reset! the Particle is reseted before beeing stored
         #
         def release_p p
             # hope there is no circular loop
@@ -105,6 +156,12 @@ module Edoors
             ( @pool[p.class] ||= [] ) << p
         end
         #
+        # requires a Particle of the given Class
+        #
+        # @param [Class] p_kls the desired Class of Particle
+        #
+        # @note if there is no Particle of the given Class, one is created
+        #
         def require_p p_kls
             l = @pool[p_kls]
             return p_kls.new if l.nil?
@@ -113,14 +170,26 @@ module Edoors
             p
         end
         #
+        # add the given Particle to the application Particle fifo
+        #
+        # @param [Particle] p the Particle to add
+        #
         def post_p p
             @app_fifo << p
         end
         #
+        # add the given Particle to the system Particle fifo
+        #
+        # @param [Particle] p the Particle to add
+        #
         def post_sys_p p
             @sys_fifo << p
         end
         #
+        # process the given particle
+        #
+        # @param [Particle] p the Particle to be processed
+        #
         def process_sys_p p
             if p.action==Edoors::SYS_ACT_HIBERNATE
                 stop!
@@ -130,8 +199,14 @@ module Edoors
             end
         end
         #
+        # starts the system mainloop
+        #
+        # first Iota#start! is called on each children unless the system is resuming from hibernation
+        # then while there is Particle in the fifo, first process all system Particle then 1 application Particle
+        # after all Iota#stop! is called on each children, unless the system is going into hibernation
+        #
         def spin!
-            @iotas.values.each do |iota| iota.start! end unless @hibernation
+            start!
             @run = true
             @hibernation = false
             while @run and (@sys_fifo.length>0 or @app_fifo.length>0)
@@ -145,18 +220,30 @@ module Edoors
                     break
                 end
             end
-            @iotas.values.each do |iota| iota.stop! end unless @hibernation
+            stop!
         end
         #
-        def stop!
+        # stops the spinning
+        #
+        def stop_spinning!
             @run=false
         end
         #
+        # sends the system into hibernation
+        #
+        # @param [String] path the path to the hibernation file
+        #
+        # the system is serialized into JSON data and flushed to disk
+        #
         def hibernate! path=nil
             @hibernation = true
             File.open(path||@hibernate_path,'w') do |f| f << JSON.pretty_generate(self) end
         end
         #
+        # resumes the system from the given hibernation file
+        #
+        # @param [String] path the hibernation file to load the system from
+        #
         def self.resume! path
             self.json_create JSON.load File.open(path,'r') { |f| f.read }
         end

data/lib/version.rb

@@ -21,7 +21,7 @@
 #
 module Edoors
     #
-    VERSION = "0.0.6"
+    VERSION = "0.0.7"
     #
 end
 #

data/spec/board_spec.rb

@@ -16,11 +16,11 @@ describe Edoors::Board do
     #
     it "require_p release_p" do
         board = Edoors::Board.new 'hell', @spin
-        p0 = board.require_p Edoors::Particle
+        p0 = board.require_p
         p1 = board.require_p Edoors::Particle
         (p0===p1).should be_false
         board.release_p p0
-        p2 = board.require_p Edoors::Particle
+        p2 = board.require_p
         (p0===p2).should be_true
     end
     #
@@ -29,21 +29,24 @@ describe Edoors::Board do
         p0['k0'] = 'v0'
         p0['k1'] = 'neither'
         p0['k2'] = 'v2'
-        p0.set_link_fields 'k0,k2'
-        p0.link_value.should eql 'v0v2'
+        p0.set_link_keys 'k0', 'k2'
+        p0.link_value.should == {'k0'=>'v0','k2'=>'v2'}
         p1 = Edoors::Particle.new
         p1['k0'] = 'v0'
         p1['k1'] = 'nore'
         p1['k2'] = 'v2'
-        p1.set_link_fields 'k0,k2'
-        p1.link_value.should eql 'v0v2'
+        p1.set_link_keys 'k0', 'k2'
+        p1.link_value.should == {'k0'=>'v0','k2'=>'v2'}
         P0 = p0
         P1 = p1
         class Board0 < Edoors::Board
-            attr_reader :ok, :follow
+            attr_reader :ok, :follow, :pass_through
             def receive_p p
                 @ok = false
+                @pass_through = false
                 case p.action
+                when Edoors::ACT_PASS_THROUGH
+                    @pass_through = true
                 when Edoors::ACT_FOLLOW
                     @follow = true
                     @ok = (p===P0 and p.merged(0)===P1)
@@ -72,6 +75,34 @@ describe Edoors::Board do
         b0.process_p p1
         b0.ok.should be_true
         b0.follow.should be_true
+        p2 = b0.require_p
+        p2.set_dst! Edoors::ACT_PASS_THROUGH, b0
+        b0.process_p p2
+        b0.pass_through.should be true
+    end
+    #
+    it "keep! and flush!" do
+        b0 = Edoors::Board.new 'hell', @spin
+        def b0.receive_p p
+            keep! p
+        end
+        def b0.get k
+            @postponed[k]
+        end
+        p0 = Edoors::Particle.new
+        b0.process_p p0
+        p1 = Edoors::Particle.new
+        p1.set_dst! Edoors::ACT_FOLLOW, b0
+        b0.process_p p1
+        p2 = Edoors::Particle.new
+        p2.set_dst! Edoors::ACT_FOLLOW, b0
+        b0.process_p p2
+        p3 = Edoors::Particle.new
+        p3.set_dst! Edoors::ACT_FOLLOW, b0
+        b0.process_p p3
+        (b0.get({}).merged_length+1).should == 4
+        b0.flush!
+        b0.get({}).should be_nil
     end
     #
     it "board->json->board" do
@@ -79,7 +110,7 @@ describe Edoors::Board do
         p0 = Edoors::Particle.new
         p1 = Edoors::Particle.new
         p1['v0']=0
-        p1.set_link_fields 'v0'
+        p1.set_link_keys 'v0'
         board.process_p p0
         board.process_p p1
         hell = Edoors::Board.json_create( JSON.load( JSON.generate(board) ) )