This expression is a cross between ‘concurrence’ and ‘iterator’.

Please look at the documentation of ‘iterator’ to learn more about the common options between ‘iterator’ and ‘concurrent-iterator’.

  pdef = Ruote.process_definition :name => 'test' do
    concurrent_iterator :on_val => 'alice, bob, charly', :to_var => 'v' do
      participant '${v:v}'
    end
  end

will be equivalent to

  pdef = Ruote.process_definition :name => 'test' do
    concurrence do
      participant 'alice'
      participant 'bob'
      participant 'charly'
    end
  end

The ‘on’ and the ‘to’ attributes follow exactly the ones for the iterator expression.

When there is no ‘to’, the current iterated value is placed in the variable named ‘i’.

The variable named ‘ii’ contains the current iterated index (an int bigger or egal to 0).

‘concurrent_iterator’ does not understand commands like rewind/break/jump/… like ‘iterator’ does, since it fires all its branches when applied.

:on and arrays

Given a workitem field named ‘x’ containing the array value

‘a’, ‘b’, ‘c’

and a workitem field ‘y’ containing the string ‘a, b, c’,

this:

  concurrent_iterator :on_field => 'x', :to_f => 'xx' do
    # ...
  end

is equivalent to

  concurrent_iterator :on => '$f:x', :to_f => 'xx' do
    # ...
  end

is equivalent to

  concurrent_iterator :on => '${f:y}', :to_f => 'xx' do
    # ...
  end

:to_field and :to_f, :to_var and :to_v, :to

Those 4 lines are equivalent:

    concurrent_iterator :on => [ 'ceo', 'cto' ], :to_field => 'a' do ...
    concurrent_iterator :on => [ 'ceo', 'cto' ], :to_f => 'a' do ...
    concurrent_iterator :on => [ 'ceo', 'cto' ], :to => 'f:a' do ...
    concurrent_iterator :on => [ 'ceo', 'cto' ], :to => 'a' do ...

Those 3 lines are equivalent:

    concurrent_iterator :on => [ 'ceo', 'cto' ], :to_var => 'a' do ...
    concurrent_iterator :on => [ 'ceo', 'cto' ], :to_v => 'a' do ...
    concurrent_iterator :on => [ 'ceo', 'cto' ], :to => 'v:a' do ...

:times and :branches

Similarly to the iterator expression, the :times or the :branches attribute may be used in stead of the ‘on’ attribute.

  pdef = Ruote.process_definition :name => 'test' do
    concurrent_iterator :times => 3 do
      participant 'user${v:i}'
    end
  end

is equivalent to

  pdef = Ruote.process_definition :name => 'test' do
    concurrence do
      participant 'user0'
      participant 'user1'
      participant 'user2'
    end
  end

ruote 2.3.0 and the citerator children

Prior to ruote 2.3.0, the concurrent-iterator only considered one child expression:

  concurrent_iterator :times => 3 do
    participant 'al'
    participant 'bob' # 'bob' would never be reached
  end

So one had to write:

  concurrent_iterator :times => 3 do
    sequence do
      participant 'al'
      participant 'bob' # 'bob' would never be reached
    end
  end

Ruote 2.3.0 lifts that restriction.

options

the concurrent_iterator accepts the same options for merging as its bigger brother, the concurrence expression.

:count, :merge (override, mix, isolate, stack, union, concat, deep, ignore), :remaining (cancel, forget) and :over.

add branches

The ‘add_branches’/’add_branch’ expression can be used to add branches to a concurrent-iterator while it is running.

  concurrent_iterator :on => 'a, b, c' do
    sequence do
      participant :ref => 'worker_${v:i}'
      add_branches 'd, e', :if => '${v:/not_sufficient}'
    end
  end

In this example, if the process level variable ‘not_sufficient’ is set to true, workers d and e will be added to the iterated elements.

Read more at the ‘add_branches’ expression description.

‘citerator‘

‘citerator’ is an alias for ‘concurrent_iterator’.

  pdef = Ruote.process_definition :name => 'test' do
    citerator :on_val => 'alice, bob, charly', :to_var => 'v' do
      participant '${v:v}'
    end
  end