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):
c = CallOnce { |flag| if(flag) { "woking...".postln; "done:" + flag } };c.value(true); // -> done: true (and posts "woking...")c.value(false); // -> done: true (nothing posted)| function |
a function that typically executes some cleanup and may return a desired value. The function is wrapped in the CallOnce for later execution. |
Cancels the CallOnce, meaning that subsequent calls to value will not execute the wrapped function at all.
the CallOnce.
Report if the CallOnce is considered already evaluated.
false if neither clear nor value were called previously; true otherwise.
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.
| ... args |
Arguments to use in the call to the wrapped function, if the call happens. If |
nil if clear was called on the CallOnce before any calls to value, otherwisevaluer = 1; // some resourcec = CallOnce { r = r - 1; postln("Resource is now released:" + r); r };c.didEvaluate; // -> falsec.value; // -> 0 (and posts "Resource is now released: 0")c.didEvaluate; // -> truec.value; // -> 0 (but posts nothing)c.clear; // even if is "cancelled" nowc.value; // -> 0; the computed value is preservedc = CallOnce { "not called".postln }c.didEvaluate; // -> falsec.clear; // "cancels" the cleanupc.didEvaluate; // -> truec.value; // -> nil// use with an argument(r = 1; // some resourcec = CallOnce { |releaseResource| if(releaseResource) { r = r - 1; "Resource is now released:" + r } { "nothing to do" }};)d = c.copy // saved for later, separate execution state// correct use sequence (non-increasing cleanup-work sequence):c.value(true);c.value(true);c.value(false);r; // -> 0d.didEvaluate; // -> false (copy didn't evaluate yet)// semantically incorrect (contract breaking) use sequenced.value(false) // -> nothing to dod.value(true) // -> nothing to do