OM# Documentation

Eval-Once Mode

The “eval-once” mode is one of the possible lock-state of OM# boxes, which allows for the box to be reevaluated only once per global request.

A “global request” is either:

• A user- or external evaluation request in a top-level patch, or
• A call to a sub-patch or abstraction (inside this patch).
• An iteration inside a loop.

IMPORTANT: Default Eval-Once

The “Auto ev-once” option in OM# General Preferences removes the possibility of user-personalised behaviors and automatically sets every boxes to the “eval-once” mode behavior.

In manual mode (when the “Auto ev-once” preference is off):

Use the key 1, or the inspector view to set/unset the eval-once mode for selected boxes.

The eval-once mode changes the number of times a box is evaluated if this box value is requested several times, that is, essentially:

• if the box is connected to several other boxes through one or several of its outputs
• if the box is connected to a REPEAT-N box with :local scope (see below).

It has an impact on computational cost (and time!), by avoiding multiple, unnecessary executions of the same box.
It can also have an impact on the results, when the box or some of its upstream dependencies are not fully deterministic.

Examples

In the first example below, the om-random box is evaluated 3 times in the “normal” case, and only 1 time if the eval/once mode is on.

In the second example eval-once is set to another downstream box (list), making the call to om-random happen 3 times only, at the first evaluation of the list box.

Eval-Once and the REPEAT-N box

REPEAT-N is a special box which simulates N successive calls to a box.
It’s optional input scope affects the behavior of boxes that are connected to it, and in the eval-once state.

• If scope = :global the “eval-once context” lasts during the whole patch execution (just like a normal function).
• If scope = :local each iteration end reinitializes the “eval-once context”, and boxes are evaluated again at the first time of the next iteration.

See also the help-patch “repeat-n” in the OM# distribution.

Multiple outputs

The eval-once mode makes particular sense for any box with multiple outputs, when several of these outputs are evaluated.
Below are typical examples where the eval-once mode should generally be on (if not set by default in the preferences) in order to avoid multiple, unnecessary computations and sometimes, inconsistent results:

1) 2) 3)

In these different cases, the boxes in “eval-once” mode would otherwise be evaluated several times, which can be useless/costly, but also potentially wrong if different values result from the successive evaluations.

Hint: Keep the “Auto ev-once” option on in the OM# preference to avoid worrying about these different cases !