flor 0.17.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bf01d8760a78e903218fef2a040fa42551d7273e
-  data.tar.gz: 402f89f60de25ebe27a11c16e3e34fdbd3e8b854
+  metadata.gz: b74ff25bb24e46910557e440ddedc83d07730ec5
+  data.tar.gz: cc0d4de7df8c9a3e39879dfd8968ae70230310c7
 SHA512:
-  metadata.gz: 1132dd0609803767926d6546549d5285a0197837dd512ea2980ce03b8be23c76e43016b3a63c36b4d43fd7bd8a7c055bc1085c482b659ea69fa2da1fa94f894e
-  data.tar.gz: 59498ec443e22d08d01f8708a19dcf7b1b4b41a179e807fa0b6225d10f5642e2a3ab61bb04624c3ad80d9b0b2378d6c4b2b71651bb67bc0c25de5b22e0395120
+  metadata.gz: b2085152306c18636cbd64e9e5d3bc140e6d3b19f2d8afc4111d5283e9da56328a7fc09ab5c2db5fa14f429f3f5f858b87c67c3c6defcb790cb34042608871cb
+  data.tar.gz: 52c344d0deb517f025eb7491201175d44356257c7fae1cad36e8f0a7006a60ec10a3829e0bbc1e7cae2781a0a2ad434e6e84f7499ef9cac94cb0ca095df91643

data/CHANGELOG.md

@@ -2,6 +2,30 @@
 # CHANGELOG.md
 
 
+## flor 0.18.0  released 2019-05-05
+
+* Refine BasicTasker#reply (more arg patterns)
+* Fix "signal" vs exid: and payload:
+* Make payload optional when cancelling
+* Unlock `signal exid: other_execution_id "xxx"`
+* Allow for `trap 'signal0' payload: { a: 'A' }`
+* Allow for "on" in blocking mode (no block given)
+* Turn "sequence" single string att results to tags
+* gh-26, refine cancel / on_cancel and payload return
+* Allow for custom :schema_info migration table
+* Introduce a dedicated #refresh for all flor models
+* Let scheduler sleep only 0.001s if @idle_count less than 1
+* Implement Scheduler #dump and #load
+* Default target #cancel and #kill to node '0'
+* Expose taskname to tasker on detasking (@Subtletree)
+* Refine BasicTasker#reply (more arg patterns)
+* Allow for `trap 'signal0' payload: { a: 'A' }`
+* Allow for "on" in blocking mode (no block given)
+* Unlock `signal exid: other_execution_id "xxx"`
+* Make payload optional when cancelling (default to payload as it was
+  upon reaching the cancelled node)
+
+
 ## flor 0.17.0  released 2019-04-08
 
 - Switch to 0.17.x

data/README.md

@@ -108,13 +108,31 @@ See [doc/](doc/).
 
 ## blog posts and presentations
 
-* [the flor language](http://jmettraux.skepti.ch/20180927.html?t=the_flor_language) - on the flor workflow definition language itself
+* [flor workflow engine](http://jmettraux.skepti.ch/20190407.html?t=flor_workflow_engine&f=readme) - on flor itself
+* [the flor language](http://jmettraux.skepti.ch/20180927.html?t=the_flor_language&f=readme) - on the flor workflow definition language itself
+* [reddit answer on workflow engines](http://jmettraux.skepti.ch/20190416.html?t=reddit_answer_on_workflow_engines&f=readme) - an answer to a Reddit question on workflow engines, archived as a post
 * [Flor, hubristic interpreter](http://rubykaigi.org/2017/presentations/jmettraux.html) - RubyKaigi 2017, Hiroshima - presentation
 * [flor design 0](http://jmettraux.skepti.ch/20171021.html?t=flor_design_0&f=readme) - running a simple execution, what happens - blog post
 * [flor, branch to branch](https://speakerdeck.com/jmettraux/flor-branch-to-branch) - q1 2017 - very dry deck
 * [flor 2017](https://speakerdeck.com/jmettraux/flor-2017) - q1 2017 - very dry deck
 
 
+## other Ruby projects about workflows
+
+There are various other Ruby and Ruby on Rails projects about workflows and business processes, each with its own take on them.
+
+* [Dynflow](http://dynflow.github.io/) - "Dynflow (DYNamic workFLOW) is a workflow engine written in Ruby"
+* [rails_workflow](https://github.com/madzhuga/rails_workflow) - "Rails Workflow Engine allows you to organize your application business logic by joining user- and auto- operations in processes"
+* [rails_engine/workflow_core](https://github.com/rails-engine/workflow_core) - "A Rails engine which providing essential infrastructure of workflow. It's based on Workflow Nets"
+* [Trailblazer](http://trailblazer.to/) - "The Advanced Business Logic Framework"
+
+There is a [workflow engine](https://ruby.libhunt.com/categories/5786-workflow-engine) category on [Awesome Ruby](https://ruby.libhunt.com/).
+
+If you want your engine/library to be added in this list, don't hesitate to ask me on [Gitter](https://gitter.im/floraison/flor) or via a pull request.
+
+It's not limited to Ruby, but there is a wider list at [meirwah/awesome-workflow-engines](https://github.com/meirwah/awesome-workflow-engines).
+
+
 ## license
 
 MIT, see [LICENSE.txt](LICENSE.txt)

data/flor.gemspec

@@ -38,16 +38,16 @@ A Ruby workflow engine (ruote next generation)
     "#{s.name}.gemspec",
   ]
 
-  s.add_runtime_dependency 'munemo', '~> 1.0', '>= 1.0.1'
-  s.add_runtime_dependency 'raabro', '~> 1.1', '>= 1.1.5'
   #s.add_runtime_dependency 'rufus-lru', '~> 1.1'
-  s.add_runtime_dependency 'fugit', '~> 1.1', '>= 1.1.8'
-  s.add_runtime_dependency 'dense', '~> 1.1', '>= 1.1.6'
+  s.add_runtime_dependency 'munemo', '~> 1.0' # >= 1.0 and < 2
+  s.add_runtime_dependency 'raabro', '~> 1.1' # >= 1.1 and < 2
+  s.add_runtime_dependency 'fugit', '~> 1.2' # >= 1.2 and < 2
+  s.add_runtime_dependency 'dense', '~> 1.1' # >= 1.1 and < 2
 
-  s.add_runtime_dependency 'sequel', '~> 5'
+  s.add_runtime_dependency 'sequel', '~> 5.0' # >= 5.0 and < 6
 
-  s.add_development_dependency 'rspec', '~> 3.7'
-  s.add_development_dependency 'terminal-table'
+  s.add_development_dependency 'rspec', '~> 3.8' # >= 3.8 and < 4
+  s.add_development_dependency 'terminal-table', '~> 1.8' # >= 1.8 and < 2
 
   s.require_path = 'lib'
 end

data/lib/flor.rb

@@ -14,7 +14,7 @@ require 'dense'
 
 module Flor
 
-  VERSION = '0.17.0'
+  VERSION = '0.18.0'
   #VERSION = '1.0.0'
 end
 

data/lib/flor/core/executor.rb

@@ -419,15 +419,14 @@ end
 
       last = (message['cause'] ||= [])[0]
 
-      c = {
-        'cause' => cause,
-        'm' => message['m'],
-        'nid' => message['nid'],
-        'type' => message['type'],
-        'at' => last && last['at'] }
+      c = { 'cause' => cause, 'at' => last && last['at'] }
+      %w[ m sm nid type ].each { |k| c[k] = message[k] }
 
       return if c == last
 
+      # argh, the causes in the messages go most recent first
+      # while the statuses in the nodes go most recent last
+
       message['cause'] =
         [ c.tap { |h| h['at'] = Flor.tstamp } ] +
         message['cause']

data/lib/flor/core/procedure.rb

@@ -386,18 +386,30 @@ class Flor::Procedure < Flor::Node
     end
   end
 
+  # From the incoming message, return the most recent cause for this node
+  #
   def message_cause
 
     (@message['cause'] || [])
       .find { |c| c['nid'] == nid }
   end
 
+  # Given the current node status and the incoming message, returns the
+  # upstream cause that lead to the status.
+  # Returns nil if the incoming message is not related to the current status.
+  #
+  def status_cause
+
+    m = node_status['m']
+
+    (@message['cause'] || []).find { |c| c['m'] == m }
+  end
+
   def pop_on_receive_last
 
     orl = @node['on_receive_last']
 
-    return nil unless orl
-    return nil if orl.empty?
+    return nil if orl.nil? || orl.empty?
 
     c = message_cause
 
@@ -411,15 +423,16 @@ class Flor::Procedure < Flor::Node
 
     @node['mtime'] = Flor.tstamp
 
-    orl.each do |m|
-
-      m['from'] = @node['parent'] if m['from'] == 'parent'
+    orl
+      .each do |m|
 
-      #m['payload'] ||= Flor.dup(@node['payload'])
-        # No, let re_applier supply payload
-    end
+        m['from'] = @node['parent'] \
+          if m['from'] == 'parent'
 
-    orl
+        m['payload'] =
+          m.delete('force_payload') ||
+          message['payload']
+      end
   end
 
   def receive_from_child_when_closed
@@ -447,8 +460,21 @@ class Flor::Procedure < Flor::Node
 
     @fcid &&
     Flor.same_branch?(nid, from) &&
-    (c = children[@fcid]) &&
-    c[0] == '_att'
+    (c = children[@fcid]) && c[0] == '_att'
+  end
+
+  def from_keyed_att?
+
+    @fcid &&
+    Flor.same_branch?(nid, from) &&
+    (c = children[@fcid]) && c[0] == '_att' && c[1].size == 2
+  end
+
+  def from_unkeyed_att?
+
+    @fcid &&
+    Flor.same_branch?(nid, from) &&
+    (c = children[@fcid]) && c[0] == '_att' && c[1].size == 1
   end
 
   def from_sub_nid
@@ -828,6 +854,16 @@ class Flor::Procedure < Flor::Node
   #
   def do_cancel
 
+    @message['payload'] ||= Flor.dup(@node['payload'])
+      #
+      # Ensure the 'cancel' message has a payload.
+      # If not, let's use the payload as it was upon reaching this node.
+
+    return wrap if node_closed? && status_cause
+      #
+      # if the node is cancelled and that is caused by a message upstream
+      # that caused the incoming message, simply reply immediately...
+
     if orl = @message['on_receive_last']
       #
       # the message on_receive_last is used by the re_apply feature

data/lib/flor/flor.rb

@@ -616,9 +616,7 @@ module Flor
     #
     def migration_dir
 
-      File.absolute_path(
-        File.join(
-          File.dirname(__FILE__), 'migrations'))
+      File.join(__dir__, 'migrations')
     end
 
     def caller_fname

data/lib/flor/log.rb

@@ -106,6 +106,12 @@ module Flor
         a << " #{_c.dg}#{k}:#{m[k]}" if m.has_key?(k)
       end
 
+      #a << " #{_c.dim}#{_c.dg}"
+      #a << "pl#{Flor.to_d(m['payload'], compact: true, colors: false)}"
+        #
+        # keep that around for when debugging payload shifts
+        # eventually consider FLOR_DEBUG flag
+
       a << _c.rs
 
       a.join

data/lib/flor/pcore/_dmute.rb

@@ -12,7 +12,10 @@ class Flor::Pro::Dmute < Flor::Procedure
           'from' => Flor.child_nid(nid, 999 + tree[1].size),
             # "#{nid}_#{999 + child.count}"
           'exid' => exid,
-          'payload' => @message['payload'].merge('ret' => '') } ] ]
+          'force_payload' => @message['payload'].merge('ret' => '') } ] ]
+            #
+            # using 'force_payload' to tell Procedure#pop_on_receive_last
+            # to use this payload
   end
 end
 

data/lib/flor/pcore/break.rb

@@ -59,7 +59,8 @@ class Flor::Pro::Break < Flor::Procedure
   def receive_last
 
     ref = att('ref')
-    nid = tags_to_nids(ref).first || @node['heat'][1]['nid']
+    nid = tags_to_nids(ref).first || target_nid
+      # nid derived from tag or target nid given by parent "cursor"
 
     payload['ret'] = att(nil) if has_att?(nil)
 
@@ -80,5 +81,15 @@ class Flor::Pro::Break < Flor::Procedure
 
     ms
   end
+
+  protected
+
+  def target_nid
+
+    # this nid is given by the parent "cursor" via a "break" or "continue"
+    # variable
+
+    @node['heat'][1]['nid']
+  end
 end
 

data/lib/flor/pcore/on.rb

@@ -100,6 +100,20 @@ class Flor::Pro::On < Flor::Macro
   # If it were, it would trap the signal named "timeout".
   #
   #
+  # ## blocking mode
+  #
+  # When "on" is given no code block, it will block.
+  # ```
+  # sequence
+  #   # ...
+  #   on 'green'  # execution (branch) blocks here until signal 'green' comes
+  #   # ...
+  # ```
+  #
+  # Behind the scenes, it simply rewrites the "on" to a "trap" without a
+  # function, a blocking trap.
+  #
+  #
   # ## see also
   #
   # Trap and signal.
@@ -166,16 +180,26 @@ class Flor::Pro::On < Flor::Macro
     l = tree[2]
 
     th = [ 'trap', [], l, *tree[3] ]
+
     th[1] << [ '_att', [ [ 'point', [], l ], [ '_sqs', 'signal', l ] ], l ]
     th[1] << [ '_att', [ [ 'name', [], l ], tname ], l ]
-    th[1] << [ '_att', [ [ 'payload', [], l ], [ '_sqs', 'event', l ] ], l ]
-    atts.each { |ac| th[1] << Flor.dup(ac) }
 
-    td = [ 'def', [], l ]
-    td[1] << [ '_att', [ [ 'msg', [], l ] ], l ]
-    non_att_children.each { |nac| td[1] << Flor.dup(nac) }
+    att_names = []
+    atts.each { |at|
+      att_names << at[1][0][0]
+      th[1] << Flor.dup(at) }
 
-    th[1] << td
+    th[1] << [ '_att', [ [ 'payload', [], l ], [ '_sqs', 'event', l ] ], l ] \
+      unless att_names.include?('payload')
+
+    if (nac = non_att_children).any?
+
+      td = [ 'def', [], l ]
+      td[1] << [ '_att', [ [ 'msg', [], l ] ], l ]
+      non_att_children.each { |nac| td[1] << Flor.dup(nac) }
+
+      th[1] << td
+    end
 
     th
   end

data/lib/flor/pcore/sequence.rb

@@ -9,14 +9,62 @@ class Flor::Pro::Sequence < Flor::Procedure
   #   task 'bravo' if f.amount > 2000
   #   task 'charly'
   # ```
+  #
+  # Giving a string as attribute result to "sequence" lets it interpret
+  # that string as a tag name, as in:
+  # ```
+  # sequence 'phase one'
+  #   alice 'gather customer requirements'
+  #   bob 'establish offer'
+  # sequence 'phase two'
+  #   alice 'present offer to customer'
+  #   bob 'sign contract'
+  # ```
+  # It is equivalent to:
+  # ```
+  # sequence tag: 'phase one'
+  #   alice 'gather customer requirements'
+  #   bob 'establish offer'
+  # sequence tag: 'phase two'
+  #   alice 'present offer to customer'
+  #   bob 'sign contract'
+  # ```
+  # Learn more about [tags](../tags.md).
+  #
+  # Please note that it sets only 1 tag, and if there are already tags
+  # sets (`sequence tags: [ 'a' 'b' ] "this won't become a tag"`), it won't set
+  # further tags.
+  #
+  # ## see also
+  #
+  # Concurrence, loop
 
   names %w[ sequence begin ]
 
+  def receive_att
+
+    ms = []
+
+    ms = enter_tag \
+      if @node['tags'].nil? && payload_ret.is_a?(String) && from_unkeyed_att?
+
+    ms + super
+  end
+
   def cancel_when_closed
 
     return cancel if node_status_flavour == 'on-error'
 
     []
   end
+
+  protected
+
+  def enter_tag
+
+    @node['tags'] = tags = [ payload_ret ]
+
+    wrap('point' => 'entered', 'nid' => nid, 'tags' => tags)
+  end
 end
 

data/lib/flor/punit/cancel.rb

@@ -29,7 +29,15 @@ class Flor::Pro::Cancel < Flor::Procedure
   # ```
   # But it's kind of brittle compared to using tags.
   #
-  # # TODO document "kill"
+  # ## kill
+  #
+  # "kill" is equivalent to "cancel", but once called, cancel handlers are
+  # ignored, it cancels through.
+  #
+  #
+  # ## see also
+  #
+  # On_cancel, on
 
   name 'cancel', 'kill'
     # ruote had "undo" as well...

data/lib/flor/punit/signal.rb

@@ -51,6 +51,26 @@ class Flor::Pro::Signal < Flor::Procedure
   # flor_unit.signal('close', exid: execution_id, payload: { 'f0' => 'zero' })
   # ```
   #
+  # ## signalling another execution
+  #
+  # If the exid of execution A is known in execution B, execution B can
+  # send a signal to A.
+  #
+  # ```ruby
+  # exid0 = @unit.launch(
+  #   %q{
+  #     trap signal: 'green' # block until receiving the 'green' signal
+  #     set f.done true
+  #   })
+  # @unit.launch(
+  #   %q{
+  #     set f.a 'a'
+  #     signal exid: f.exid0 'green' # send 'green' signal to exid0
+  #     set f.b 'b'
+  #   },
+  #   payload: { 'exid0' => exid0 })
+  # ```
+  #
   # ## see also
   #
   # On and trap.
@@ -64,14 +84,18 @@ class Flor::Pro::Signal < Flor::Procedure
 
   def receive_last
 
-    name = att('name', nil)
+    na = att('name', nil)
+    ei = att('exid') || exid
+    pl = att('payload') || payload.copy_current
 
-    return super unless name
+    return super unless na
 
     wrap(
-      'point' => 'signal', 'nid' => nid, 'name' => name,
-      'payload' => payload.copy_current
-    ) + super
+      'point' => 'signal',
+      'exid' => ei, 'nid' => nid,
+      'name' => na, 'payload' => pl
+    ) +
+    super
   end
 end