ruote-maestrodev 2.2.1

data/lib/ruote/worker.rb

@@ -0,0 +1,386 @@
+#--
+# 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
+# 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.
+#++
+
+require 'ruote/fei'
+
+
+module Ruote
+
+  #
+  # Workers fetch 'msgs' and 'schedules' from the storage and process them.
+  #
+  # Read more at http://ruote.rubyforge.org/configuration.html
+  #
+  class Worker
+
+    EXP_ACTIONS = %w[ reply cancel fail receive dispatched pause resume ]
+      # 'apply' is comprised in 'launch'
+      # 'receive' is a ParticipantExpression alias for 'reply'
+
+    PROC_ACTIONS = %w[ cancel kill pause resume ].collect { |a| a + '_process' }
+    DISP_ACTIONS = %w[ dispatch dispatch_cancel dispatch_pause dispatch_resume ]
+
+    attr_reader :storage
+    attr_reader :context
+
+    attr_reader :run_thread
+    attr_reader :running
+
+    # Given a storage, creates a new instance of a Worker.
+    #
+    def initialize(storage)
+
+      @subscribers = []
+        # must be ready before the storage is created
+        # services like Logger to subscribe to the worker
+
+      @storage = storage
+      @context = Ruote::Context.new(storage, self)
+
+      @last_time = Time.at(0.0).utc # 1970...
+
+      @running = true
+      @run_thread = nil
+
+      @msgs = []
+      @sleep_time = 0.000
+    end
+
+    # Runs the worker in the current thread. See #run_in_thread for running
+    # in a dedicated thread.
+    #
+    def run
+
+      step while @running
+    end
+
+    # Triggers the run method of the worker in a dedicated thread.
+    #
+    def run_in_thread
+
+      Thread.abort_on_exception = true
+        # TODO : remove me at some point
+
+      @running = true
+
+      @run_thread = Thread.new { run }
+    end
+
+    # Joins the run thread of this worker (if there is no such thread, this
+    # method will return immediately, without any effect).
+    #
+    def join
+
+      @run_thread.join if @run_thread
+    end
+
+    # Loggers and trackers call this method when subscribing for events /
+    # actions in this worker.
+    #
+    def subscribe(actions, subscriber)
+
+      @subscribers << [ actions, subscriber ]
+    end
+
+    # Shuts down this worker (makes sure it won't fetch further messages
+    # and schedules).
+    #
+    def shutdown(join=true)
+
+      @running = false
+
+      if join
+        begin
+          @run_thread.join
+        rescue Exception => e
+        end
+      else
+        sleep(3)
+      end
+    end
+
+    # Returns true if the engine system is inactive, ie if all the process
+    # instances are terminated or are stuck in an error.
+    #
+    # NOTE : for now, if a branch of a process is in error while another is
+    # still running, this method will consider the process instance inactive
+    # (and it will return true if all the processes are considered inactive).
+    #
+    def inactive?
+
+      # the cheaper tests first
+
+      return false if @msgs.size > 0
+      return false unless @context.storage.empty?('schedules')
+      return false unless @context.storage.empty?('msgs')
+
+      wfids = @context.storage.get_many('expressions').collect { |exp|
+        exp['fei']['wfid']
+      }
+
+      error_wfids = @context.storage.get_many('errors').collect { |err|
+        err['fei']['wfid']
+      }
+
+      (wfids - error_wfids == [])
+    end
+
+    protected
+
+    # One worker step, fetches schedules and triggers those whose time has
+    # came, then fetches msgs and processes them.
+    #
+    def step
+
+      now = Time.now.utc
+      delta = now - @last_time
+
+      if delta >= 0.8
+        #
+        # at most once per second, deal with 'ats' and 'crons'
+
+        @last_time = now
+
+        @storage.get_schedules(delta, now).each { |sche| trigger(sche) }
+      end
+
+      # msgs
+
+      @msgs = @storage.get_msgs if @msgs.empty?
+
+      processed = 0
+      collisions = 0
+
+      while msg = @msgs.shift
+
+        r = process(msg)
+
+        if r != false
+          processed += 1
+        else
+          collisions += 1
+        end
+
+        if collisions > 2
+          @msgs = @msgs[(@msgs.size / 2)..-1] || []
+        end
+
+        #@msgs.concat(@storage.get_local_msgs)
+
+        #print r == false ? '*' : '.'
+
+        break if Time.now.utc - @last_time >= 0.8
+      end
+
+      #p processed
+
+      if processed == 0
+        @sleep_time += 0.001
+        @sleep_time = 0.499 if @sleep_time > 0.499
+        sleep(@sleep_time)
+      else
+        @sleep_time = 0.000
+      end
+    end
+
+    # Given a schedule, attempts to trigger it.
+    #
+    # It first tries to
+    # reserve the schedule. If the reservation fails (another worker
+    # was successful probably), false is returned. The schedule is
+    # triggered if the reservation was successful, true is returned.
+    #
+    def trigger(schedule)
+
+      msg = Ruote.fulldup(schedule['msg'])
+
+      return false unless @storage.reserve(schedule)
+
+      @storage.put_msg(msg.delete('action'), msg)
+
+      true
+    end
+
+    # Processes one msg.
+    #
+    # Will return false immediately if the msg reservation failed (another
+    # worker grabbed the message.
+    #
+    # Else will execute the action ordered in the msg, and return true.
+    #
+    # Exceptions in execution are intercepted here and passed to the
+    # engine's (context's) error_handler.
+    #
+    def process(msg)
+
+      return false unless @storage.reserve(msg)
+
+      begin
+
+        action = msg['action']
+
+        if msg['tree']
+          #
+          # warning here, it could be a reply, with a 'tree' key...
+
+          launch(msg)
+
+        elsif EXP_ACTIONS.include?(action)
+
+          Ruote::Exp::FlowExpression.do_action(@context, msg)
+
+        elsif DISP_ACTIONS.include?(action)
+
+          @context.dispatch_pool.handle(msg)
+
+        elsif PROC_ACTIONS.include?(action)
+
+          self.send(action, msg)
+
+        #else
+          # msg got deleted, might still be interesting for a subscriber
+        end
+
+        notify(msg)
+
+      rescue => exception
+
+        @context.error_handler.msg_handle(msg, exception)
+      end
+
+      true
+    end
+
+    # Given a successfully executed msg, now notifies all the subscribers
+    # interested in the kind of action the msg ordered.
+    #
+    def notify(msg)
+
+      @subscribers.each do |actions, subscriber|
+
+        if actions == :all || actions.include?(msg['action'])
+          subscriber.notify(msg)
+        end
+      end
+    end
+
+    # Works for both the 'launch' and the 'apply' msgs.
+    #
+    # Creates a new expression, gives and applies it with the
+    # workitem contained in the msg.
+    #
+    def launch(msg)
+
+      tree = msg['tree']
+      variables = msg['variables']
+      wi = msg['workitem']
+
+      exp_class = @context.expmap.expression_class(tree.first)
+
+      # msg['wfid'] only : it's a launch
+      # msg['fei'] : it's a sub launch (a supplant ?)
+
+      wi['wf_name'] ||= (
+        tree[1]['name'] || tree[1].keys.find { |k| tree[1][k] == nil })
+
+      wi['wf_revision'] ||= (
+        tree[1]['revision'] || tree[1]['rev'])
+
+      exp_hash = {
+        'fei' => msg['fei'] || {
+          'engine_id' => @context.engine_id,
+          'wfid' => msg['wfid'],
+          'subid' => Ruote.generate_subid(msg.inspect),
+          'expid' => '0' },
+        'parent_id' => msg['parent_id'],
+        'original_tree' => tree,
+        'variables' => variables,
+        'applied_workitem' => wi,
+        'forgotten' => msg['forgotten']
+      }
+
+      if not exp_class
+
+        exp_class = Ruote::Exp::RefExpression
+
+      elsif is_launch?(msg, exp_class)
+
+        def_name, tree = Ruote::Exp::DefineExpression.reorganize(tree)
+        variables[def_name] = [ '0', tree ] if def_name
+        exp_class = Ruote::Exp::SequenceExpression
+      end
+
+      exp = exp_class.new(@context, exp_hash.merge!('original_tree' => tree))
+
+      exp.initial_persist
+      exp.do_apply(msg)
+    end
+
+    # Returns true if the msg is a "launch" (ie not a simply "apply").
+    #
+    def is_launch?(msg, exp_class)
+
+      return false if exp_class != Ruote::Exp::DefineExpression
+      return true if msg['action'] == 'launch'
+      (msg['trigger'] == 'on_re_apply')
+    end
+
+    # Handles a 'cancel_process' msg (translates it into a "cancel root
+    # expression of that process" msg).
+    #
+    # Also works for 'kill_process' msgs.
+    #
+    def cancel_process(msg)
+
+      root = @storage.find_root_expression(msg['wfid'])
+
+      return unless root
+
+      @storage.put_msg(
+        'cancel',
+        'fei' => root['fei'],
+        'wfid' => msg['wfid'], # indicates this was triggered by cancel_process
+        'flavour' => msg['action'] == 'kill_process' ? 'kill' : nil)
+    end
+
+    alias kill_process cancel_process
+
+    # Handles 'pause_process' and 'resume_process'.
+    #
+    def pause_process(msg)
+
+      root = @storage.find_root_expression(msg['wfid'])
+
+      return unless root
+
+      @storage.put_msg(
+        msg['action'] == 'pause_process' ? 'pause' : 'resume',
+        'fei' => root['fei'],
+        'wfid' => msg['wfid']) # it was triggered by {pause|resume}_process
+    end
+
+    alias resume_process pause_process
+  end
+end
+

data/lib/ruote/workitem.rb

@@ -0,0 +1,394 @@
+#--
+# 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
+# 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.
+#++
+
+require 'ruote/util/misc'
+require 'ruote/util/lookup'
+require 'ruote/util/hashdot'
+
+
+module Ruote
+
+  #
+  # A workitem can be thought of an "execution token", but with a payload
+  # (fields).
+  #
+  # The payload/fields MUST be JSONifiable.
+  #
+  class Workitem
+
+    attr_reader :h
+
+    def initialize(h)
+
+      @h = h
+      class << @h; include Ruote::HashDot; end
+
+      #class << @h['fields']
+      #  alias_method :__get, :[]
+      #  alias_method :__set, :[]=
+      #  def [](key)
+      #    __get(key.to_s)
+      #  end
+      #  def []=(key, value)
+      #    __set(key.to_s, value)
+      #  end
+      #end
+        # indifferent access, not activated for now
+    end
+
+    # Returns the underlying Hash instance.
+    #
+    def to_h
+
+      @h
+    end
+
+    # Returns the String id for this workitem (something like
+    # "0_0!!20100507-wagamama").
+    #
+    # It's in fact a shortcut for
+    #
+    #   Ruote::FlowExpressionId.to_storage_id(h.fei)
+    #
+    def sid
+
+      Ruote::FlowExpressionId.to_storage_id(h.fei)
+    end
+
+    # Returns the "workflow instance id" (unique process instance id) of
+    # the process instance which issued this workitem.
+    #
+    def wfid
+
+      h.fei['wfid']
+    end
+
+    # Returns a Ruote::FlowExpressionId instance.
+    #
+    def fei
+
+      FlowExpressionId.new(@h['fei'])
+    end
+
+    # Returns a complete copy of this workitem.
+    #
+    def dup
+
+      Workitem.new(Rufus::Json.dup(@h))
+    end
+
+    # The participant for which this item is destined. Will be nil when
+    # the workitem is transiting inside of its process instance (as opposed
+    # to when it's being delivered outside of the engine).
+    #
+    def participant_name
+
+      @h['participant_name']
+    end
+
+    # Returns the name of the workflow to which this workitem belongs, or nil.
+    #
+    def wf_name
+
+      @h['wf_name']
+    end
+
+    alias definition_name wf_name
+
+    # Returns the revision of the workflow to which this workitem belongs,
+    # or nil.
+    #
+    def wf_revision
+
+      @h['wf_revision']
+    end
+
+    alias definition_revision wf_revision
+
+    # Returns the payload, ie the fields hash.
+    #
+    def fields
+
+      @h['fields']
+    end
+
+    # Sets all the fields in one sweep.
+    #
+    # Remember : the fields must be a JSONifiable hash.
+    #
+    def fields=(fields)
+
+      @h['fields'] = fields
+    end
+
+    # A shortcut to the value in the field named __result__
+    #
+    # This field is used by the if expression for instance to determine
+    # if it should branch to its 'then' or its 'else'.
+    #
+    def result
+
+      fields['__result__']
+    end
+
+    # Sets the value of the 'special' field __result__
+    #
+    # See #result
+    #
+    def result=(r)
+
+      fields['__result__'] = r
+    end
+
+    # When was this workitem dispatched ?
+    #
+    def dispatched_at
+
+      fields['dispatched_at']
+    end
+
+    # Warning : equality is based on fei and not on payload !
+    #
+    def ==(other)
+
+      return false if other.class != self.class
+      self.h['fei'] == other.h['fei']
+    end
+
+    alias eql? ==
+
+    # Warning : hash is fei's hash.
+    #
+    def hash
+
+      self.h['fei'].hash
+    end
+
+    # For a simple key
+    #
+    #   workitem.lookup('toto')
+    #
+    # is equivalent to
+    #
+    #   workitem.fields['toto']
+    #
+    # but for a complex key
+    #
+    #   workitem.lookup('toto.address')
+    #
+    # is equivalent to
+    #
+    #   workitem.fields['toto']['address']
+    #
+    def lookup(key, container_lookup=false)
+
+      Ruote.lookup(@h['fields'], key, container_lookup)
+    end
+
+    # 'lf' for 'lookup field'
+    #
+    alias :lf :lookup
+
+    # Like #lookup allows for nested lookups, #set_field can be used
+    # to set sub fields directly.
+    #
+    #   workitem.set_field('customer.address.city', 'Pleasantville')
+    #
+    # Warning : if the customer and address field and subfield are not present
+    # or are not hashes, set_field will simply create a "customer.address.city"
+    # field and set its value to "Pleasantville".
+    #
+    def set_field(key, value)
+
+      Ruote.set(@h['fields'], key, value)
+    end
+
+    # Shortcut for wi.fields['__timed_out__']
+    #
+    def timed_out
+
+      @h['fields']['__timed_out__']
+    end
+
+    # Shortcut for wi.fields['__error__']
+    #
+    def error
+
+      @h['fields']['__error__']
+    end
+
+    # Shortcut for wi.fields['params']
+    #
+    # When a participant is invoked like in
+    #
+    #    participant :ref => 'toto', :task => 'x"
+    #
+    # then
+    #
+    #    p workitem.params
+    #      # => { 'ref' => 'toto', 'task' => 'x' }
+    #
+    def params
+
+      @h['fields']['params'] || {}
+    end
+
+    # When a participant is invoked like in
+    #
+    #    accounting 'do_invoice', :customer => 'acme corp'
+    #
+    # then
+    #
+    #    p workitem.params
+    #      # => { 'ref' => 'accounting', 'do_invoice' => nil, 'customer' => 'acme corp' }
+    #
+    # and
+    #
+    #    p workitem.param_text
+    #      # => 'do_invoice'
+    #
+    # It returns nil when there is no text passed directly.
+    #
+    def param_text
+
+      (params.find { |k, v| v.nil? } || []).first
+    end
+
+    # Sometimes a value is passed as a[n expression] parameter or as a
+    # workitem field, with priority to the parameter.
+    #
+    #   sequence do
+    #     set 'f:country' => 'uruguay'
+    #     participant 'toto'
+    #       # in toto, workitem.param_or_field(:country) will yield 'uruguay'
+    #     participant 'toto', :country => 'argentina'
+    #       # workitem.param_or_field(:country) will yield 'argentina'
+    #   end
+    #
+    def param_or_field(key)
+
+      key = key.to_s
+
+      (@h['fields']['params'] || {})[key] || @h['fields'][key]
+    end
+
+    # Like #param_or_field, but priority is given to the field.
+    #
+    def field_or_param(key)
+
+      key = key.to_s
+
+      @h['fields'][key] || (@h['fields']['params'] || {})[key]
+    end
+
+    # Shortcut to the temporary/trailing fields
+    #
+    # http://groups.google.com/group/openwferu-users/browse_thread/thread/981dba6204f31ccc
+    #
+    def t
+      @h['fields']['t'] ||= {}
+    end
+
+    # (advanced)
+    #
+    # Shortcut for wi.fields['__command__']
+    #
+    # __command__ is read by the 'cursor' and the 'iterator' expressions
+    # when a workitem reaches it (apply and reply).
+    #
+    def commmand
+
+      @h['fields']['__command__']
+    end
+
+    # (advanced)
+    #
+    # Shortcut for wi.fields['__command__'] = x
+    #
+    # __command__ is read by the 'cursor' and the 'iterator' expressions
+    # when a workitem reaches it (apply and reply).
+    #
+    def command=(com)
+
+      com = com.is_a?(Array) ? com : com.split(' ')
+      com = [ com.first, com.last ]
+      com[1] = com[1].to_i if com[1] and com[0] != 'jump'
+
+      @h['fields']['__command__'] = com
+    end
+
+    # Shortcut for wi.fields['__tags__']
+    #
+    def tags
+
+      @h['fields']['__tags__'] || []
+    end
+
+    # Used by FlowExpression when entering a tag.
+    #
+    def self.add_tag(hworkitem, tag)
+
+      (hworkitem['fields']['__tags__'] ||= []) << tag
+    end
+
+    # Used by FlowExpression when leaving a tag.
+    #
+    def self.remove_tag(hworkitem, tag)
+
+      # it's a bit convoluted... trying to cope with potential inconsistencies
+      #
+      # normally, it should only be a tags.pop(), but since user have
+      # access to the workitem and its fields... better be safe than sorry
+
+      tags = (hworkitem['fields']['__tags__'] || [])
+
+      if index = tags.rindex(tag)
+        tags.delete_at(index)
+      end
+    end
+
+    # Encodes this workitem as JSON. If pretty is set to true, will output
+    # prettified JSON.
+    #
+    def as_json(pretty=false)
+
+      pretty ? Rufus::Json.pretty_encode(@h) : Rufus::Json.encode(@h)
+    end
+
+    # Given a JSON String, decodes and returns a Ruote::Workitem instance.3
+    # If the decode thing is not an object/hash, will raise an ArgumentError.
+    #
+    def self.from_json(json)
+
+      h = Rufus::Json.decode(json)
+
+      raise ArgumentError(
+        "Arg not a JSON hash/object, but a #{h.class}. Cannot create workitem"
+      ) unless h.is_a?(Hash)
+
+      self.new(h)
+    end
+  end
+end
+