Spin: yard documentation

1 files changed, 86 insertions, 0 deletions

diff --git a/lib/edoors/spin.rb b/lib/edoors/spin.rb
index b8f8c65..7efacf1 100644
--- a/lib/edoors/spin.rb
+++ b/lib/edoors/spin.rb
@@ -23,6 +23,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
             #
@@ -60,6 +79,10 @@ module Edoors
         #
         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
             {
                 'kls'           => self.class.name,
@@ -74,19 +97,39 @@ module Edoors
             }.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
@@ -96,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
@@ -106,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?
@@ -114,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!
@@ -131,6 +199,12 @@ 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
             @run = true
@@ -149,15 +223,27 @@ module Edoors
             @iotas.values.each do |iota| iota.stop! end unless @hibernation
         end
         #
+        # stops the spinning
+        #
         def stop!
             @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