hegemon 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 49bad6b2e72c34ac00fb694f3d7b40d1b8bd168a
-  data.tar.gz: ccf88b8f9e69b31726b5f2bf8a9fc23b0eed5333
+  metadata.gz: 3b434952e8994ae0a8d76f3892f7519a3ef21fbd
+  data.tar.gz: dfcfaf716ddaefe24334316dbc03597bdb42150f
 SHA512:
-  metadata.gz: a95f34e0f58946285972a6694eae01058d1b9fe5cc010c090790102c965aa49cb51482d5ab2967e8d8425f0ca0901b3dabac3a93dd2756ececdca63118bbc924
-  data.tar.gz: 6593a9e1dd3dfe3c2a5fca87e3aeb4859d0a4ed6d76bb7f6da94f8c8f8a5edde55a4950e4bef3a1660c168ce287f70b69c6b84451f11b569cdbdbeaee323f1d3
+  metadata.gz: dd1b9994151efd8aa79065d1f3cf96753661d17d57ee317ec2deb5d948cce280013996f1516eefca9353d0c082de73aca8417d683315f83ae879242849098d70
+  data.tar.gz: 138a26699c3523e855e554bb71f555f9154d8d11d66c086586cd19ec3208e1d7169a6f61ef43126df41476ffce105f15fa7cd1a3520cb064478eab3a407a7dcc

data/lib/hegemon.rb

@@ -4,53 +4,170 @@ Thread.abort_on_exception = true
 
 module Hegemon
   
-  #***
-  # Accessor functions
-  #***
+  ##
+  # :section: Accessor Methods
+  #
   
+  # Return the current state (as a symbol)
   def state;      @_hegemon_state;                   end
+  # Return the list of declared states (as an array of symbols)
   def states;     @_hegemon_states.keys;             end
+  # Return the current state (as a HegemonState object)
   def state_obj;  @_hegemon_states[@_hegemon_state]; end
+  # Return the current state (as a Hash of HegemonState objects keyed by symbol)
   def state_objs; @_hegemon_states.clone;            end
   
-  threadlock :state, :states, :state_obj, :state_objs, :lock=>:@_hegemon_lock
+  # threadlock :state, :states, :state_obj, :state_objs, :lock=>:@_hegemon_lock
   
-  #***
-  # Declarative functions
-  #***
-  # Run these inside of your object's #initialize method
-  #  to set the parameters of the state machine
-  # All user-provided action blocks will have the scope of the instance object
-  #  in which the state machine parameters are initialized, and all parameters
-  #  should be initialized in the same place (in #initialize, typically)
-  #***
   
-  ##
-  # Bypass all transition requirements and actions to directly impose state +s+
-  # This should not be used in the public API except to set the initial state
-  def impose_state(s); @_hegemon_state = s; end
-  threadlock :impose_state, :lock=>:@_hegemon_lock
   
   ##
-  # Declare a state in the state machine
-  # [+state+] The state name to use, as a symbol
-  # [+&block+] The state's declarative block 
-  #  (refer to Declarative Functions of HegemonState)
+  # :section: Declarative Methods
+  #
+  
+  #
+  # Declare a state in the state machine.  
+  # Returns the HegemonState object created.
+  #
+  # [+state+]
+  #   The state name to use, as a symbol
+  # [+block+]
+  #   The state's declarative block.  
+  #   All code within gets evaluated not in its original binding,
+  #   but in the context of a new HegemonState instance object.  
+  #   For stable use, only call methods in this block that are
+  #   listed in HegemonState@Declarative+Methods.
+  # 
+  # The state and associated state machine data and methods will be
+  # associated with the object referred to by +self+ object in the context
+  # in which the declarative method is called.
+  # 
+  # This means that in typical usage, the declarative methods listed 
+  # in Hegemon@Declarative+Methods (including declare_state) should be 
+  # called only from within an instance method, such as +initialize+.
+  # 
+  # The following example creates a skeleton state machine in each
+  # +MyStateMachine+ instance object with two states: +:working+ and +:idle+.
+  # 
+  #   require 'hegemon'
+  #   
+  #   class MyStateMachine
+  #     include Hegemon
+  #     
+  #     def initialize
+  #       declare_state :working do
+  #         # various HegemonState Declarative Methods
+  #       end
+  #       declare_state :idle do
+  #         # various HegemonState Declarative Methods
+  #       end
+  #     end
+  #   end
+  # 
   def declare_state(state, &block)
     @_hegemon_states ||= Hash.new
     @_hegemon_states[state] = HegemonState.new(self, state, &block)
   end
   threadlock :declare_state, :lock=>:@_hegemon_lock
   
-  # Attempt a transition from the current state to state +s+
-  def request_state(s, *flags)
+  
+  #
+  # Bypass all transition requirements and actions to 
+  # directly impose state +state+ as the current state.
+  #
+  # This should *not* be used in the public API *except* to 
+  # set the initial state of the state machine, because state changes
+  # imposed by impose_state do not obey any rules of the state machine.
+  #
+  # [+state+]
+  #   The state to impose, as a symbol
+  #
+  # This method should be called in the same scope in which the state
+  # was declared with declare_state\.
+  # 
+  # The following example creates a skeleton state machine in each
+  # +MyStateMachine+ instance object with two states: +:working+ and +:idle+
+  # and sets +:working+ as the initial state.
+  # 
+  #   require 'hegemon'
+  #   
+  #   class MyStateMachine
+  #     include Hegemon
+  #     
+  #     def initialize
+  #       impose_state :working
+  #       declare_state :working do
+  #         # various HegemonState Declarative Methods
+  #       end
+  #       declare_state :idle do
+  #         # various HegemonState Declarative Methods
+  #       end
+  #     end
+  #   end
+  def impose_state(s) # :args: state
+    @_hegemon_state = s
+  nil end
+  threadlock :impose_state, :lock=>:@_hegemon_lock
+  
+  
+  
+  ##
+  # :section: State Action Methods
+  #
+  
+  #
+  # Request a transition from the current state to state +state+.  
+  # Returns +true+ if the transition was performed, else returns +false+.
+  #
+  # [+state+]
+  #   The state to which transition is desired, as a symbol
+  # [+flags+]
+  #   All subsequent arguments are interpreted as flags,
+  #   and the only meaningful flag is +:force+ 
+  #   (See transition requirements below).
+  #
+  # In order for the transition to occur, the transition must 
+  # have been defined (using HegemonState#transition_to), and the
+  # transition rules declared in the HegemonTransition declarative block
+  # have been suitably met by any one of the following situations:
+  # * *All* HegemonTransition#requirement blocks evaluate as +true+ 
+  #   and the +:force+ flag was included in +flags+.
+  # * At least *one* HegemonTransition#sufficient block and *all* 
+  #   HegemonTransition#requirement blocks evaluate as +true+
+  # * *All* HegemonTransition#condition blocks and *all* 
+  #   HegemonTransition#requirement blocks evaluate as +true+
+  #
+  # Note that evaluation of the rule blocks stops when a match is found,
+  # so rule blocks with code that has "side effects" are discouraged.
+  #
+  def request_state(s, *flags) # :args: state, *flags
     return false unless @_hegemon_states[@_hegemon_state].transitions[s]
     @_hegemon_states[@_hegemon_state].transitions[s].try(*flags)
   end
   threadlock :request_state, :lock=>:@_hegemon_lock
   
-  # Check for relevant state updates and do.
-  #  Using :only_auto flag will ignore all transitions with auto_update false
+  #
+  # Check the list of possible transitions from the current state
+  # and perform the first transition that is found to be ready, if any.  
+  # Returns +true+ if the transition was performed, else returns +false+.
+  #
+  # [+flags+]
+  #   All subsequent arguments are interpreted as flags,
+  #   and the only meaningful flag is +:only_auto+.  
+  #   Use of the +:only_auto+ flag indicates that all state
+  #   transitions which have disabled automatic updating with 
+  #   HegemonTransition#auto_update should be ignored.
+  # 
+  # In order for a transition to occur, the transition rules 
+  # declared in the HegemonTransition declarative block have been 
+  # suitably met by any one of the following situations:
+  # * *All* HegemonTransition#requirement blocks evaluate as +true+ 
+  #   and the +:force+ flag was included in +flags+.
+  # * At least *one* HegemonTransition#sufficient block and *all* 
+  #   HegemonTransition#requirement blocks evaluate as +true+
+  # * *All* HegemonTransition#condition blocks and *all* 
+  #   HegemonTransition#requirement blocks evaluate as +true+
+  #
   def update_state(*flags)
     return false unless @_hegemon_states[@_hegemon_state]
     trans = @_hegemon_states[@_hegemon_state].transitions
@@ -59,48 +176,94 @@ module Hegemon
   false end
   threadlock :update_state, :lock=>:@_hegemon_lock
   
-  def block_until_state(s);
+  #
+  # Sleep the current thread until the current state is equal to +state+
+  #
+  # [+state+]
+  #   The symbol to compare against the current state against
+  #
+  def block_until_state(s); # :args: state
     raise ArgumentError, "Cannot block until undefined state :#{s}" \
       unless @_hegemon_states.keys.include? s
     sleep 0 until @_hegemon_state==s
-  end
+  nil end
   
-  def do_state_tasks(i=0)
+  # 
+  # Perform all HegemonState#task\s associated with the current state.  
+  # Tasks are performed in the order they were declared in the 
+  # HegemonState declarative block.
+  # 
+  # [+iter_num+ = 0]
+  #   Specify the iteration number to be passed to the task block.
+  #   When called by the +hegemon_auto_thread+ (see start_hegemon_auto_thread),
+  #   this number counts up from zero for each iteration of the 
+  #   +hegemon_auto_thread+ loop.  If no value is specified, +0+ is used.
+  # 
+  def do_state_tasks(iter_num = 0)
     return nil unless @_hegemon_states[@_hegemon_state]
-    @_hegemon_states[@_hegemon_state].do_tasks(i)
+    @_hegemon_states[@_hegemon_state].do_tasks(iter_num)
   nil end
   threadlock :do_state_tasks, :lock=>:@_hegemon_lock
   
+  
+  
+  ##
+  # :section: Thread Action Methods
+  #
+  
   def iter_hegemon_auto_loop(i=0)
     do_state_tasks(i)
     update_state(:only_auto)
   end
+  private :iter_hegemon_auto_loop
   threadlock :iter_hegemon_auto_loop, :lock=>:@_hegemon_lock
   
-  # Run the automatic hegemon thread
-  def start_hegemon_auto_thread
+  #
+  # Run the +hegemon_auto_thread+ if it is not already running.  
+  # Returns the Thread object.  
+  # The +hegemon_auto_thread+ continually calls do_state_tasks and update_state,
+  # counting up from +0+ the value passed to do_state_tasks, until the 
+  # thread is stopped with end_hegemon_auto_thread\.
+  #
+  # [+throttle = 0.1+]
+  #   The amount of time to sleep between iterations, 0.1 seconds by default.
+  #
+  def start_hegemon_auto_thread(throttle = 0.1)
     if (not @_hegemon_auto_thread) \
     or (not @_hegemon_auto_thread.status)
       
       @_end_hegemon_auto_thread = false
+      @_hegemon_auto_thread_throttle ||= throttle
       @_hegemon_auto_thread = Thread.new do
         i = 0
         until @_end_hegemon_auto_thread
           iter_hegemon_auto_loop(i)
           i += 1
+          sleep @_hegemon_auto_thread_throttle
         end
       end
     end
+    @_hegemon_auto_thread
   end
   
+  #
+  # Block until the +hegemon_auto_thread+ is finished.
+  #
   def join_hegemon_auto_thread
     @_hegemon_auto_thread.join if @_hegemon_auto_thread
   end
   
+  #
+  # Raise a flag to stop the loop inside +hegemon_auto_thread+.
+  # 
   def end_hegemon_auto_thread
     @_end_hegemon_auto_thread = true
   end
   threadlock :end_hegemon_auto_thread, :lock=>:@_hegemon_lock
+  
+  #
+  # :section:
+  ##
 end
 
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hegemon
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Joe McIlvain