onlycall

onlycall, function

def pure onlycall(max: number): boolean

Reports an error and causes the script to fail if called more than max times in a single execution scope. Otherwise, returns true.

• max: the maximum number of times this specific call can be made.

Example

table T = extend.range(10)
T.M = onlycall(T.5)

This outputs the following error message:

‘onlycall()’: called 5 times.

Remarks

This function returns true because its intended use is as an if expression condition:

if onlycall(10m into T) then T.realValue else 0

Using it in this fashion ensures that the function is not eliminated by any optimization.

What is counted ?

Two separate uses of onlycall in two different locations in a script always count their number of executions separately. Note that each iteration of a loop block counts as a separate location for this purpose.

A single use of onlycall will always count all its executions when used in one of the following contexts:

• on a vector of a small table.
• inside a for block or each block that either uses keep variables or operates on a small table.
• inside a non-parallel montecarlo block or a non-parallel autodiff block

Outside of the above cases, Envision may partition the execution of the code in order to parallelize it over multiple cores/machines, causing onlycall to underestimate the actual number of calls.

Errors

Calling onlycall more than its specified number of times (or specifying a number of times < 1) will report an error message:

‘onlycall()’: called 5 times.