genie 0.1

data/genie-0.1/lib/nist/genie/commands.rb

@@ -0,0 +1,413 @@
+
+require 'nist/common/guid'
+require 'nist/common/log'
+require 'nist/common/singletonReflection'
+
+Object.outputters << Log4r::ObjectOutputter.new('CommandNotification')
+
+# ==============================================
+
+class Object
+
+def resolve; self; end
+
+end # Object
+
+# ==============================================
+
+# In addition to specifying some information about
+# the commands associated with a particular semantic,
+# instances contain Procs that tell the command how
+# to 'do' and 'undo'. The default behavior is to
+# send do_<semantics> or undo_<semantics> to the target.
+class CommandMetainfo
+
+@@registry = Hash.new
+
+# Look up an instance.
+def self.[](sym)
+  @@registry[sym]
+end
+
+# Look up an instance: identical to [].
+def self.lookup(sym)
+  self[sym]
+end
+
+# The Symbol that identifies the command semantics.
+attr_reader :semantics
+
+# A string that a GUI can use to explain the command.
+# Defaults to a String representation of the semantics.
+attr_accessor :description
+
+# An Integer (defaults to one).
+attr_accessor :max_attempts
+
+# A Boolean, true if the command might change
+# data. If this is false, the command is
+# guaranteed not to change any data: it is
+# only a query.
+attr_accessor :may_update
+
+# A Boolean, true if the command has more complicated
+# effects than a setter: defaults to true
+attr_accessor :may_have_side_effects
+
+# A Float that guesses how long the operation might
+# take. It would be more accurate (but a nuisance)
+# to maintain separate estimates for do and undo.
+# The larger of the two is probably the best to use.
+# For that matter, it would be nice to have separate
+# estimates for CPU time and wall clock time.
+# This value is not automatically maintaind: some
+# separate process needs to periodically update
+# this, based on the result's execution_seconds.
+attr_accessor :estimated_seconds
+
+# A Proc which takes arguments:
+# 1. Target
+# 2. Semantics
+# 3. Argument Hash  (should not be modified)
+# 4. Undo data Hash (may have extra data added)
+attr_accessor :do_proc
+
+# An optional Proc which takes arguments:
+# 1. Target
+# 2. Semantics
+# 3. Argument Hash  (should not be modified. Includes undo data.)
+# If the undo_proc is nil, the command can not be undone.
+attr_accessor :undo_proc
+
+# Sets the description as well as the semantics.
+def semantics=(aSymbol)
+  @semantics=aSymbol
+	self.description=aSymbol.to_s
+end
+
+# New instances are automatically cached in the @@registry.
+def initialize(semantics)
+  self.semantics=semantics
+	@@registry[semantics]=self
+	self.max_attempts=1
+	self.estimated_seconds=0.1
+	self.may_update=true
+	self.may_have_side_effects=true
+	self.do_proc=default_do_proc
+	self.undo_proc=default_undo_proc
+end
+
+# Returns the do_proc that gets used if you do not provide another.
+def default_do_proc
+  lambda {|target, method_name, argHash, undoDataHash|
+	  method_name = 'do_'+semantics.to_s
+	  target.send(method_name, argHash, undoDataHash)
+		}
+end
+
+# Returns the undo_proc that gets used if you do not provide another.
+def default_undo_proc
+  lambda {|target, semantics, argHash|
+	  method_name = 'undo_'+semantics.to_s
+	  target.send(method_name, argHash)
+		}
+end
+
+end # CommandMetainfo
+
+# ==============================================
+
+# An abstract factor.  Has an invariant command_id,
+# can wrap itself in a QueueEntry, and can
+# make its inverse.
+class BasicCommand
+
+# Uniquely identifies this instance.
+attr_reader :command_id
+
+def initialize
+	@command_id=GUID.new
+end
+
+def to_entry
+	QueueEntry.new(self)
+end
+
+# Returns a command that undoes the receiver.
+def inverse
+  UndoRedoCommand.new(self)
+end
+
+# Returns the chain of do/undo/redo actions
+# culminating in the receiver. For most commands
+# this returns an Array containing only the
+# receiver. UndoRedoCommand instances return
+# Arrays that have more than one element.
+def command_chain
+  [self]
+end
+
+# Returns one of three Symbols (:do, :undo, :redo)
+# depending on the function of the 'do' message.
+# For most commands, this returns :do. Only
+# UndoRedoCommands can return :undo or :redo.
+def type; :do; end
+
+end # BasicCommand
+
+# ==============================================
+
+# An abstract factor. Knows its semantics, and
+# can use that knowlege to look up a CommandMetainfo
+# (which answers several queries on behalf of the command).
+class SemanticCommand < BasicCommand
+
+# A Symbol that specifies what the command does
+attr_accessor :semantics
+
+def initialize(semantics)
+  self.semantics=semantics
+	super()
+end
+
+# Returns the CommandMetainfo that describes the receiver.
+def metainfo
+  CommandMetainfo[semantics]
+end
+
+# Returns a Boolean, true if the command can be undone
+# (because the metainfo posesses an undo_proc).
+# Compare to QueueDispatcher#undo?
+def undoable?
+  !metainfo.undo_proc.nil?
+end
+alias is_undoable undoable?
+
+forward(:metainfo, CommandMetainfo, :max_attempts, :may_update, :may_have_side_effects, :estimated_seconds, :description)
+
+end # SemanticCommand
+
+# ==============================================
+
+# Represents a basic operation. This implementation
+# relies command description in the form of a CommandMetainfo 
+# that has semantics corresponding to the Command.
+class Command < SemanticCommand
+
+attr_accessor :target
+
+attr_accessor :args
+
+attr_accessor :undo_data
+
+def initialize(semantics)
+  self.args=Hash.new
+	self.undo_data=Hash.new
+	super
+end
+
+def target_resolved
+  target.resolve
+end
+
+def args_resolved
+  answer = Hash.new
+  args.each {|key, value| answer[key]=value.resolve }
+	answer
+end
+
+# Returns a resolved Hash that includes 
+# undo_data as well as args.
+def data_resolved
+  answer = args_resolved
+	undo_data.each {|key, value| answer[key]=value.resolve }
+	answer
+end
+
+# Builds a Result by executing a block with error handling and logging.
+# FIXME: Logging needs to be per-thread, since several processors
+#        might be working in parallel.
+def _execute(method)
+  answer = Result.new
+	notices = Log4r::Outputter['CommandNotification'].history
+	notices.clear
+	startTime = Time.now
+	begin
+	  answer.result = yield
+	rescue LoggedFatal
+	  # Do nothing, it's already logged
+	rescue Exception => e
+	  # Log the exception (without throwing a new LoggedFatal)
+		cr = "\n\t"
+	  self.logger.fatal("Command::#{method} caught exception of class #{e.class.name} with message <#{e.message}> and backtrace #{cr}<#{e.backtrace.join(cr)}>.")
+	end
+	answer.execution_seconds = Time.now - startTime
+	answer.add_notices(notices)
+	answer
+end
+private :_execute
+
+def _do(cache_undo_data)
+  ud = cache_undo_data ? undo_data : Hash.new
+  answer = _execute('do') {metainfo.do_proc.call(target_resolved, semantics, args_resolved, ud)}
+	answer.undo_data=ud
+	answer
+end
+private :_do
+
+def do()
+  _do(true)
+end
+
+def redo
+  _do(false)
+end
+
+def undo
+  if undoable?
+	   return _execute('undo') {metainfo.undo_proc.call(target_resolved, semantics, data_resolved)} 
+	end
+	answer = Result.new
+	answer.add_error("Attempt to undo a command (semantics=:#{semantics.to_s}) which is not undoable.")
+	answer
+end
+
+
+end # Command
+
+# ==============================================
+
+# Represents an indivisible collection of Commands
+# that succeed or fail or as unit. Some metainformation
+# (such as max_attempts) comes from the semantics-specified 
+# CommandMetainfo, but others (such as may_update and
+# may_have_side_effects) are derived from the children.
+# This is the safest thing to do. In principle one could
+# implement a process which ensures that the CommandMetainfo
+# is fully consistent with the chilren for all reasonable
+# combinations of children, but that would probably be
+# error prone.
+class UnitOfWork < SemanticCommand
+
+# An Array of component Commands.
+attr_accessor :children
+
+def initialize(semantics, *kids)
+	self.children=kids
+	super(semantics)
+end
+
+def size
+  children.size
+end
+
+def [](idx)
+  children[idx]
+end
+
+# which_method is either :do, :redo, or :undo
+def _do(which_method)
+  answer = CompoundResult.new
+	children.each {|kid|
+	   r = kid.send(which_method)
+		 answer << r
+		 break if r.error?
+		 }
+	answer
+end
+private :_do
+
+def do()
+  _do(:do)
+end
+
+def redo()
+  _do(:redo)
+end
+
+def undo()
+  _do(:undo)
+end
+
+
+def may_update
+  children.any? {|kid| kid.may_update }
+end
+
+def may_have_side_effects
+  children.any? {|kid| kid.may_have_side_effects }
+end
+
+# Returns a Boolean, true if the command can be undone
+# (because the metainfo posesses an undo_proc).
+# Compare to QueueDispatcher#undo?
+def undoable?
+  children.all? {|kid| kid.undoable? }
+end
+alias is_undoable undoable?
+
+end # UnitOfWork
+
+
+# ==============================================
+
+# Represents a command that undoes some other command.
+# A redo is an undo of an undo. 
+class UndoRedoCommand < BasicCommand
+
+# The command that gets undone (not the command at the end
+# of the chain)
+attr_accessor :command_undone
+
+# The id of the command that gets undone. Used for marshalling.
+attr_accessor :id_of_command_undone
+
+def initialize(command)
+	self.command_undone=command
+	self.id_of_command_undone=command.command_id
+end
+
+forward(:command_undone, Command, :max_attempts, :may_update, :may_have_side_effects, :description)
+
+def do(); command_undone.undo; end
+
+def redo; self.do(); end
+
+def undo; command_undone.redo; end
+
+# Returns a Boolean, true if the command can be undone
+# (because the metainfo posesses an undo_proc).
+# Compare to QueueDispatcher#undo?
+# This method always returns true, under the 
+# presumption that instance creation was valid.
+# The first UndoRedoCommand in an undo/redo chain
+# should be created only if the base command is
+# undoable. Undoing the UndoRedoCommand is equivalent
+# to a redo of the original command, so that is always
+# possible.
+def undoable?
+  true
+end
+alias is_undoable undoable?
+
+# Returns the chain of do/undo/redo actions
+# culminating in the receiver. 
+# UndoRedoCommand instances return
+# Arrays that have more than one element.
+# Other commands returns an Array containing 
+# only the receiver. 
+def command_chain
+  command_undone.command_chain << self
+end
+
+# Returns one of three Symbols (:do, :undo, :redo)
+# depending on the function of the 'do' message.
+# UndoRedoCommands can only return :undo or :redo.
+# Other commands, only return :do.
+def type
+  command_chain.size.even? ? :undo : :redo
+end
+
+
+end # UndoRedoCommand
+

data/genie-0.1/lib/nist/genie/genie.rb

@@ -0,0 +1,4 @@
+require 'nist/genie/results'
+require 'nist/genie/queues'
+require 'nist/genie/commands'
+require 'nist/genie/processors'

data/genie-0.1/lib/nist/genie/processors.rb

@@ -0,0 +1,382 @@
+
+
+class EntryProcessor
+
+# The queue whose entries are processed.
+# Also the queue sending #entry_added.
+attr_reader :queue
+
+# Provides transactions
+attr_accessor :transaction_controller
+
+def initialize
+  self.transaction_controller = NullTransactionController.new
+end
+
+def queue=(aQueue)
+  queue.remove_watcher(self) if queue
+  @queue=aQueue
+	aQueue.add_watcher(self)
+end
+
+def _transact(err)
+  err ? transaction_controller.rollback : transaction_controller.commit
+end
+
+# Process the entry and commit its changes, if any.
+def process(entry)
+  result = entry.do
+	commit_ok = true
+	err = result.error?
+	commit_ok = _transact(err) if entry.may_update
+	result.add_error('Commit failure') if !commit_ok
+	commit_ok && !err
+end
+
+end
+
+# ========================================
+
+# Processes each command as it is received.
+class NotifiedProcessor < EntryProcessor
+
+def entry_added(entry)
+  queue.claim_entry(entry)
+	process(entry)
+	process(entry) while entry.retry?
+	queue.processed(entry)
+	true
+end
+
+end # Processor
+
+# ========================================
+
+# A TransactionController that does nothing.
+# For real transactions, see one of these (may need adaptors):
+# * DBI          http://ruby-dbi.sourceforge.net/
+# * MySQL/Ruby   http://www.tmtm.org/mysql/ruby/README.html
+# * ODB          http://brian.imxcc.com/odb/
+# * Trans-simple http://raa.ruby-lang.org/project/trans-simple/
+# * RDBC         http://raa.ruby-lang.org/project/rdbc/
+class NullTransactionController
+
+def commit; true; end
+def rollback; end
+
+end # NullTransactionController
+
+# ========================================
+
+=begin rdoc
+Mix this module into any class to give it the ability
+to periodically kick of the do_behavior. Just send
+it start and stop messages. These methods are asynchronous.
+There are also synchronous versions that end in _synch.
+Both versions take a Symbol that specifies the subtle
+details of how the receiver should start or stop: see
+VALID_START_SEMANTICS and VALID_STOP_SEMANTICS. 
+
+The do_behavior can be a Proc, Method, or Symbol.
+It takes no arguments, should be thread safe, and
+shuld be guaranteed not to raise an exception.
+If your behavior might raise an exception, wrap
+it in a Proc with exeption handling and logging.
+
+This class offers some optional compensation for the time it
+takes to execute do_behavior. Toward that end it
+maintains a sequential list of the most recent
+max_num_do_times measurements of the do_behavior. 
+
+This mixin is not currently thread safe: this feature 
+may be added later, but it does not look very necessary: 
+a single controller will probably manage all instances. 
+
+It was tempting to use a SimpleMachine to control the
+internnal states. This does not buy us as much as it
+would normally, perhaps because in this case most of 
+the events are internally generated.
+      def entry_state; :halted; end
+      def self.define_transitions
+      	{
+      	:halted => [:half_sleep, :sleep, :do],
+      	:half_sleep => [:halted, :do],
+      	:do => [:halted, :sleep],
+      	:sleep => [:halted, :do]
+      	}
+      end
+      def define_transitions; self.class.define_transitions; end
+      define_transit_tests(define_transitions)
+      write_missing_redispatch_templates(define_transitions)
+=end
+module Periodic
+
+# Specifies the behavior that gets periodically
+# executed. Either:
+# * A Symbol executed by instance this is mixed into
+# * A Proc
+# * A Method
+# Defaults to :process
+attr_accessor :do_behavior
+
+# A float representing either the sleep time,
+# or the approximate time between invocations 
+# (depending on  #subtract_do_time
+attr_accessor :seconds
+
+# A Boolean: 
+# * If true, attempt to adjust the sleep
+#   time so that #seconds includes the invocation time.
+# * If false, #seconds represents the sleep time.
+attr_accessor :subtract_do_time
+
+# A Symbol that specifies the start semantics when
+# #start is invoked without an argument,
+attr_accessor :default_start_semantics
+
+# A Symbol that specifies the stop semantics when
+# #stop is invoked without an argument.
+attr_accessor :default_stop_semantics
+
+# An array of up to MAX_NUM_AVG Floats representing do times.
+# All the times need to be kept, so that the do_times_total
+# can be adjusted when a new measurement replaces an old one.
+attr_accessor :do_times
+
+# A float, the total of the values in do_times
+attr_accessor :do_times_total
+
+# An Integer that specifies the maximum number of
+# measured execution times to keep track of when
+# computing do_times_average
+attr_reader :max_num_do_times
+
+# Non nil while the instance is sleeping.
+# We need to hold on to the thread so that 
+# it can be terminated if we need to stop 
+# immediately.
+attr_reader :sleep_thread
+
+# Non nil while the instance is performing
+# the do_behavior.
+# We need to hold on to the thread so that 
+# it can be terminated if we need to stop 
+# immediately.
+attr_reader :do_thread
+
+# A symbol that keeps track of the current state of the instance.
+attr_reader :state
+
+def initialize_periodic(seconds)
+  self.seconds=seconds
+	self.do_behavior=:process
+	self.subtract_do_time=true
+	self.default_start_semantics=:start_sleep
+	self.default_stop_semantics=:stop_during_sleep
+	self.do_times=Array.new
+	self.do_times_total=0.0
+	self.max_num_do_times=10
+  _halt!
+end
+
+# This setter has the following side effects if the new value is smaller than the old one:
+# * do_times is truncated
+# * do_times_total is changed
+def max_num_do_times=(int)
+  @max_num_do_times=int
+	return unless int<do_times.size
+	do_times = do_times[do_times.size-int, int]
+	do_times_total = do_times.inject(0.0) {|sum, val| sum+val }
+end
+
+# An Array of Symbols describing the first thing that happens
+# when you send #start.
+# * :start_do - The do_behavior is invoked, followed by a sleep.
+# * :start_sleep - The receiver sleeps before executing the do_behavior for the first time.
+# * :start_half_sleep - The receiver sleeps half the normal time before executing the do_behavior.
+VALID_START_SEMANTICS = [:start_do, :start_sleep, :start_half_sleep]
+
+# An Array of Symbols describing how to stop.
+# * :stop_immediately - abort the do_behavior (if running) as well as the sleep.
+# * :stop_during_sleep - Let the do_behavior finish, if it is running. 
+#   If the receiver is sleeping, stop immedately.    
+# * :stop_after_next_do - Let the current sleep and the subsequent do_behavior finish
+#   before stopping. If the do_behavior is already running, let it finish, but don't
+#   sleep or run the do_behavior again after that.
+VALID_STOP_SEMANTICS = [:stop_immediately, :stop_after_next_do, :stop_during_sleep]
+
+# An Array of Symbols describing valid state
+VALID_STATES = [:halted, :running, :halt_scheduled, :halt_after_do_scheduled]
+
+# Returns a Float, the time in seconds that the instance
+# should sleep between invocations.
+def sleep_time
+  subtract_do_time ? seconds - do_times_average : seconds
+end
+
+# A running average based on do_times_total
+def do_times_average
+  do_times_total / do_times.size
+end
+
+# Start the reciever sychronousy according to start_semantics.
+# Does not return until the instance has been stopped.	
+def start_synch(start_semantics=default_start_semantics)
+  fail "Invalid start_semantics: #{start_semantics.to_s}" unless VALID_START_SEMANTICS.include?(start_semantics)
+	_running!
+  case start_semantics
+	when :start_sleep
+		  _sleep
+	when :start_half_sleep
+	    _sleep(0.5)
+	end
+	while (_running? || _halt_after_do?)
+	    _do
+			_halt! if halt_after_do?
+	    _sleep if running
+	end
+	_halted!
+end
+
+# Start the reciever sychronousy according to stop_semantics.
+# Does not return until the instance has been stopped.
+def stop(stop_semantics=default_stop_semantics)
+  fail "Invalid stop_semantics: #{stop_semantics.to_s}" unless VALID_STOP_SEMANTICS.include?(stop_semantics)
+  case stop_semantics
+	when :stop_immediately
+	    _halt!
+			_stop_thread(do_thread, stop_semantics)
+	    _stop_thread(sleep_thread, stop_semantics)
+	when :stop_after_next_do
+	    _halt_after_do!
+			# Don't stop any threads.
+	when :stop_during_sleep
+	    _halt!	
+	    _stop_thread(sleep_thread, stop_semantics)
+	end
+end
+
+# Start the receiver according to start_semantics, and return immediately.
+def start(start_semantics=default_start_semantics)
+  Thread.new{ start_synch(start_semantics) }
+end
+
+# Schedule the receiver to stop, in the mannner specified by stop_semantics.
+# Returns immediately. Depending on stop_semantics, the receiver may
+# execute one more time.
+def stop_synch(stop_semantics=default_stop_semantics)
+  stop_synch(stop_semantics)
+end
+
+def running?;       :running == state; end
+alias _running? running?
+alias is_running? running?
+
+private
+
+def _add_do_time(t)
+  do_times << t
+	do_times_total += t
+	do_times_total -= do_times.shift if do_times.size>max_num_do_times
+end
+
+def _do()
+  do_thread = Thread.current
+	startTime = Time.now
+	answer = case
+	when do_behavior.instance_of?(Symbol) : self.send(do_behavior)
+	when do_behavior.instance_of?(Proc)   : do_behavior.call
+	when do_behavior.instance_of?(Method) : do_behavior.call
+	end
+	_add_do_time(Time.now-startTime)
+	do_thread = nil
+	rescue
+	ensure
+	answer
+end
+
+def _sleep(fraction=1)
+	sleep_thead = Thread.current
+	sleep(sleep_time * fraction)
+	sleep_thread = nil
+	rescue
+	ensure
+end
+
+def _stop_thread(thread, semantics)
+  thread.raise("Periodic mixin stopped with semantics #{semantics.to_s}") if thread
+end
+
+# Test state
+def _halt_after_do?; :halt_after_do_scheduled == state; end
+# Set state
+def _running!;       state = :running; end
+def _halt!;          state = :halt_scheduled; end
+def _halted!;        state = :halted; end
+def _halt_after_do!; state = :halt_after_do_scheduled; end
+
+end # Periodic
+
+# ========================================
+
+class PollingProcessor < EntryProcessor
+include Periodic
+
+# Prevents stale commands in the queue.
+# The highest priority consideration in determining
+# if the processor should process claims.
+attr_accessor :max_command_age
+
+# How much work the instance should request
+# each time it processes commands.
+# Insuficient work will result in a high transaction overhead.
+attr_accessor :min_claim_time
+
+# Large claim size increases odds of command conflict.
+# An upper limit on how many commands will be
+# processed at one time. Too many commands will increase
+# the chance of a conflict. See also claim_size_limit
+attr_accessor :max_claim_size
+
+# Used to adjust the claim_size_limit. Normally 1.0.
+# This is multiplied by the CLAIM_FRACTION_MULIPLIER
+# each time a proccessing attempt fails. It is reset
+# to 1.0 once a processing attempt succeeds.
+attr_reader :claim_fraction
+
+CLAIM_FRACTION_MULIPLIER=0.5
+
+def initialize
+  initialize_periodic(1.0)
+	self.do_behavior=:action
+	self.max_max_periods_without_claims = 10
+	self.min_claim_size = 5
+	self.max_claim_size = 20
+	_reset
+end
+
+def claim?
+  queue.age_oldest_available > max_command_age &&
+	queue.estimated_seconds > min_claim_time
+end
+alias should_claim claim?
+
+def action
+  return unless claim?
+	entry = queue.claim_seconds(min_claim_time, claim_size_limit)
+	success = process(entry)
+	queue.processed(entry) 
+	success ? _reset : _shrink
+end
+
+# Shrink the claim_size_limit by muliplying claim_fraction by CLAIM_FRACTION_MULTIPLIER
+def _shrink
+  @claim_fraction *= CLAIM_FRACTION_MULTIPLIER
+end
+
+# Reset the claim_size_limit by resetting claim_fraction to 1.0
+def _reset
+  @claim_fraction = 1.0
+end
+
+end # PollingProcessor