CallOnce:
Filter:

CallOnce : Thunk : AbstractFunction : Object

execute a function (at most) once

Description

Unlike a Thunk, which takes no arguments, a CallOnce does allow arguments to be passed to the function it wraps, but the function is executed at most once. A CallOnce can also be "cancelled" with a clear call, without ever executing the wrapped function, even if CallOnce's value is called later.

The general contract for CallOnce is that any calls into the function after the first would do the same or less (cleanup) work as the first call did. Thus, subsequent calls are completely redundant and can be answered with the result from the first call, even if the arguments change on subsequent calls. Prototypical use case: if a cleanup is called with a releaseResource: false argument, e.g. because the resource was already released by CmdPeriod, it is assumed that the cleanup will not be called later with a releaseResource: true argument.

Since it executes its function (at most) once, CallOnce is not a general-purpose function memoization facility for functions with arguments.

Basic example (see end of page for more):

Class Methods

CallOnce.new(function)

From superclass: Thunk

Arguments:

function

a function that typically executes some cleanup and may return a desired value. The function is wrapped in the CallOnce for later execution.

Inherited class methods

Instance Methods

.clear

From superclass: Thunk

Cancels the CallOnce, meaning that subsequent calls to value will not execute the wrapped function at all.

Returns:

the CallOnce.

.didEvaluate

From superclass: Thunk

Report if the CallOnce is considered already evaluated.

Returns:

false if neither clear nor value were called previously; true otherwise.

.value( ... args)

If clear was called previously, the value call has no side-effect. Otherwise, on the first call to value the function wrapped by the CallOnce is evaluated with the arguments provided to value and the result of this evaluation is stored as the CallOnce's result, used to answer all subsequent calls to value.

Arguments:

... args

Arguments to use in the call to the wrapped function, if the call happens. If didEvaluate already returns true (before the current call to value) then the current args are irrelevant because the wrapped function is not called anymore.

Returns:

  • nil if clear was called on the CallOnce before any calls to value, otherwise
  • the value that was computed by the function (wrapped by the CallOnce) on the first call to CallOnce's value

Inherited instance methods

Undocumented instance methods

.prEvaluate(selector, args)

.valueArray( ... args)

.valueArrayEnvir( ... args)

.valueEnvir( ... args)

Examples

helpfile source: https://github.com/supercollider/supercollider/tree/3.13/HelpSource/Classes/CallOnce.schelp
link::Classes/CallOnce::