Introducing Local Parameters in OCaml

I want to start a series about local mode, an idea developed in Jane Street's experimental branch of the OCaml compiler. This branch is where we try and refine ideas with the goal of eventually upstreaming them into the main compiler. For now, local mode is available in the Jane Street compiler for us to explore.

We'll work through how local affects the type system, piece by piece. The eventual payoff is allocation behavior that can make latency-sensitive code faster, but I think understanding the type-level behavior first is a better way to approach it than jumping straight to allocation.

I'm using Jane Street's version of OCaml 4.14.1. Local is a mode, not exactly a type, so I don't want to call these local types. In the examples I'll write full type annotations on my let bindings: inference works with local mode, but explicit signatures give us more compact examples and better error messages.

Start with a simple function and add the local annotation to its parameter. This says the parameter does not escape the function. If the function returns that local parameter, the compiler reports that the value escapes its region: returning it breaks the promise made by the annotation.

With a function of two arguments, the annotation can apply only to the first, x. Returning x causes the escape error, but returning the unannotated second argument y compiles. We have made a promise about x, not about y.

A region is an area of code. For now, we can think of every function as defining a region, although there is an exception that I'll explain in a later video. A local parameter cannot escape its region, and returning it is one way to do that.

Storing a local value elsewhere is another way to escape. For example, if x is a local string parameter and I assign it to an external string reference, the compiler rejects the assignment even when the function returns y. The local annotation promises callers that the argument will not escape.

Why is that useful? Suppose a type has a mutable string field and a function f takes its first argument locally. A caller can call f with t1 and t2 and later mutate t1. Since f cannot retain t1, the caller can reason that the later mutation won't affect f's retained relationship to that argument or a value returned by f.

Local parameters are also useful for callbacks. Imagine a with_file function taking a filename and a callback whose file-handle parameter is local. Once the callback finishes, the enclosing function knows the handle has not been stored or returned by it, so it can close the file. Without this guarantee, we would have to trust the callback not to keep the handle.

The annotation restricts the implementation of the function, not what a caller may pass. A local parameter can receive a local or a global argument. The restriction against returning or storing that argument is the promise the function makes to every caller; this is only the beginning of the exploration.