IncrementalFunction
IncrementalFunction[fun]
represents a compilable function that can pause its execution, storing its state to be resumed later.
Details
- Incremental functions have to be processed by compiler functions such as FunctionCompile.
- An active incremental function is held with a data structure of type "IncrementalFunction".
- In compiled code, an incremental function is held as an "IncrementalFunction" type.
- Incremental functions can return incremental results with IncrementalYield.
- When the "Send" operation is used to resume an incremental function, the value is accepted with IncrementalReceive.
- Incremental functions can receive incremental values with IncrementalReceive.
- An incremental function does not ever need to finish executing.
- An incremental function can incrementally return a sequence of results.
- An incremental function that reaches the end of its code cannot be resumed.
- When the data structure that holds a running incremental function is no longer used, the function is terminated and any resources it holds are released.
- Any number of instances of an incremental function can be active at any one time.
- An incremental function can recursively call itself or other incremental functions.
- An active incremental function ds can be restarted with ds["Next"] and ds["Send",x].
Examples
open all close allBasic Examples (2)
An incremental function that has one yield:
func = IncrementalFunction@Function[Typed[arg, "MachineInteger"], IncrementalYield[arg + 1];];A CompiledCodeFunction that returns an "IncrementalFunction" data structure:
comp = FunctionCompile[func]Create an instance of the incremental function:
ds = comp[10]Run the incremental function to the IncrementalYield and return the partial result:
ds["Next"]The incremental function has finished, so calling the "Next" operation results in a failure:
ds["Next"]An incremental function that returns a sequence of multiples of its argument:
comp =
FunctionCompile@IncrementalFunction@
Function[Typed[num, "Integer64"],
Module[{mul = num}, While[True, IncrementalYield[mul += num]]]
];An instance of the incremental function that returns multiples of 7:
ds = comp[7]The first result from the incremental function:
ds["Next"]ds["Next"]Table[ds["Next"], 100]A different instance of the incremental function that returns multiples of 17:
ds1 = comp[17]The first 100 multiples of 17:
Table[ds1["Next"], 100]The function that is returning multiples of 7 is still waiting to be woken up and return results:
Table[ds["Next"], 100]Scope (2)
An incremental function can be used in a FunctionDeclaration, and in this way can call itself:
decl =
FunctionDeclaration[
incrementalFlatten,
Typed[ {"InertExpression"} -> "IncrementalFunction"["InertExpression", "Null"]]@
IncrementalFunction@
Function[{expr},
If[AtomQ[expr]
,
IncrementalYield[expr];
,
Do[ IncrementalYield[res], {elem, expr}, {res, incrementalFlatten[elem]}]
]]];
comp = FunctionCompile[decl, Function[Typed[ arg, "InertExpression"], incrementalFlatten[arg]]];Create a running incremental function with an expression input:
ds = comp[ {1, 2, {a, b, d}, g[10, 20]}]This function will yield the elements of the input expression in a depth-first fashion:
ds["Next"]ds["Next"]ds["Next"]An incremental function must use the Wolfram Compiler, but it can work with Wolfram expressions:
comp =
FunctionCompile@IncrementalFunction@
Function[{Typed[fname, "InertExpression"], Typed[elem, "InertExpression"]},
Module[{stm, data, dataQ = True},
stm = InertEvaluate[InertExpression[OpenRead][fname]];
If[FailureQ[stm],
Return[]];
While[
dataQ,
data = InertEvaluate[InertExpression[Read][stm, elem]];
If[data === InertExpression[EndOfFile],
dataQ = False,
IncrementalYield[data];
]
];
InertEvaluate[InertExpression[Close][stm]];
]
];A running incremental function that will open a file and yield increments of data:
ds = comp["ExampleData/numbers", "Number"]ds["Next"]ds["Next"]A different running instance of the same incremental function that reads data in a different way:
ds1 = comp["ExampleData/numbers", {"Number", "Number", "Number"}]ds1["Next"]Neat Examples (1)
An incremental function is useful for returning one result at a time, as in this Game of Life implementation:
compGOF = FunctionCompile@IncrementalFunction[
Function[{Typed[state, "PackedArray"::["MachineInteger", 2]]},
Module[{current = state, nrows, ncols, neighborSum, next},
{nrows, ncols} = Dimensions[state];
neighborSum = Function[{grid, i, j},
Module[{total = 0},
Do[
total += grid[[Mod[i + di, nrows, 1], Mod[j + dj, ncols, 1]]],
{di, -1, 1},
{dj, -1, 1}
];
total
]
];
While[True,
IncrementalYield[current];
next = Table[
With[{sum = neighborSum[current, i, j]},
If[current[[i, j]] == 1,
Switch[sum,
0 | 1,
0
,
2 | 3,
1
,
_,
0
]
,
If[sum == 3, 1, 0]
]
],
{i, nrows}, {j, ncols}
];
current = next;
]
]
]
]Start the incremental function with a random initial state:
initial = RandomInteger[1, {100, 100}];
golInstance = compGOF[initial]ListAnimate@Table[ArrayPlot[golInstance["Next"]], 42]Text
Wolfram Research (2025), IncrementalFunction, Wolfram Language function, https://reference.wolfram.com/language/ref/IncrementalFunction.html.
CMS
Wolfram Language. 2025. "IncrementalFunction." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/IncrementalFunction.html.
APA
Wolfram Language. (2025). IncrementalFunction. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/IncrementalFunction.html