ruote 2.1.11 → 2.2.0

data/couch_url.txt

@@ -0,0 +1 @@
+http://127.0.0.1:5984

data/jruby_issue.txt

@@ -0,0 +1,32 @@
+
+  ** #<ConcurrencyError: Detected invalid array contents due to unsynchronized modifications with concurrent users>
+/Users/jmettraux/w/ruote/lib/ruote/log/test_logger.rb:124:in `check_waiting'
+/Users/jmettraux/w/ruote/lib/ruote/log/test_logger.rb:71:in `notify'
+/Users/jmettraux/w/ruote/lib/ruote/worker.rb:279:in `notify'
+/Users/jmettraux/w/ruote/lib/ruote/worker.rb:276:in `each'
+/Users/jmettraux/w/ruote/lib/ruote/worker.rb:276:in `notify'
+/Users/jmettraux/w/ruote/lib/ruote/worker.rb:261:in `process'
+/Users/jmettraux/w/ruote/lib/ruote/worker.rb:173:in `step'
+/Users/jmettraux/w/ruote/lib/ruote/worker.rb:75:in `run'
+/Users/jmettraux/w/ruote/lib/ruote/worker.rb:87:in `run_in_thread'
+/Users/jmettraux/w/ruote/lib/ruote/worker.rb:87:in `initialize'
+/Users/jmettraux/w/ruote/lib/ruote/worker.rb:87:in `new'
+/Users/jmettraux/w/ruote/lib/ruote/worker.rb:87:in `run_in_thread'
+/Users/jmettraux/w/ruote/lib/ruote/engine.rb:70:in `initialize'
+./test/functional/base.rb:33:in `new'
+./test/functional/base.rb:33:in `setup'
+/Users/jmettraux/.rvm/rubies/jruby-1.5.6/lib/ruby/1.8/test/unit/testcase.rb:77:in `run'
+/Users/jmettraux/.rvm/rubies/jruby-1.5.6/lib/ruby/1.8/test/unit/testsuite.rb:34:in `run'
+/Users/jmettraux/.rvm/rubies/jruby-1.5.6/lib/ruby/1.8/test/unit/testsuite.rb:33:in `each'
+/Users/jmettraux/.rvm/rubies/jruby-1.5.6/lib/ruby/1.8/test/unit/testsuite.rb:33:in `run'
+/Users/jmettraux/.rvm/rubies/jruby-1.5.6/lib/ruby/1.8/test/unit/testsuite.rb:34:in `run'
+/Users/jmettraux/.rvm/rubies/jruby-1.5.6/lib/ruby/1.8/test/unit/testsuite.rb:33:in `each'
+/Users/jmettraux/.rvm/rubies/jruby-1.5.6/lib/ruby/1.8/test/unit/testsuite.rb:33:in `run'
+/Users/jmettraux/.rvm/rubies/jruby-1.5.6/lib/ruby/1.8/test/unit/ui/testrunnermediator.rb:46:in `run_suite'
+/Users/jmettraux/.rvm/rubies/jruby-1.5.6/lib/ruby/1.8/test/unit/ui/console/testrunner.rb:67:in `start_mediator'
+/Users/jmettraux/.rvm/rubies/jruby-1.5.6/lib/ruby/1.8/test/unit/ui/console/testrunner.rb:41:in `start'
+/Users/jmettraux/.rvm/rubies/jruby-1.5.6/lib/ruby/1.8/test/unit/ui/testrunnerutilities.rb:29:in `run'
+/Users/jmettraux/.rvm/rubies/jruby-1.5.6/lib/ruby/1.8/test/unit/autorunner.rb:216:in `run'
+/Users/jmettraux/.rvm/rubies/jruby-1.5.6/lib/ruby/1.8/test/unit/autorunner.rb:12:in `run'
+/Users/jmettraux/.rvm/rubies/jruby-1.5.6/lib/ruby/1.8/test/unit.rb:279
+

data/lib/ruote.rb

@@ -3,5 +3,5 @@ require 'ruote/storage/hash_storage'
 require 'ruote/worker'
 require 'ruote/engine'
 require 'ruote/participant'
-require 'ruote/parser/ruby_dsl'
+require 'ruote/reader/ruby_dsl'
 

data/lib/ruote/context.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2010, John Mettraux, jmettraux@gmail.com
+# Copyright (c) 2005-2011, John Mettraux, jmettraux@gmail.com
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -29,7 +29,7 @@ module Ruote
 
   #
   # A sort of internal registry, via a shared instance of this class, the worker
-  # and the engine can access subservices like parser, treechecker,
+  # and the engine can access subservices like reader, treechecker,
   # wfid_generator and so on.
   #
   class Context
@@ -40,7 +40,7 @@ module Ruote
     attr_accessor :worker
     attr_accessor :engine
 
-    def initialize (storage, worker=nil)
+    def initialize(storage, worker=nil)
 
       @storage = storage
       @storage.context = self
@@ -80,14 +80,14 @@ module Ruote
     #     # ...
     #   end
     #
-    def [] (key)
+    def [](key)
 
       SERVICE_PREFIX.match(key) ? @services[key] : get_conf[key]
     end
 
     # Mostly used by engine#configure
     #
-    def []= (key, value)
+    def []=(key, value)
 
       raise(
         ArgumentError.new('use context#add_service to register services')
@@ -105,7 +105,7 @@ module Ruote
       get_conf.keys
     end
 
-    def add_service (key, *args)
+    def add_service(key, *args)
 
       path, klass, opts = args
 
@@ -141,8 +141,8 @@ module Ruote
     #
     def shutdown
 
-      @storage.shutdown if @storage.respond_to?(:shutdown)
       @worker.shutdown if @worker
+      @storage.shutdown if @storage.respond_to?(:shutdown)
 
       @services.values.each { |s| s.shutdown if s.respond_to?(:shutdown) }
     end
@@ -168,8 +168,8 @@ module Ruote
 
       { 's_wfidgen' => [
           'ruote/id/mnemo_wfid_generator', 'Ruote::MnemoWfidGenerator' ],
-        's_parser' => [
-          'ruote/parser', 'Ruote::Parser' ],
+        's_reader' => [
+          'ruote/reader', 'Ruote::Reader' ],
         's_treechecker' => [
           'ruote/svc/treechecker', 'Ruote::TreeChecker' ],
         's_expmap' => [
@@ -185,7 +185,9 @@ module Ruote
         's_error_handler' => [
           'ruote/svc/error_handler', 'Ruote::ErrorHandler' ],
         's_logger' => [
-          'ruote/log/wait_logger', 'Ruote::WaitLogger' ] }
+          'ruote/log/wait_logger', 'Ruote::WaitLogger' ],
+        's_history' => [
+          'ruote/log/default_history', 'Ruote::DefaultHistory' ] }
     end
   end
 end

data/lib/ruote/engine.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2010, John Mettraux, jmettraux@gmail.com
+# Copyright (c) 2005-2011, John Mettraux, jmettraux@gmail.com
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -58,7 +58,7 @@ module Ruote
     # If the second options is set to { :join => true }, the worker wil
     # be started and run in the current thread.
     #
-    def initialize (worker_or_storage, opts=true)
+    def initialize(worker_or_storage, opts=true)
 
       @context = worker_or_storage.context
       @context.engine = self
@@ -97,6 +97,13 @@ module Ruote
       @context.worker
     end
 
+    # A shortcut for engine.context.history
+    #
+    def history
+
+      @context.history
+    end
+
     # Quick note : the implementation of launch is found in the module
     # Ruote::ReceiverMixin that the engine includes.
     #
@@ -110,9 +117,9 @@ module Ruote
     #
     # Returns the wfid (workflow instance id) of the running single.
     #
-    def launch_single (process_definition, fields={}, variables={})
+    def launch_single(process_definition, fields={}, variables={})
 
-      tree = @context.parser.parse(process_definition)
+      tree = @context.reader.read(process_definition)
       name = tree[1]['name'] || (tree[1].find { |k, v| v.nil? } || []).first
 
       raise ArgumentError.new(
@@ -124,10 +131,8 @@ module Ruote
       }
       wfid, timestamp = singles['h'][name]
 
-      if wfid && (timestamp + 1.0 < Time.now.to_f || process(wfid) != nil)
-        return wfid
-      end
-        # process is already running
+      return wfid if wfid && (ps(wfid) || Time.now.to_f - timestamp < 1.0)
+        # return wfid if 'singleton' process is already running
 
       wfid = @context.wfidgen.generate
 
@@ -154,45 +159,44 @@ module Ruote
       wfid
     end
 
-    # Given a process identifier (wfid), cancels this process.
+    # Given a workitem or a fei, will do a cancel_expression,
+    # else it's a wfid and it does a cancel_process.
     #
-    def cancel_process (wfid)
+    def cancel(wi_or_fei_or_wfid)
 
-      @context.storage.put_msg('cancel_process', 'wfid' => wfid)
-    end
+      target = Ruote.extract_id(wi_or_fei_or_wfid)
 
-    # Given a process identifier (wfid), kills this process. Killing is
-    # equivalent to cancelling, but when killing, :on_cancel attributes
-    # are not triggered.
-    #
-    def kill_process (wfid)
-
-      @context.storage.put_msg('kill_process', 'wfid' => wfid)
+      if target.is_a?(String)
+        @context.storage.put_msg('cancel_process', 'wfid' => target)
+      else
+        @context.storage.put_msg('cancel', 'fei' => target)
+      end
     end
 
-    # Cancels a segment of process instance. Since expressions are nodes in
-    # processes instances, cancelling an expression, will cancel the expression
-    # and all its children (the segment of process).
-    #
-    def cancel_expression (fei)
-
-      fei = fei.to_h if fei.respond_to?(:to_h)
-      @context.storage.put_msg('cancel', 'fei' => fei)
-    end
+    alias cancel_process cancel
+    alias cancel_expression cancel
 
-    # Like #cancel_expression, but :on_cancel attributes (of the expressions)
-    # are not triggered.
+    # Given a workitem or a fei, will do a kill_expression,
+    # else it's a wfid and it does a kill_process.
     #
-    def kill_expression (fei)
+    def kill(wi_or_fei_or_wfid)
 
-      fei = fei.to_h if fei.respond_to?(:to_h)
-      @context.storage.put_msg('cancel', 'fei' => fei, 'flavour' => 'kill')
+      target = Ruote.extract_id(wi_or_fei_or_wfid)
+
+      if target.is_a?(String)
+        @context.storage.put_msg('kill_process', 'wfid' => target)
+      else
+        @context.storage.put_msg('cancel', 'fei' => target, 'flavour' => 'kill')
+      end
     end
 
+    alias kill_process kill
+    alias kill_expression kill
+
     # Replays at a given error (hopefully you fixed the cause of the error
     # before replaying...)
     #
-    def replay_at_error (err)
+    def replay_at_error(err)
 
       msg = err.msg.dup
       action = msg.delete('action')
@@ -233,7 +237,7 @@ module Ruote
     #
     #   engine.re_apply(fei, :merge_in_fields => { 'customer' => 'bob' })
     #
-    def re_apply (fei, opts={})
+    def re_apply(fei, opts={})
 
       @context.storage.put_msg('cancel', 'fei' => fei.to_h, 're_apply' => opts)
     end
@@ -241,9 +245,9 @@ module Ruote
     # Returns a ProcessStatus instance describing the current status of
     # a process instance.
     #
-    def process (wfid)
+    def process(wfid)
 
-      list_processes([ wfid ], {}).first
+      statuses([ wfid ], {}).first
     end
 
     # Returns an array of ProcessStatus instances.
@@ -257,18 +261,19 @@ module Ruote
     # To simply list the wfids of the currently running, Engine#process_wfids
     # is way cheaper to call.
     #
-    def processes (opts={})
+    def processes(opts={})
 
-      wfids = nil
+      wfids = @context.storage.expression_wfids(opts)
 
-      if opts.size > 0
-
-        wfids = @context.storage.expression_wfids(opts)
+      opts[:count] ? wfids.size : statuses(wfids, opts)
+    end
 
-        return wfids.size if opts[:count]
-      end
+    # Returns a list of processes or the process status of a given process
+    # instance.
+    #
+    def ps(wfid=nil)
 
-      list_processes(wfids, opts)
+      wfid == nil ? processes : process(wfid)
     end
 
     # Returns an array of current errors (hashes)
@@ -281,7 +286,7 @@ module Ruote
     #
     #   engine.errors(:skip => 100, :limit => 100)
     #
-    def errors (wfid=nil)
+    def errors(wfid=nil)
 
       wfid, options = wfid.is_a?(Hash) ? [ nil, wfid ] : [ wfid, {} ]
 
@@ -307,7 +312,7 @@ module Ruote
     #
     #   engine.schedules(:skip => 100, :limit => 100)
     #
-    def schedules (wfid=nil)
+    def schedules(wfid=nil)
 
       wfid, options = wfid.is_a?(Hash) ? [ nil, wfid ] : [ wfid, {} ]
 
@@ -317,7 +322,7 @@ module Ruote
 
       return scheds if options[:count]
 
-      scheds.collect { |sched| Ruote.schedule_to_h(sched) }
+      scheds.collect { |s| Ruote.schedule_to_h(s) }.sort_by { |s| s['wfid'] }
     end
 
     # Returns a [sorted] list of wfids of the process instances currently
@@ -326,11 +331,37 @@ module Ruote
     # This operation is substantially less costly than Engine#processes (though
     # the 'how substantially' depends on the storage chosen).
     #
-    def process_wfids
+    def process_ids
+
+      @context.storage.expression_wfids({})
+    end
+
+    alias process_wfids process_ids
+
+    # Warning : expensive operation.
+    #
+    # Leftovers are workitems, errors and schedules belonging to process
+    # instances for which there are no more expressions left.
+    #
+    # Better delete them or investigate why they are left here.
+    #
+    # The result is a list of documents (hashes) as found in the storage. Each
+    # of them might represent a workitem, an error or a schedule.
+    #
+    # If you want to delete one of them you can do
+    #
+    #   engine.storage.delete(doc)
+    #
+    def leftovers
+
+      wfids = @context.storage.expression_wfids({})
+
+      wis = @context.storage.get_many('workitems').compact
+      ers = @context.storage.get_many('errors').compact
+      scs = @context.storage.get_many('schedules').compact
+        # some slow storages need the compaction... [c]ouch...
 
-      @context.storage.ids('expressions').collect { |sfei|
-        sfei.split('!').last
-      }.uniq.sort
+      (wis + ers + scs).reject { |doc| wfids.include?(doc['fei']['wfid']) }
     end
 
     # Shuts down the engine, mostly passes the shutdown message to the other
@@ -371,7 +402,7 @@ module Ruote
     #
     #   engine.wait_for('20100612-bezerijozo', '20100612-yakisoba')
     #
-    def wait_for (*items)
+    def wait_for(*items)
 
       logger = @context['s_logger']
 
@@ -390,20 +421,43 @@ module Ruote
       worker.join if worker
     end
 
-    # Loads and parses the process definition at the given path.
+    # Loads (and turns into a tree) the process definition at the given path.
     #
-    def load_definition (path)
+    def load_definition(path)
 
-      @context.parser.parse(path)
+      @context.reader.read(path)
     end
 
-    # Registers a participant in the engine. Returns the participant instance.
+    # Registers a participant in the engine.
     #
-    # Some examples :
+    # Takes the form
+    #
+    #   engine.register_participant name_or_regex, klass, opts={}
+    #
+    # With the form
+    #
+    #   engine.register_participant name_or_regex do |workitem|
+    #     # ...
+    #   end
+    #
+    # A BlockParticipant is automatically created.
     #
-    #   require 'ruote/part/hash_participant'
-    #   alice = engine.register_participant 'alice', Ruote::HashParticipant
-    #     # register an in-memory (hash) store for Alice's workitems
+    #
+    # == name or regex
+    #
+    # When registering participants, strings or regexes are accepted. Behind
+    # the scenes, a regex is kept.
+    #
+    # Passing a string like "alain" will get ruote to automatically turn it
+    # into the following regex : /^alain$/.
+    #
+    # For finer control over this, pass a regex directly
+    #
+    #   engine.register_participant /^user-/, MyParticipant
+    #     # will match all workitems whose participant name starts with "user-"
+    #
+    #
+    # == some examples
     #
     #   engine.register_participant 'compute_sum' do |wi|
     #     wi.fields['sum'] = wi.fields['articles'].inject(0) do |s, (c, v)|
@@ -413,57 +467,37 @@ module Ruote
     #   end
     #
     #   class MyParticipant
-    #     def initialize (name)
-    #       @name = name
+    #     def initialize(opts)
+    #       @name = opts['name']
     #     end
-    #     def consume (workitem)
+    #     def consume(workitem)
     #       workitem.fields['rocket_name'] = @name
     #       send_to_the_moon(workitem)
     #     end
-    #     def cancel (fei, flavour)
+    #     def cancel(fei, flavour)
     #       # do nothing
     #     end
     #   end
-    #   engine.register_participant /^moon-.+/, MyParticipant.new('Saturn-V')
     #
+    #   engine.register_participant(
+    #     /^moon-.+/, MyParticipant, 'name' => 'Saturn-V')
     #
-    # == 'stateless' participants are preferred over 'stateful' ones
-    #
-    # Ruote 2.1 is OK with 1 storage and 1+ workers. The workers may be
-    # in other ruby runtimes. This implies that if you have registered a
-    # participant instance (instead of passing its classname and options),
-    # that participant will only run in the worker 'embedded' in the engine
-    # where it was registered... Let me rephrase it, participants instantiated
-    # at registration time (and that includes block participants) only runs
-    # in one worker, always the same.
-    #
-    # 'stateless' participants, instantiated at each dispatch, are preferred.
-    # Any worker can handle them.
-    #
-    # Block participants are still fine for demos (where the worker is included
-    # in the engine (see all the quickstarts). And small engines with 1 worker
-    # are not that bad, not everybody is building huge systems).
-    #
-    # Here is a 'stateless' participant example :
-    #
-    #   class MyStatelessParticipant
-    #     def initialize (opts)
-    #       @opts = opts
-    #     end
-    #     def consume (workitem)
-    #       workitem.fields['rocket_name'] = @opts['name']
-    #       send_to_the_moon(workitem)
-    #     end
-    #     def cancel (fei, flavour)
-    #       # do nothing
+    #   # computing the total for a invoice being passed in the workitem.
+    #   #
+    #   class TotalParticipant
+    #     include Ruote::LocalParticipant
+    #
+    #     def consume(workitem)
+    #       workitem['total'] = workitem.fields['items'].inject(0.0) { |t, item|
+    #         t + item['count'] * PricingService.lookup(item['id'])
+    #       }
+    #       reply_to_engine(workitem)
     #     end
     #   end
-    #
-    #   engine.register_participant(
-    #     'moon', MyStatelessParticipant, 'name' => 'saturn5')
+    #   engine.register_participant 'total', TotalParticipant
     #
     # Remember that the options (the hash that follows the class name), must be
-    # serialisable via JSON.
+    # serializable via JSON.
     #
     #
     # == require_path and load_path
@@ -480,14 +514,18 @@ module Ruote
     # containing the participant implementation. 'require' will load and eval
     # the ruby code only once, 'load' each time.
     #
-    def register_participant (regex, participant=nil, opts={}, &block)
+    def register_participant(regex, participant=nil, opts={}, &block)
+
+      if participant.is_a?(Hash)
+        opts = participant
+        participant = nil
+      end
 
       pa = @context.plist.register(regex, participant, opts, block)
 
       @context.storage.put_msg(
         'participant_registered',
-        'regex' => regex.to_s,
-        'engine_worker_only' => (pa != nil))
+        'regex' => regex.is_a?(Regexp) ? regex.inspect : regex.to_s)
 
       pa
     end
@@ -506,7 +544,7 @@ module Ruote
     #
     # Originally implemented in ruote-kit by Torsten Schoenebaum.
     #
-    def register (*args, &block)
+    def register(*args, &block)
 
       if args.size > 0
         register_participant(*args, &block)
@@ -518,7 +556,7 @@ module Ruote
 
     # Removes/unregisters a participant from the engine.
     #
-    def unregister_participant (name_or_participant)
+    def unregister_participant(name_or_participant)
 
       re = @context.plist.unregister(name_or_participant)
 
@@ -556,11 +594,22 @@ module Ruote
       @context.plist.list
     end
 
-    # Accepts a list of Ruote::ParticipantEntry instances.
+    # Accepts a list of Ruote::ParticipantEntry instances or a list of
+    # [ regex, [ classname, opts ] ] arrays.
     #
     # See Engine#participant_list
     #
-    def participant_list= (pl)
+    # Some examples :
+    #
+    #   engine.participant_list = [
+    #     [ '^charly$', [ 'Ruote::StorageParticipant', {} ] ],
+    #     [ '.+', [ 'MyDefaultParticipant', { 'default' => true } ]
+    #   ]
+    #
+    # This method writes the participant list in one go, it might be easier to
+    # use than to register participant one by ones.
+    #
+    def participant_list=(pl)
 
       @context.plist.list = pl
     end
@@ -578,6 +627,14 @@ module Ruote
       @storage_participant ||= Ruote::StorageParticipant.new(self)
     end
 
+    # Returns an instance of the participant registered under the given name.
+    # Returns nil if there is no participant registered for that name.
+    #
+    def participant(name)
+
+      @context.plist.lookup(name, nil)
+    end
+
     # Adds a service locally (will not get propagated to other workers).
     #
     #   tracer = Tracer.new
@@ -589,7 +646,7 @@ module Ruote
     #
     # This method returns the service instance it just bound.
     #
-    def add_service (name, path_or_instance, classname=nil, opts=nil)
+    def add_service(name, path_or_instance, classname=nil, opts=nil)
 
       @context.add_service(name, path_or_instance, classname, opts)
     end
@@ -603,30 +660,111 @@ module Ruote
     #   # allow ruby_eval
     #   @engine.configure('ruby_eval_allowed', true)
     #
-    def configure (config_key, value)
+    def configure(config_key, value)
 
       @context[config_key] = value
     end
 
-    # A convenience methods for advanced users (like Oleg).
+    # Returns a configuration value.
     #
-    # Given a fei (flow expression id), fetches the workitem as stored in
-    # the expression with that fei.
-    # This is the "applied workitem", if the workitem is currently handed to
-    # a participant, this method will return the workitem as applied, not
-    # the workitem as saved by the participant/user in whatever worklist it
-    # uses. If you need that workitem, do the vanilla thing and ask it to
-    # the [storage] participant or its worklist.
+    #   engine.configure('ruby_eval_allowed', true)
     #
-    # The fei might be a string fei (result of fei.to_storage_id), a
-    # FlowExpressionId instance or a hash.
+    #   p engine.configuration('ruby_eval_allowed')
+    #     # => true
     #
-    def workitem (fei)
+    def configuration(config_key)
 
-      fexp = Ruote::Exp::FlowExpression.fetch(
-        @context, Ruote::FlowExpressionId.extract_h(fei))
+      @context[config_key]
+    end
 
-      Ruote::Workitem.new(fexp.h.applied_workitem)
+    # Returns the process tree that is triggered in case of error.
+    #
+    # Note that this 'on_error' doesn't trigger if an on_error is defined
+    # in the process itself.
+    #
+    # Returns nil if there is no 'on_error' set.
+    #
+    def on_error
+
+      @context.storage.get_trackers['trackers']['on_error']['msg']['tree']
+
+    rescue
+      nil
+    end
+
+    # Returns the process tree that is triggered in case of process termination.
+    #
+    # Note that a termination process doesn't raise a termination process when
+    # it terminates itself.
+    #
+    # Returns nil if there is no 'on_terminate' set.
+    #
+    def on_terminate
+
+      @context.storage.get_trackers['trackers']['on_terminate']['msg']['tree']
+
+    rescue
+      nil
+    end
+
+    # Sets a participant or subprocess to be triggered when an error occurs
+    # in a process instance.
+    #
+    #   engine.on_error = participant_name
+    #
+    #   engine.on_error = subprocess_name
+    #
+    #   engine.on_error = Ruote.process_definition do
+    #     alpha
+    #   end
+    #
+    # Note that this 'on_error' doesn't trigger if an on_error is defined
+    # in the process itself.
+    #
+    def on_error=(target)
+
+      @context.tracker.add_tracker(
+        nil, # do not track a specific wfid
+        'error_intercepted', # react on 'error_intercepted' msgs
+        'on_error', # the identifier
+        nil, # no specific condition
+        { 'action' => 'launch',
+          'wfid' => 'replace',
+          'tree' => target.is_a?(String) ?
+            [ 'define', {}, [ [ target, {}, [] ] ] ] : target,
+          'workitem' => 'replace',
+          'variables' => 'compile' })
+    end
+
+    # Sets a participant or a subprocess that is to be launched/called whenever
+    # a regular process terminates.
+    #
+    #   engine.on_terminate = participant_name
+    #
+    #   engine.on_terminate = subprocess_name
+    #
+    #   engine.on_terminate = Ruote.define do
+    #     alpha
+    #     bravo
+    #   end
+    #
+    # Note that a termination process doesn't raise a termination process when
+    # it terminates itself.
+    #
+    # on_terminate processes are not triggered for on_error processes.
+    # on_error processes are triggered for on_terminate processes as well.
+    #
+    def on_terminate=(target)
+
+      @context.tracker.add_tracker(
+        nil, # do not track a specific wfid
+        'terminated', # react on 'error_intercepted' msgs
+        'on_terminate', # the identifier
+        nil, # no specific condition
+        { 'action' => 'launch',
+          'tree' => target.is_a?(String) ?
+            [ 'define', {}, [ [ target, {}, [] ] ] ] : target,
+          'workitem' => 'replace' })
     end
 
     # A debug helper :
@@ -636,7 +774,7 @@ module Ruote
     # will let the engine (in fact the worker) pour all the details of the
     # executing process instances to STDOUT.
     #
-    def noisy= (b)
+    def noisy=(b)
 
       @context.logger.noisy = b
     end
@@ -645,14 +783,15 @@ module Ruote
 
     # Used by #process and #processes
     #
-    def list_processes (wfids, opts)
+    def statuses(wfids, opts)
 
-      swfids = wfids ? wfids.collect { |wfid| /!#{wfid}-\d+$/ } : nil
+      swfids = wfids.collect { |wfid| /!#{wfid}-\d+$/ }
 
-      exps = @context.storage.get_many('expressions', wfids)
-      swis = @context.storage.get_many('workitems', wfids)
-      errs = @context.storage.get_many('errors', wfids)
-      schs = @context.storage.get_many('schedules', swfids)
+      exps = @context.storage.get_many('expressions', wfids).compact
+      swis = @context.storage.get_many('workitems', wfids).compact
+      errs = @context.storage.get_many('errors', wfids).compact
+      schs = @context.storage.get_many('schedules', swfids).compact
+        # some slow storages need the compaction... couch...
 
       errs = errs.collect { |err| ProcessError.new(err) }
       schs = schs.collect { |sch| Ruote.schedule_to_h(sch) }
@@ -672,13 +811,9 @@ module Ruote
         (by_wfid[sch['wfid']] ||= [ [], [], [], [] ])[3] << sch
       end
 
-      wfids = if wfids
-        wfids
-      else
-        wfids = by_wfid.keys.sort
-        wfids = wfids.reverse if opts[:descending]
-        wfids
-      end
+      wfids = by_wfid.keys.sort
+      wfids = wfids.reverse if opts[:descending]
+        # re-adjust list of wfids, only take what was found
 
       wfids.inject([]) { |a, wfid|
         info = by_wfid[wfid]
@@ -696,17 +831,17 @@ module Ruote
   #
   class EngineVariables
 
-    def initialize (storage)
+    def initialize(storage)
 
       @storage = storage
     end
 
-    def [] (k)
+    def [](k)
 
       @storage.get_engine_variable(k)
     end
 
-    def []= (k, v)
+    def []=(k, v)
 
       @storage.put_engine_variable(k, v)
     end
@@ -719,17 +854,17 @@ module Ruote
   #
   class ParticipantRegistrationProxy
 
-    def initialize (engine)
+    def initialize(engine)
 
       @engine = engine
     end
 
-    def participant (name, klass, options={})
+    def participant(name, klass=nil, options={}, &block)
 
-      @engine.register_participant(name, klass, options)
+      @engine.register_participant(name, klass, options, &block)
     end
 
-    def catchall (*args)
+    def catchall(*args)
 
       klass = args.empty? ? Ruote::StorageParticipant : args.first
       options = args[1] || {}
@@ -739,7 +874,7 @@ module Ruote
 
     # Maybe a bit audacious...
     #
-    def method_missing (method_name, *args)
+    def method_missing(method_name, *args)
 
       participant(method_name, *args)
     end
@@ -748,7 +883,7 @@ module Ruote
   # Refines a schedule as found in the ruote storage into something a bit
   # easier to present.
   #
-  def self.schedule_to_h (sched)
+  def self.schedule_to_h(sched)
 
     h = sched.dup