genie 0.1

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

@@ -0,0 +1,435 @@
+
+require 'nist/common/rubyToolsDay'
+require 'nist/common/singletonReflection'
+
+class QueueDispatcher
+
+# An array of queues
+attr_accessor :child_queues
+
+# A two-argument Proc that determines which queue(s) should
+# be sent #enqueue and #do messages. The arguments are:
+# * The queue under evaluation
+# * The Command to be distributed
+# The result is treated as a Boolean.
+# When the selection_proc is nil (as it is by default)
+# all child_queues are selected.
+attr_accessor :selection_proc
+
+def initialize(*child_queues)
+  self.child_queues = child_queues
+end
+
+# Returns an Array of queues that the argument (a command)
+# should be distributed to.
+def select_queues(cmnd)
+  return child_queues unless selection_proc
+  child_queues.select {|queue|
+	  selection_proc.call(queue, cmnd)
+		}
+end
+
+# Ask each of the child_queues selected by selection_proc
+# to enqueue the argument. Unlike Queue#enquue (which returns
+# a QueueEntry), this returns an Array of QueueEntries.
+def enqueue(cmnd)
+  select_queues(cmnd).collect {|queue| queue.enqueue(cmmnd) }
+end
+
+# Ask each of the child_queues selected by selection_proc
+# to enqueue the argument.
+def do(cmnd)
+  selected = select_queues(cmnd)
+	# Avoid the assembly of a composite result if only one queue is selected
+	return selected[0].do(cmnd) if selected.size == 1
+	# Since #do sleeps until the command has been processed, we need to
+	# spawn a thread for each queue. If we did not do that, the #do would
+	# be issued sequentially.
+	answer = Result.new
+	threads = Array.new
+	selected.each {|queue| 
+		threads << Thread.new(answer) {|result| result.add(true, queue.do(cmnd)) }
+		}
+	# Wait for all threads to finish
+	threads.each {|thread| thread.join }
+	# Finally done!
+	answer
+end
+
+end # QueueDispatcher
+
+# ======================================
+
+class Queue
+
+# If strict_bundle_handling is true, all the commands in
+# a TransactionBundle must be redone if any command fails.  
+# Otherwise, the commands that failed are asked if they 
+# may_have_side_effects: if any of the failures might have 
+# side effects, the entire TransactionBundle must be redone. 
+# If, however, all the failed commands respond that they can 
+# not contain side effects, only the failures are redone. 
+# strict_bundle_handling is cautious, but not necessary 
+# (provided the side effect query is accuate): after all, 
+# the bundle is not a UnitOfWork.
+attr_accessor :strict_bundle_handling
+
+# An Array of available QueueEntries.
+# The oldest entries have the lowest indices.
+attr_accessor :available
+
+# QueueEntries that are currently being processed.
+attr_accessor :claimed
+
+# QueueEntries that have been fully processed (not necessarily
+# successfully).
+attr_accessor :history
+
+# An Array of objcts that respond to
+#    command_added(aCommand, aQue)
+# This method returns a Boolean, true if the
+# reciever wishes to handle the command.
+# When a command is enqueued, watchers are
+# notified until either one of the watchers
+# accepts the command, or all of the watchers
+# have been informed of the command.
+# The order of watchers in this array changes
+# with every send of notify_watchers. This 
+# rotation distributes the load among watchers. 
+attr_accessor :watchers
+
+def initialize
+  self.strict_bundle_handling=true
+	self.available=Array.new
+	self.claimed=Array.new
+	self.history=Array.new
+	self.watchers=Array.new
+end
+
+def add_processor(processor)
+  processor.queue = self
+end
+
+# Register a watcher to recieve entry_added messages.
+def add_watcher(watcher)
+  watchers << watcher
+end
+
+# Deregister a watcher, so that it no longer
+# recieves entry_added messages.
+# Returns the removed watcher (nil if it was not present)
+def remove_watcher(watcher)
+  watchers.delete(watcher)
+end
+
+# Add to the receiver a command which will be executed
+# asynchronously.
+def enqueue(cmnd)
+  entry = cmnd.to_entry
+  available << entry
+	Thread.new(entry) { |e| notify_watchers(e) }
+	entry
+end
+
+def do(cmnd)
+  entry = enqueue(cmnd)
+	entry.thread = Thread.current
+	Thread.stop
+	entry.result
+end
+
+def notify_watchers(queueEntry)
+  watchers.size.times {
+	  w = watchers.shift
+		watchers.push(w)
+		return if w.entry_added(queueEntry)
+		}
+end
+
+# Number of entries available for execution.
+def num_available; available.size; end
+
+# Total estimated time of all entries available for execution
+def estimated_seconds
+  available.inject(0.0) {|sum, entry| sum + entry.estimated_seconds }
+end
+
+# Returns the age of the oldest QueueEntry.
+# Returns 0.0 if none are available
+def age_oldest_available
+  return 0.0 if available.empty?
+  available[0].age
+end
+
+# Acts like claim_one if num is less than two.
+# Otherwise builds a TransactionBundle from
+# the specified number of QueueEntries (or num_available
+# if that is smaller). Adds the TransactionBundle
+# to claimed, and returns the TransactionBundle.
+def claim_num(num)
+  return claim_one if num<2
+	# Ruby actually uses num.min(available.size)
+	kids = available.slice!(0, num)
+	answer = TransactionBundle.new(kids)
+	claimed << answer
+	answer
+end
+
+# Remove the oldest QueueEntrhy from available.
+# Add this oldest entry to claimed.
+# Return the entry.
+def claim_one
+  return nil if available.empty?
+  answer = available.shift
+	claimed << answer
+	answer
+end
+
+# Returns a QueueEntry or TransactionBundle
+# that should approach as closely
+# as possible the requested execution time 
+# (limited to the specified number of entries).
+# maxNum can be nil if an upper limit on the
+# number of commands is not desired.
+def claim_seconds(sec, maxNum=nil)
+  num = num_for_estimated_seconds(sec, maxNum)
+	claim_num(num)
+end
+
+# Transfer the specified entry from available
+# to claimed, and return the entry (nil if
+# the entry is not present).
+def claim_entry(entry)
+  answer = available.delete(entry)
+	claimed << answer if answer
+	answer
+end
+
+# Computes how many of the oldest available commands
+# are necessary to approach (but not exceed) an estimated
+# execution time of sec seconds. An upper limit can be
+# specified: use nil if the upper limit is not desired.
+def num_for_estimated_seconds(sec, maxNum=nil)
+	answer = 0
+	time = 0.0
+	available.each {|entry|
+	  time+=entry.estimated_seconds
+		return answer if time > sec || (maxNum && answer>=maxNum)
+		answer+=1
+		}
+	answer
+end
+
+# Remove the argument from the claimed collection
+def _relinquish(entry)
+  claimed.delete(entry)
+end
+
+# Return the entries to the beginning of the #available
+# collection.  The arguments are intended
+# to be QueueEntries, not TransactionBundles
+# (which are decomposed by #partition inside #processed).
+def _reschedule(*entries)
+  entries.reverse.each {|entry| 
+	  available.unshift(entry) 
+		_relinquish(entry)
+		}
+	entries
+end
+
+
+# The entries have either completed successfully,
+# or we've given up on them. Either way, add them
+# to the history. The arguments are intended
+# to be QueueEntries, not TransactionBundles
+# (which are decomposed by #partition inside #processed).
+def _finish(*entries)
+  entries.each {|entry| 
+	  entry.finish
+	  history << entry 
+		_relinquish(entry)
+		}
+end
+
+# The entry has been processed (not necessarily to completion).
+# Remove the receiver from #claimed, and add the entry or its children
+# to either #history or #available.
+# Return an (ideally empty) Array of those entries that have been
+# rescheduled.
+def processed(entry)
+	not_done, done = entry.partition(strict_bundle_handling)
+	_finish(*done)
+	_reschedule( *not_done )
+end
+
+end # Queue
+
+
+# #############################################################
+
+# Represents an entry in a queue
+class QueueEntry
+
+# The command executed by the entry.
+attr_accessor :command
+
+# An instance of Time representing the
+# moment when the entry was added to the queue
+attr_accessor :when_added
+
+# An instance of Time representing the
+# moment when processor finished working with the entry.
+attr_accessor :when_finished
+
+# The Thread that will be awakended once the
+# entry has been fully processed.
+# Nil if the entry was directly added by #enque.
+# Not nil if the entry was added by #do.
+attr_accessor :thread
+
+# An Integer, originally zero, specifying how many times the
+# command has been attempted.
+attr_accessor :num_attempts
+
+# An array of Results
+attr_accessor :results
+
+# A Symbol that specifies the state of the entry.
+# This is currently not used: it can be used
+# by other components.
+attr_accessor :status
+
+def initialize(command)
+  self.command=command
+	self.num_attempts=0
+	self.when_added=Time.now
+	self.results=Array.new
+end
+
+# Returns the time in seconds since
+# the creation of the entry.
+def age
+  Time.now - when_added
+end
+
+forward(:command, nil, :may_update, :may_have_side_effects, :estimated_seconds, :description)
+
+# Retruns an Integer, the number of times
+# the system can currently attempt the command
+def remaining_attempts
+  command.max_attempts - num_attempts
+end
+
+# Returns a Boolean, true if the system has
+# not exhausted its maximum number of attempts.
+def remaining_attempts?
+  remaining_attempts > 0
+end
+alias has_remaining_attempts remaining_attempts?
+
+
+# Return the most recent result. Returns nil if
+# the command has not yet been attempted.
+def result; results[-1]; end
+
+# Returns a Boolean, true if the most recent Result
+# has an error.
+def error?
+  r = result
+	r && r.error?
+end
+alias has_error error?
+
+# Returns a Boolean, true if the most recent Result
+# has an error that might not occur if the command was
+# attempted another time.
+def retryable_error?
+  r = result
+	r && r.retryable_error?
+end
+alias has_retryable_error retryable_error?
+
+# The queue is done with the entry.
+# Wakes up the thread that submitted the entry to the queue
+# (via #do). Should not be called until the que is done with
+# the entry, and a result (sccessfull or not) is available.
+def finish
+  self.when_finished = Time.now
+	thread.run if thread
+end
+
+# Ask the command to #do. Caches the Result.
+def do
+  r = command.do
+	self.num_attempts+= 1
+	results << r
+	r
+end
+
+# returns an array composed of two arrays:
+#    entries that need to be rescheduled for another try
+#    entries that that are finished, and should not be tried again.
+def partition(strict)
+	return [[self],[]] if retry? 
+	[[],[self]]
+end
+
+def retry?
+  retryable_error? && remaining_attempts?
+end
+
+def undo?
+  command.undoable? && :undo!=command.type
+end
+alias can_undo undo?
+
+def redo?
+  command.undoable? && :undo==command.type
+end
+alias can_redo redo?
+
+end # QueueEntry
+
+
+class TransactionBundle
+
+attr_accessor :children
+
+def initialize(children)
+  self.children=children
+end
+
+def do
+  answer = CompoundResult.new
+	children.each {|kid| answer.add(kid.do) }
+	answer
+end
+
+# returns an array composed of two arrays:
+#    entries that need to be rescheduled for another try
+#    entries that that are finished, and should not be tried again.
+def partition(strict)
+  return children.partition {|kid| kid.retry? } if retry_individually(strict)
+	return [children,[]] if retry? 
+	[[],children]
+end
+
+def may_update
+  children.any? {|kid| kid.may_update }
+end
+
+def retry?
+	children.any? {|kid| kid.retry? }
+end
+alias should_retry retry? 
+
+def retry_individually(strict)
+  return false if strict
+  ! children.any? {|kid| kid.error? && kid.may_have_side_effects }
+end
+
+
+end # TransactionBundle
+
+
+

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

@@ -0,0 +1,113 @@
+require 'nist/common/log'
+
+class Log4r::LogEvent
+# Applications that casn have recoverable errors
+# need to define Log4r::LogEvent#retryable_error?
+# This framework does not currently define what is
+# retryable, so we define here a retryable_error?
+# that always returns false.
+def retryable_error?; false; end
+end
+
+
+# Represents the result of an attempt to execute a command
+class Result
+
+# A resolvable referring to the result of the execution
+attr_accessor :result
+
+# An Array of Log4r::LogEvents (both fatal and non fatal)
+# resulting from exection.
+attr_accessor :notices
+
+# A Float containing the wall clock time in seconds required to execute the command
+attr_accessor :execution_seconds
+
+# A hash of additional data not present in the command's args,
+# but necessary to undo the operation.
+attr_accessor :undo_data
+
+def initialize(result=nil)
+  self.result=result
+  self.notices=Array.new
+	self.undo_data=Hash.new
+end
+
+def error?
+  notices.any? {|notice| notice.error? }
+end
+alias has_error error?
+
+def retryable_error?
+  notices.any? {|notice| notice.retryable_error? }
+end
+alias has_retryable_error retryable_error?
+
+def add_notices(anArray)
+  notices.concat(anArray)
+end
+
+def add_error(description, levelString='ERROR', trace=caller)
+  levelNum = Log4r.level_name_to_index(levelString)
+  notices << Log4r::LogEvent.new(levelNum, logger, trace, description)
+end
+
+end # Result
+
+# #############################################################
+
+class CompoundResult
+
+attr_accessor :children
+
+def initialize(*kids)
+  self.children=kids
+end
+
+def add(aResult)
+  children << aResult
+end
+alias << add
+
+def size
+  children.size
+end
+
+def [](idx)
+  children[idx]
+end
+
+def error?
+  children.any? {|kid| kid.error? }
+end
+alias has_error error?
+
+def retryable_error?
+  children.any? {|kid| kid.retryable_error? }
+end
+alias has_retryable_error retryable_error?
+
+def notices
+  answer = Array.new
+  children.each {|kid| answer.concat(kid.notices) }
+	answer
+end
+
+# Returns an Array of child Result#result values.
+def result
+  children.collect {|kid| kid.result }
+end
+
+# Returns the sum of the execution times, as seconds.
+def execution_seconds
+  children.inject(0.0) {|sum, kid| sum + kid.execution_seconds }
+end
+
+# Returns the union of all the child result undo_data hashes.
+def undo_data
+  answer = Hash.new
+	children.each {|kid| answer.merge!(kid.undo_data) }
+	answer
+end
+
+end # CompoundResult