More

Meta

Search

configuration

Before evoking configuration it’s perhaps a good idea to have a look at the post announcing ruote 2.1, it’s detailing the design decisions behind ruote 2.1. It helps understand the 3 objects detailed in this page, engine, worker and storage.

In ruote 2.1, the engine class became shallow, just a few methods that insert launch and reply orders in the storage and read it when querying for process statuses.

The real engine is composed of a storage (persistent core) and of one or more workers.

Storage implementations are meant to be process/thread safe, ie they can be used by multiple worker processes and engines.

The engine class is nothing more than a dashboard, with indicators and a few knobs.

This is the ruote configuration you can see in the entry page of this documentation :

engine options

participant_threads_enabled: (from ruote 2.3.0 on)

Defaults to true.

By default, the dispatching of workitems to participants is done in a new Ruby thread. The goal is not to block the worker with potentially lengthy operations. Dispatching via a homing pigeon, for example, is a costly operation, you have to take the pigeon out of his cage, attach the message, and set it free… By default such blocking operations are performed in their own threads.

In deployments where multi-workers are the norm, having one worker blocked dispatching is no problem. In such contexts, turning off the threaded dispatching is OK.

remote_definition_allowed:

Defaults to false.

Remote definitions are process definitions reachable over HTTP. Since process definition are ‘code’, ruote, by default, prevents you from doing things like

(this setting only makes sense in “1 worker – test/development” environments, in other environments, just leave it alone)

The WaitLogger is a component inside of ruote that keeps track of the 147 latest messages processed by the local worker (if any). This 147 number can be tuned thanks to the ‘wait_logger_max’ option.

preserve_configuration:

Default to false.

More of a storage configuration. When set to true, the engine/worker/storage group will not write any configuration to the persistence behind the storage. It will simply read.

This option is useful in multi-worker setting, when configuration is done once and then read by the workers.

restless_worker:

Defaults to false.

More of a worker configuration. When set to true, the worker will not sleep between its storage polls for msgs and schedules to execute. This option is set to true by some storage implementations, those that block in a connection with their persistence backend and get pushed msgs and/or schedules.

Safely ignore this option.

worker_state_enabled:

Defaults to false.

When set to true, “unlocks” the #worker_state= method of Ruote::Dashboard (Ruote::Engine). Possible states are “running” (default), “paused” and “stopped”. Workers reads that state and pause/resume/stop accordingly. Please note that a stopped worker won’t read state further since it’s stopped and gone, use “paused” for pause/resume.

engine on_error / on_terminate

There are the on_error and the on_cancel attributes common to all expressions. Engine#on_error and #on_terminate are quite close to those, but there is an important catch. The on_error attribute will cancel the expression to which it is attached and then run the on_error ‘routine’, while Engine#on_error runs independently of the process whose error triggered the reaction. Same thing for on_terminate.

The processes triggered by on_error and on_terminate are independent processes (but they do not trigger further on_error / on_terminate, cascade prevention).

on_error

Each time an unchecked error occurs in a process instance, the participant or the subprocess given in on_error will get triggered.

# you can pass a participant name
engine.on_error = 'administrator'
# or a subprocess name
engine.on_error = 'error_procedure'
# or directly a subprocess definition
engine.on_error = Ruote.define do
concurrence do
administrator :msg => 'something went wrong'
supervisor :msg => 'something went wrong'
end
end

The workitem used in the on_error “handler” is a copy of the workitem at the error point.

engine on_terminate

This handler launches a subprocess each time a process instance terminates in a regular way.

Its usage is similar to Engine#on_error :

# you can pass a participant name
engine.on_terminate = 'archiver'
# or a subprocess name
engine.on_terminate = 'archival_procedure'
# or directly a subprocess definition
engine.on_terminate = Ruote.define do
concurrence do
supervisor :msg => 'process ${wfid} terminated'
archiver
end
end

The workitem passed to the triggered process instance is a copy of the one in the process that just terminated.

worker

As of now, there are no configuration options for workers. They don’t complain, they are not syndicated, they just work.

storage

Workflows / business processes usually involve real persons, humans. They are slower than computers. These days processes also imply multiple systems / services. These two things imply that workflows / processes may last a long time. Persistence is necessary, this is done with the storage.

Since workers share the storage, it has not only to provide reliable persistence but also helpers to avoid worker collisions.

The following table summarizes the various storage implementations.

multiple workers tells if yes or no the storage supports multiple workers;remote worker indicates if workers not on the same host as the storage are possible;speed is a relative indication of the speed of the storage.