ruote 2.2.0 → 2.3.0

data/lib/ruote/log/storage_history.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2011, John Mettraux, jmettraux@gmail.com
+# Copyright (c) 2005-2012, 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
@@ -41,8 +41,11 @@ module Ruote
   #
   #   process_history = engine.history.by_wfid(wfid0)
   #
-  # Note that, by default, the history is an in-memory history (and it is
-  # useless when there are multiple workers).
+  #
+  # == final note
+  #
+  # By default, the history is an in-memory history (see Ruote::DefaultHistory)
+  # (and it is worthless when there are multiple workers).
   #
   class StorageHistory
 
@@ -53,13 +56,7 @@ module Ruote
       @context = context
       @options = options
 
-      if @context.worker
-
-        # only care about logging if there is a worker present
-
-        @context.storage.add_type('history')
-        @context.worker.subscribe(:all, self)
-      end
+      @context.storage.add_type('history')
     end
 
     # Returns all the wfids for which there are history items (msgs) stored.
@@ -126,10 +123,12 @@ module Ruote
       @context.storage.purge_type!('history')
     end
 
-    # This is the method called by the workqueue. Incoming engine events
-    # are 'processed' here.
+    # This method is called by the worker via the context. Successfully
+    # processed msgs are passed here.
     #
-    def notify(msg)
+    def on_msg(msg)
+
+      return unless accept?(msg)
 
       msg = msg.dup
         # a shallow copy is sufficient
@@ -151,6 +150,17 @@ module Ruote
 
       @context.storage.put(msg)
     end
+
+    protected
+
+    # This default implementation lets all the messages in.
+    #
+    # Feel free to override this method in a subclass.
+    #
+    def accept?(msg)
+
+      true
+    end
   end
 end
 

data/lib/ruote/log/wait_logger.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2011, John Mettraux, jmettraux@gmail.com
+# Copyright (c) 2005-2012, 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
@@ -22,45 +22,252 @@
 # Made in Japan.
 #++
 
-require 'ruote/log/test_logger'
-
 
 module Ruote
 
+  # The error raised by WaitLogger#wait_for upon a timeout.
+  #
+  class LoggerTimeout < StandardError
+
+    def initialize(interests, timeout)
+
+      super("waited for #{interests.inspect}, timed out after #{timeout}s")
+    end
+  end
+
+  #
+  # The logic behind Ruote::Dashboard#wait_for is implemented here.
+  #
+  # This logger keeps track of the last 147 events. This number can
+  # be tweaked via the 'wait_logger_max' storage option
+  # (http://ruote.rubyforge.org/configuration.html)
+  #
+  # One doesn't play directly with this class. It's available only via
+  # the Ruote::Dashboard#wait_for and Ruote::Dashboard#noisy=
   #
-  # A helper logger for quickstart examples.
+  # To access the log of processed msgs, look at history services, not
+  # at this wait_logger.
   #
-  # Keeps a maximum of 147 messages.
+  # === options (storage initialization options)
   #
-  class WaitLogger < TestLogger
+  # wait_logger_max(Integer)::
+  #   defaults to 147, max number of recent records to keep track of
+  # wait_logger_timeout(Integer)::
+  #   defaults to 60 (seconds), #wait_for times out after how many seconds?
+  #
+  class WaitLogger
+
+    require 'ruote/log/fancy_printing'
+
+    attr_reader :seen
+    attr_reader :log
 
+    # When set to true, this logger will spit out the ruote activity
+    # happening in this Ruby's runtime ruote worker (if any) to $stdout.
+    #
     attr_accessor :noisy
 
+    # The timeout for #wait_for. Defaults to 60 (seconds). When set to
+    # number inferior or equal to zero, no timeout will be enforced.
+    #
+    attr_accessor :timeout
+
     def initialize(context)
 
       @context = context
-      @color = 33
 
-      @context.worker.subscribe(:all, self) if @context.worker
+      @seen = []
+      @log = []
+      @waiting = []
 
-      @noisy = false
       @count = -1
+      @color = 33
+      @noisy = false
 
-      @seen = []
-      @waiting = []
+      @log_max = context['wait_logger_max'] || 147
+      @timeout = context['wait_logger_timeout'] || 60 # in seconds
+
+      @check_mutex = Mutex.new
     end
 
-    def notify(msg)
+    # The context will call this method for each msg sucessfully processed
+    # by the worker.
+    #
+    def on_msg(msg)
 
-      puts(pretty_print(msg)) if @noisy
+      puts(fancy_print(msg, @noisy)) if @noisy
 
-      #return if @waiting.size < 1
-      #check_msg(msg)
+      return if msg['action'] == 'noop'
 
       @seen << msg
-      @seen.shift if @seen.size > 147
+      @log << msg
+
+      while @log.size > @log_max; @log.shift; end
+      while @seen.size > @log_max; @seen.shift; end
+    end
+
+    # Returns an array of the latest msgs, but fancy-printed. The oldest
+    # first.
+    #
+    def fancy_log
+
+      @log.collect { |msg| fancy_print(msg) }
+    end
+
+    # Debug only : dumps all the seen events to $stdout
+    #
+    def dump
+
+      @seen.collect { |msg| fancy_print(msg) }.join("\n")
+    end
+
+    # Blocks until one or more interests are satisfied.
+    #
+    # interests must be an array of interests. Please refer to
+    # Dashboard#wait_for documentation for allowed values of each interest.
+    #
+    # If multiple interests are given, wait_for blocks until
+    # all of the interests are satisfied.
+    #
+    # wait_for may only be used by one thread at a time. If one
+    # thread calls wait_for and later another thread calls wait_for
+    # while the first thread is waiting, the first thread's
+    # interests are lost and the first thread will never wake up.
+    #
+    def wait_for(interests, opts={})
+
+      @waiting << [ Thread.current, interests ]
+
+      Thread.current['__result__'] = nil
+      start = Time.now
+
+      to = opts[:timeout] || @timeout
+      to = nil if to.nil? || to <= 0
+
+      loop do
+
+        raise(
+          Ruote::LoggerTimeout.new(interests, to)
+        ) if to && (Time.now - start) > to
+
+        @check_mutex.synchronize { check_waiting }
+
+        break if Thread.current['__result__']
+
+        sleep 0.007
+      end
+
+      Thread.current['__result__']
+    end
+
+    def color=(c)
+
+      @color = c
+    end
+
+    def self.fp(msg)
+
+      @logger ||= TestLogger.new(nil)
+      puts @logger.send(:fancy_print, msg)
+    end
+
+    protected
+
+    def check_waiting
+
+      while @waiting.any? and msg = @seen.shift
+
+        @waiting.delete_if do |thread, interests|
+          thread['__result__'] = msg if matches(interests, msg)
+          (interests.size < 1)
+        end
+      end
+    end
+
+    FINAL_ACTIONS = %w[
+      terminated ceased error_intercepted
+    ]
+    ACTIONS = FINAL_ACTIONS + %w[
+      launch apply reply
+      fail
+      dispatch dispatched receive
+      cancel dispatch_cancel kill
+      pause resume dispatch_pause dispatch_resume
+      regenerate
+      pause_process resume_process cancel_process kill_process
+      reput noop raise
+      respark
+    ]
+
+    # Checks whether message msg matches any of interests being waited for.
+    #
+    # Some interests look for actions on particular workflows (e.g.,
+    # waiting for some workflow to finish). Other interests are not
+    # attached to any particular workflow (e.g., :inactive waits until
+    # the engine finishes processing all active and pending workflows)
+    # but are still satisfied when actions happen on workflows (e.g.,
+    # the last workflow being run finishes).
+    #
+    # Returns true if all interests being waited for have been satisfied,
+    # false otherwise.
+    #
+    def matches(interests, msg)
+
+      action = msg['action']
+
+      interests.each do |interest|
+
+        satisfied = case interest
+
+          when :or_error
+            #
+            # let's force an immediate reply
+
+            interests.clear if action == 'error_intercepted'
+
+          when :inactive
+
+            (FINAL_ACTIONS.include?(action) && @context.worker.inactive?)
+
+          when :empty
+
+            (action == 'terminated' && @context.storage.empty?('expressions'))
+
+          when Symbol
+
+            (action == 'dispatch' && msg['participant_name'] == interest.to_s)
+
+          when Fixnum
+
+            interests.delete(interest)
+
+            if (interest > 1)
+              interests << (interest - 1)
+              false
+            else
+              true
+            end
+
+          when Hash
+
+            interest.all? { |k, v|
+              k = 'tree.0' if k == 'exp_name'
+              Ruote.lookup(msg, k) == v
+            }
+
+          when /^[a-z_]+$/
+
+            (action == interest)
+
+          else # wfid
+
+            (FINAL_ACTIONS.include?(action) && msg['wfid'] == interest)
+        end
+
+        interests.delete(interest) if satisfied
+      end
 
-      check_waiting
+      (interests.size < 1)
     end
   end
 end

data/lib/ruote/observer.rb

@@ -0,0 +1,82 @@
+#--
+# Copyright (c) 2005-2012, 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
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# Made in Japan.
+#++
+
+
+module Ruote
+
+  #
+  # An abstract class for observing the activity of a ruote engine.
+  #
+  # Subclass it and add it as a service to observe certain events.
+  #
+  #   require 'ruote/observer'
+  #
+  #   class MyLaunchObserver < Ruote::Observer
+  #
+  #     def on_msg_launch(msg)
+  #       puts "just launched process instance #{msg['wfid']}"
+  #     end
+  #   end
+  #
+  #   dashboard.add_service('launch_observer', MyLaunchObserver)
+  #
+  #   # ...
+  #
+  # Simply add a "on_msg_<msg_name>" method for it to intercept the
+  # given messages.
+  #
+  # See Ruote::ProcessObserver for a base class with precisely defined
+  # methods with helpful arguments if you don't want to investigate
+  # "msgs" too much.
+  #
+  class Observer
+
+    def initialize(context)
+
+      @context = context
+    end
+
+    def on_pre_msg(msg)
+
+      route('pre', msg)
+    end
+
+    def on_msg(msg)
+
+      route(nil, msg)
+    end
+
+    protected
+
+    def route(time, msg)
+
+      target = [ 'on', time, 'msg', msg['action'] ].compact.join('_')
+
+      return unless self.respond_to?(target)
+
+      send(target, msg)
+    end
+  end
+end
+

data/lib/ruote/part/block_participant.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2011, John Mettraux, jmettraux@gmail.com
+# Copyright (c) 2005-2012, 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
@@ -22,8 +22,6 @@
 # Made in Japan.
 #++
 
-require 'ruote/part/local_participant'
-
 
 module Ruote
 
@@ -48,19 +46,20 @@ module Ruote
   # == do_not_thread
   #
   # By default, this participant (like most other participants) is executed
-  # in its own thread (in a Ruby runtime where EventMachine is running,
-  # EM.next_tick is used instead of a new thread).
+  # in its own thread.
   #
-  # You can change that behaviour (beware block thats monopolises the whole
-  # engine !) by doing
   #
-  #   alpha = engine.register_participant :alpha do |workitem|
-  #     workitem.fields['time'] = Time.now
-  #   end
+  # == context
   #
-  #   alpha.do_not_thread = true
+  # As it includes Ruote::LocalParticipant, the block partitcipant has
+  # access to:
   #
-  # (you could also override do_not_thread, the method ...)
+  # * #context: the ruote context
+  # * #workitem: the current workitem (usually passed as arg to the block)
+  # * #fei: the current flow expression id
+  # * #fexp: the current flow expression
+  # * #flavour: only used in #on_cancel (nil or 'kill')
+  # * #lookup_variable(key): looks up a variable...
   #
   class BlockParticipant
 
@@ -73,26 +72,14 @@ module Ruote
       @opts = opts
     end
 
-    def do_not_thread
-
-      @opts['do_not_thread']
-    end
-
-    def consume(workitem)
+    def on_workitem
 
-      block = @opts['block']
-
-      @context.treechecker.block_check(block)
-        # raises in case of 'security' violation
-
-      #block = eval(block, @context.send(:binding))
-        # doesn't work with ruby 1.9.2-p136
-      block = eval(block, @context.instance_eval { binding })
-        # works OK with ruby 1.8.7-249 and 1.9.2-p136
+      block = get_block('on_workitem', 'block')
 
       r = if block.arity == 1
 
         block.call(workitem)
+
       else
 
         block.call(
@@ -108,7 +95,57 @@ module Ruote
 
     def cancel(fei, flavour)
 
-      # do nothing
+      if block = get_block('on_cancel')
+        block.call(fei, flavour)
+      end
+    end
+
+    def on_reply(workitem)
+
+      if block = get_block('on_reply')
+        block.call(workitem)
+      end
+    end
+
+    def accept?(workitem)
+
+      if block = get_block('accept?')
+        block.call(workitem)
+      else
+        true
+      end
+    end
+
+    def do_not_thread(workitem)
+
+      dnt = @opts['do_not_thread']
+
+      return dnt unless dnt.is_a?(String)
+
+      block = get_block('do_not_thread')
+
+      block.call(workitem)
+    end
+
+    protected
+
+    def get_block(*keys)
+
+      key = keys.find { |k| @opts[k] }
+
+      return nil unless key
+
+      block = @opts[key]
+
+      @context.treechecker.block_check(block)
+        # raises in case of 'security' violation
+
+      #eval(block, @context.send(:binding))
+        # doesn't work with ruby 1.9.2-p136
+      #eval(block, @context.instance_eval { binding })
+        # works OK with ruby 1.8.7-249 and 1.9.2-p136
+      eval(block, self.instance_eval { binding })
+        # works OK with ruby 1.8.7-249 and 1.9.2-p136
     end
   end
 end