OCaml Local Types: Regional Parameters and Loop Regions

This episode continues the series on local values in Jane Street’s publicly available OCaml compiler branch. I want to explain regions and a hidden mode called regional, using examples that initially appear to violate the rules from earlier videos.

Consider an identity function with a parameter annotated as a local string. It compiles, and the inferred type takes a local string and returns a local string. That seems surprising: every function defines a region, and a local value is not supposed to escape its region.

A second example is a recursive iterator over a list. It accepts a function, applies it to each head and makes a tail-recursive call on the remainder. Marking the function parameter local permits a caller to provide a closure without necessarily allocating that closure on the heap.

The iterator still compiles even though the recursive call is a tail call, which lies outside the current function’s region. Why can the function parameter be passed there? The identity function’s return and the iterator’s tail call both seem to allow local values to escape.

The explanation is that a parameter marked local is treated as regional inside the function. Regional is a hidden mode, not a keyword that can be written in the program. A regional value may escape one region, though it does not have to escape at all.

A parameter must have been supplied by a caller, so it already lives beyond the callee’s own region. Letting it cross that one boundary is safe. In the identity example, the returned string is local to the caller: it cannot simply become global, which would allow an actually local value to escape too far.

In the iterator, the function argument is also regional within the current invocation. It can therefore cross the boundary at the tail call and be passed to the next invocation, even though the current function’s region ends before that call.

To show the distinction, I pass the iterator’s function argument through an identity function whose type takes and returns a local value. Its result is known only as local; the type does not preserve the fact that the original argument was regional. Passing that result to the tail call now produces an escaping-local error.

Regions also surround loop bodies. I rewrite the iterator to traverse an array with a for loop and call the function for each element. The example is about the lifetime of local allocations made while the loop runs.

If the called function returns locally, its local allocations are made in its parent’s region—in this case, the loop-body region. Each time an iteration ends, that region can be reclaimed before the next iteration. Without such a boundary, repeated work could accumulate space across the loop.

The presenter notes that the loop rule is less consequential for typing in this example because loops do not normally return a value except via mechanisms such as references. It is still useful for understanding allocation behavior: local allocations in a loop’s region end with the iteration.