ruote 2.1.10 → 2.1.11

data/CHANGELOG.txt

@@ -2,6 +2,56 @@
 = ruote - CHANGELOG.txt
 
 
+== ruote - 2.1.11    released 2010/10/01
+
+- Engine#process broken with process where schedule count > 1 (Thanks David)
+- Engine#launch_single for 1! instance processes (Thanks Eric)
+- Workitem#command and #command= helpers
+- ProcessError#workitem helper
+- fetch_flow_expression made public and aliased to fexp
+- ${r:workitem_field} (idea: Nathan Stults)
+- Ruote::Dollar::Dict and Ruote::Dollar::RubyContext
+- made Ruote.dsub a service : @context.dollar_sub.s(...) (idea: Nathan Stults)
+- moved simpler services to ruote/svc/
+- using BlankSlate for ruby process definitions
+- Engine.new(worker, :join => true) will let the worker run in the current
+  thread (and not return)
+- StorageParticipant#query(:count => true)
+- storage.get_many(type, keys, :descending => true)
+- engine.processes(:skip => 50, limit => 50)
+- listen expression : using lwfid instead of wfid (storage change)
+- fixed issue when re-applying root expressions (Thanks Brett)
+- storage_participant.query using :skip and :limit
+- engine.schedules([wfid]) and ProcessStatus#schedules
+- differentiating on_re_apply from on_cancel (process gardening)
+- engine.participant_list= more tolerant about its input
+- engine.process(wfid).stored_workitems
+- engine.process(wfid).workitems and .position
+- engine.process(wfid).last_active
+- engine.errors(wfid=nil) now returns array of ProcessError instances
+- engine.register { block } (Torsten)
+- participant.accept?(workitem)
+- 'ref' expression (pointing to participants or subprocesses)
+- engine.process_wfids (list process instance wfids)
+- set 'v:alpha' => [ 'MyParticipant', { 'flavour' => 'vanilla' }]
+  participants registered as variables (just for that process instance)
+- engine.participant_list and .participant_list=
+- engine.register_participant 'al', 'AlParticipant', :require_path => 'pa/th'
+- engine.register_participant 'al', 'AlParticipant', :load_path => 'pa/th'
+- engine.[un]register for .[un]register_participant
+- engine.noisy = true (a shortcut)
+- engine.storage_participant (a shortcut)
+- removed direct dependency on rufus-lru
+- WaitLogger : a transient @seen (Thanks Kaspar)
+- error_handler : more error catching
+- storage#copy_to(other_storage) item by item implementation
+- Engine#wait_for OK with multiple threads
+- ExpressionMap now loads all expressions in Ruote::Exp:: namespace
+- 'error_intercepted' msg now features error_class, _message and _backtrace (RM)
+- Engine#join and Worker#join
+- workitem.error now includes error's backtrace (contributed by Rich Meyers)
+
+
 == ruote - 2.1.10    released 2010/06/15
 
 - storage#copy_to(other_storage) implemented
@@ -30,7 +80,7 @@
 - Workitem#error and Workitem#timed_out shortcuts
 - participant :on_error => 'x' broken. Fixed. Thanks Oleg.
 - Engine#workitem(fei) for advanced users
-- LocalParticpant : added a reject(workitem) method
+- LocalParticipant : added a reject(workitem) method
 - participant exp : dispatched = true set right after dispatch
 
 

data/CREDITS.txt

@@ -16,6 +16,10 @@ Torsten Schoenebaum - http://github.com/tosch
 Contributors
 ------------
 
+David Goodlad - http://github.com/dgoodlad
+Eric Dennis - http://github.com/threetee
+David Greaves - http://github.com/lbt
+Rich Meyers - http://github.com/richmeyers
 Oleg Pudeyev - http://github.com/p
 Brett Anthoine - http://github.com/anb
 Matt Nichols - http://github.com/mattnichols
@@ -39,6 +43,11 @@ Richard Jennings
 Feedback
 --------
 
+Eric Platon - engine.launch_single idea
+Marc Lee - storage.clear consistency
+Nathan Stults - enhanced dollar substitution and service
+Don H. French - Engine#register_from_dir idea
+Kaspar Schiess - http://github.com/kschiess
 Oleg (foenixx) - many suggestions and bug reports
 Avishai Shalom - discussion and ideas about participant/worker locality
 Gonzalo Suarez - many help

data/README.rdoc

@@ -12,6 +12,19 @@ Process definitions are mainly describing how workitems are routed to participan
 
 == usage
 
+grab ruote
+
+  gem install ruote
+  gem install yajl-ruby
+
+Note : the json gem has a serious bug :
+
+  http://github.com/flori/json/issues#issue/21
+
+So yajl-ruby is seriously recommended.
+
+Then
+
   require 'rubygems'
   require 'ruote'
   require 'ruote/storage/fs_storage'

data/Rakefile

@@ -4,6 +4,17 @@ require 'lib/ruote/version.rb'
 require 'rubygems'
 require 'rake'
 
+#
+# clean
+
+require 'rake/clean'
+CLEAN.include('pkg', 'rdoc', 'ruote_work', 'ruote_data', 'logs')
+
+task :default => [ :clean ]
+
+
+#
+# jeweler tasks
 
 begin
 
@@ -23,10 +34,9 @@ ruote is an open source ruby workflow engine.
     gem.rubyforge_project = 'ruote'
     gem.test_file = 'test/test.rb'
 
-    gem.add_dependency 'rufus-json', '>= 0.2.2'
-    gem.add_dependency 'rufus-cloche', '>= 0.1.17'
+    gem.add_dependency 'rufus-json', '>= 0.2.5'
+    gem.add_dependency 'rufus-cloche', '>= 0.1.20'
     gem.add_dependency 'rufus-dollar'
-    gem.add_dependency 'rufus-lru'
     gem.add_dependency 'rufus-mnemo', '>= 1.1.0'
     gem.add_dependency 'rufus-scheduler', '>= 2.0.5'
     gem.add_dependency 'rufus-treechecker', '>= 1.0.3'
@@ -41,32 +51,51 @@ ruote is an open source ruby workflow engine.
     # Gem::Specification http://www.rubygems.org/read/chapter/20
   end
   Jeweler::GemcutterTasks.new
+
 rescue LoadError
   puts 'Jeweler (or a dependency) not available. Install it with: gem install jeweler'
 end
 
-begin
-  require 'yard'
-  YARD::Rake::YardocTask.new do |doc|
-    doc.options = [ '-o', 'rdoc', '--title', "ruote #{Ruote::VERSION}" ]
-  end
-rescue LoadError
-  task :yard do
-    abort 'YARD is not available. In order to run yardoc, you must: sudo gem install yard'
-  end
+
+#
+# rdoc
+
+#begin
+#  require 'yard'
+#  YARD::Rake::YardocTask.new do |doc|
+#    doc.options = [ '-o', 'rdoc', '--title', "ruote #{Ruote::VERSION}" ]
+#  end
+#rescue LoadError
+#  task :yard do
+#    abort 'YARD is not available. In order to run yardoc, you must: sudo gem install yard'
+#  end
+#end
+
+#
+# make sure to have rdoc 2.5.x to run that
+#
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rd|
+
+  rd.main = 'README.rdoc'
+  rd.rdoc_dir = 'rdoc'
+
+  rd.rdoc_files.include(
+    'README.rdoc', 'CHANGELOG.txt', 'CREDITS.txt', 'lib/**/*.rb')
+
+  rd.title = "ruote #{Ruote::VERSION}"
 end
 
-require 'rake/clean'
-CLEAN.include('pkg', 'rdoc', 'work', 'logs')
 
-task :default => [ :clean ]
+#
+# upload_rdoc
 
 desc 'Upload the documentation to rubyforge'
-task :upload_rdoc => :yard do
-  sh %{
-    rsync -azv -e ssh \
-      rdoc \
-      jmettraux@rubyforge.org:/var/www/gforge-projects/ruote/
-  }
+task :upload_rdoc => [ :clean, :rdoc ] do
+
+  account = 'jmettraux@rubyforge.org'
+  webdir = '/var/www/gforge-projects/ruote'
+
+  sh "rsync -azv -e ssh rdoc #{account}:#{webdir}/"
 end
 

data/TODO.txt

@@ -214,6 +214,26 @@
 [o] storage participant : accept string for fei
 [o] => Ruote::FlowExpressionId.extract(x)
 [o] fei : place engine id in fei.to_storage_id (and back)
+[o] wait_for(:inactive) blocks until worker is inactive
+[o] storage0.copy_to(storage1) / migrate_to as requested by Matt Nichols
+[o] check if rufus-lru is still needed
+[o] storage migration : eats all the memory :(
+[x] remove dependency on rufus-scheduler
+[o] engine.storage_participant
+[o] engine.noisy = true shortcut
+[o] (ft_27) set "v:mypart" => [ 'MyParticipant', {} ]
+    binding a participant on the fly (just for this process)
+[o] participant timeout as an instance method
+[o] engine.process_wfids (lighter than engine.processes)
+[o] storage.get_many(x, y, :descending => true) ?
+[o] storage_participant.query : use skip and limit
+[o] engine.processes use skip and limit
+[o] engine.errors use skip and limit
+[o] ParticipantEntry is a bit brittle when editing engine.participant_list
+[o] use blank slate for process definition
+[o] lib/ruote/svc for treechecker, error_handler and co (tree_checker)
+[o] part/template.rb, use Rufus::Json.pretty_encode
+[o] storage.clear OR storage.purge! OR both (cf discussion with marc_lee) !!
 
 [ ] exp : exp (restricted form of eval ?)
 [ ] exp : case (is it necessary ?)
@@ -358,12 +378,30 @@
 
 [ ] solve the ps#root_expression_for(fei) dilemma
 
-[ ] engine.noisy = true shortcut
-
 [ ] re_apply_stalled
     http://groups.google.com/group/openwferu-users/browse_thread/thread/ff29f26d6b5fd135
 
-[ ] wait_for(:inactive) blocks until worker is inactive
+[ ] engine.purge (arts style : worker.@msgs = [])
+
+[ ] http://ruote.rubyforge.org/irclogs/ruote_2010-07-07.txt
+    configuration issue
+    maybe fail with a good error message when registering service...
+
+[ ] participant 'toto', :while => '${not_good}' (really ?)
+
+[ ] engine.register_from_dir() have a way to re-evaluate the dir
+[o] OR remove engine.register_from_dir()
+[o] AND provide a better register &block
+[o] provide a mean for a participant to reject a workitem (intra plist)
+    on_reply and now filter ?
+
+[ ] rw : upgrade [register_]participant documentation
+
+[ ] StorageParticipant#by_store[_name]
+    maybe : reform the store_name system !
+
+[ ] rename 'parser' to 'reader'
 
-[ ] storage0.copy_to(storage1) / migrate_to as requested by Matt Nichols
+[ ] process_count and error_count ? (processes(:count => true))
+[ ] engine.ps(wfid) (shortcut ?)
 

data/examples/pong.rb

@@ -0,0 +1,37 @@
+
+# http://gist.github.com/596822
+
+require 'rubygems'
+require 'ruote'
+
+pdef = Ruote.process_definition do
+  repeat do
+    ping # mister ping, please shoot first
+    pong
+  end
+end
+
+class Opponent
+  include Ruote::LocalParticipant
+
+  def initialize (options)
+    @options = options
+  end
+
+  def consume (workitem)
+    puts @options['sound']
+    reply_to_engine(workitem)
+  end
+end
+
+engine = Ruote::Engine.new(Ruote::Worker.new(Ruote::HashStorage.new))
+
+engine.register_participant :ping, Opponent, 'sound' => 'ping'
+engine.register_participant :pong, Opponent, 'sound' => 'pong'
+
+wfid = engine.launch(pdef)
+
+sleep 5 # five seconds of ping pong fun
+
+engine.cancel_process(wfid) # game over
+

data/lib/ruote/context.rb

@@ -113,7 +113,7 @@ module Ruote
 
       service = if klass
 
-        require(path)
+        require(path) if path
 
         aa = [ self ]
         aa << opts if opts
@@ -125,6 +125,14 @@ module Ruote
       end
 
       self.class.class_eval %{ def #{key[2..-1]}; @services['#{key}']; end }
+        #
+        # This 'one-liner' will add an instance method to Context for this
+        # service.
+        #
+        # If the service key is 's_dishwasher', then the service will be
+        # available via Context#dishwasher.
+        #
+        # I.e. dishwasher = engine.context.dishwasher
 
       service
     end
@@ -163,19 +171,21 @@ module Ruote
         's_parser' => [
           'ruote/parser', 'Ruote::Parser' ],
         's_treechecker' => [
-          'ruote/util/treechecker', 'Ruote::TreeChecker' ],
+          'ruote/svc/treechecker', 'Ruote::TreeChecker' ],
         's_expmap' => [
-           'ruote/exp/expression_map', 'Ruote::ExpressionMap' ],
+           'ruote/svc/expression_map', 'Ruote::ExpressionMap' ],
         's_tracker' => [
-          'ruote/evt/tracker', 'Ruote::Tracker' ],
+          'ruote/svc/tracker', 'Ruote::Tracker' ],
         's_plist' => [
-          'ruote/part/participant_list', 'Ruote::ParticipantList' ],
+          'ruote/svc/participant_list', 'Ruote::ParticipantList' ],
         's_dispatch_pool' => [
-          'ruote/part/dispatch_pool', 'Ruote::DispatchPool' ],
-        's_logger' => [
-          'ruote/log/wait_logger', 'Ruote::WaitLogger' ],
+          'ruote/svc/dispatch_pool', 'Ruote::DispatchPool' ],
+        's_dollar_sub' => [
+          'ruote/svc/dollar_sub', 'Ruote::DollarSubstitution' ],
         's_error_handler' => [
-          'ruote/error_handler', 'Ruote::ErrorHandler' ] }
+          'ruote/svc/error_handler', 'Ruote::ErrorHandler' ],
+        's_logger' => [
+          'ruote/log/wait_logger', 'Ruote::WaitLogger' ] }
     end
   end
 end

data/lib/ruote/engine/process_error.rb

@@ -50,6 +50,10 @@ module Ruote
       Ruote::FlowExpressionId.new(msg['fei'])
     end
 
+    def wfid
+      msg['fei']['wfid']
+    end
+
     def tree
       @h['msg']['tree']
     end
@@ -82,6 +86,12 @@ module Ruote
       @h['msg']['workitem']['fields']
     end
 
+    # Returns an instance of Ruote::Workitem
+    #
+    def workitem
+      Ruote::Workitem.new(msg['workitem'])
+    end
+
     protected
 
     def to_dot (opts)

data/lib/ruote/engine/process_status.rb

@@ -38,20 +38,35 @@ module Ruote
     #
     attr_reader :expressions
 
+    # An array of the workitems currently in the storage participant for this
+    # process instance.
+    #
+    # Do not confuse with #workitems
+    #
+    attr_reader :stored_workitems
+
     # An array of errors currently plaguing the process instance. Hopefully,
     # this array is empty.
     #
     attr_reader :errors
 
-    def initialize (context, expressions, errors)
+    # An array of schedules (open structs yielding information about the
+    # schedules of this process)
+    #
+    attr_reader :schedules
+
+    def initialize (context, expressions, stored_workitems, errors, schedules)
 
       @expressions = expressions.collect { |e|
         Ruote::Exp::FlowExpression.from_h(context, e) }
       @expressions.sort! { |a, b| a.fei.expid <=> b.fei.expid }
 
-      @errors = errors.collect { |e|
-        ProcessError.new(e) }
-      @errors.sort! { |a, b| a.fei.expid <=> b.fei.expid }
+      @stored_workitems = stored_workitems.collect { |h|
+        Ruote::Workitem.new(h)
+      }
+
+      @errors = errors.sort! { |a, b| a.fei.expid <=> b.fei.expid }
+      @schedules = schedules.sort! { |a, b| a['owner'].sid <=> b['owner'].sid }
     end
 
     # Returns the expression at the root of the process instance.
@@ -134,23 +149,97 @@ module Ruote
     #
     def wfid
 
-      begin
-        root_expression.fei.wfid
-      rescue
-        @errors.first.fei.wfid
-      end
+      @expressions.any? ? @expressions.first.fei.wfid : @errors.first.fei.wfid
     end
 
+    # For a process
+    #
+    #   Ruote.process_definition :name => 'review', :revision => '0.1' do
+    #     author
+    #     reviewer
+    #   end
+    #
+    # will yield 'review'.
+    #
     def definition_name
 
       root_expression.attribute('name') || root_expression.attribute_text
     end
 
+    # For a process
+    #
+    #   Ruote.process_definition :name => 'review', :revision => '0.1' do
+    #     author
+    #     reviewer
+    #   end
+    #
+    # will yield '0.1'.
+    #
     def definition_revision
 
       root_expression.attribute('revision')
     end
 
+    # Returns the 'position' of the process.
+    #
+    #   pdef = Ruote.process_definition do
+    #     alpha :task => 'clean car'
+    #   end
+    #   wfid = engine.launch(pdef)
+    #
+    #   sleep 0.500
+    #
+    #   engine.process(wfid) # => [["0_0", "alpha", {"task"=>"clean car"}]]
+    #
+    # A process with concurrent branches will yield multiple 'positions'.
+    #
+    # It uses #workitems underneath.
+    #
+    def position
+
+      workitems.collect { |wi|
+        r = [ wi.fei.sid, wi.participant_name ]
+        params = wi.fields['params'].dup
+        params.delete('ref')
+        r << params
+        r
+      }
+    end
+
+    # Returns a list of the workitems currently 'out' to participants
+    #
+    # For example, with an instance of
+    #
+    #   Ruote.process_definition do
+    #     concurrence do
+    #       alpha :task => 'clean car'
+    #       bravo :task => 'sell car'
+    #     end
+    #   end
+    #
+    # calling engine.process(wfid).workitems will yield two workitems
+    # (alpha and bravo).
+    #
+    # Warning : do not confuse the workitems here with the workitems held
+    # in a storage participant or equivalent.
+    #
+    def workitems
+
+      @expressions.select { |fexp|
+        fexp.is_a?(Ruote::Exp::ParticipantExpression)
+      }.collect { |fexp|
+        Ruote::Workitem.new(fexp.h.applied_workitem)
+      }
+    end
+
+    # Returns a parseable UTC datetime string which indicates when the process
+    # was last active.
+    #
+    def last_active
+
+      @expressions.collect { |fexp| fexp.h.put_at }.max
+    end
+
     # Returns the process definition tree as it was when this process instance
     # was launched.
     #
@@ -170,25 +259,33 @@ module Ruote
 
       "(process_status wfid '#{wfid}', " +
       "expressions #{@expressions.size}, " +
-      "errors #{@errors.size})"
+      "stored_workitems #{@stored_workitems.size}, " +
+      "errors #{@errors.size}, " +
+      "schedules #{@schedules.size}, " +
+      ")"
     end
 
     def inspect
 
-      s = "== #{self.class} ==\n"
-      s << "   expressions : #{@expressions.size}\n"
+      s = [ "== #{self.class} ==" ]
+      s << "   expressions : #{@expressions.size}"
       @expressions.each do |e|
-        s << "     #{e.fei.to_storage_id} : #{e}\n"
+        s << "     #{e.fei.to_storage_id} : #{e}"
       end
-      s << "   errors : #{@errors.size}\n"
+      s << "   errors : #{@errors.size}"
       @errors.each do |e|
-        s << "     #{e.fei.to_storage_id} :\n" if e.fei
-        s << "     #{e.inspect}\n"
+        s << "     #{e.fei.to_storage_id} :" if e.fei
+        s << "     #{e.inspect}"
       end
+      s << "   schedules : #{@schedules.size}"
+      s << "   stored workitems : #{@stored_workitems.size}"
 
-      s
+      s.join("\n") + "\n"
     end
 
+    # Returns a 'dot' representation of the process. A graph describing
+    # the tree of flow expressions that compose the process.
+    #
     def to_dot (opts={})
 
       s = [ "digraph \"process wfid #{wfid}\" {" ]
@@ -199,27 +296,24 @@ module Ruote
       s.join("\n")
     end
 
-    def to_h
-
-      h = {}
-
-      %w[
-        wfid
-        definition_name definition_revision
-        original_tree current_tree
-        variables tags
-      ].each { |m| h[m] = self.send(m) }
-
-      h['launched_time'] = launched_time.to_s
-
-      # all_variables and all_tags ?
-
-      h['root_expression'] = nil
-      h['expressions'] = @expressions.collect { |e| e.fei.to_h }
-      h['errors'] = @errors.collect { |e| e.to_h }
-
-      h
-    end
+    #--
+    #def to_h
+    #  h = {}
+    #  %w[
+    #    wfid
+    #    definition_name definition_revision
+    #    original_tree current_tree
+    #    variables tags
+    #  ].each { |m| h[m] = self.send(m) }
+    #  h['launched_time'] = launched_time
+    #  h['last_active'] = last_active
+    #  # all_variables and all_tags ?
+    #  h['root_expression'] = nil
+    #  h['expressions'] = @expressions.collect { |e| e.fei.to_h }
+    #  h['errors'] = @errors.collect { |e| e.to_h }
+    #  h
+    #end
+    #++
 
     # Returns the current version of the process definition tree. If no
     # manipulation (gardening) was performed on the tree, this method yields
@@ -230,15 +324,21 @@ module Ruote
       h = Ruote.decompose_tree(original_tree)
 
       @expressions.sort { |e0, e1|
+
         e0.fei.expid <=> e1.fei.expid
+
       }.each { |e|
-        tree = if v = e.tree[1]['_triggered']
+
+        trigger = e.tree[1]['_triggered']
+
+        tree = if trigger && trigger != 'on_re_apply'
           t = original_tree_from_parent(e).dup
-          t[1]['_triggered'] = v
+          t[1]['_triggered'] = trigger
           t
         else
           e.tree
         end
+
         h.merge!(Ruote.decompose_tree(tree, e.fei.expid))
       }
 
@@ -269,7 +369,6 @@ module Ruote
     return nil unless t
 
     t << []
-
     i = 0
 
     loop do