Provisional API: This reference documents current compiler behavior. Compatibility is not yet promised.

src/regions.x

Values that can outlive the region that allocated them.

Functions

Compiler

Compiler.check_regions

void Compiler.check_regions(Compiler c, List ast)

Warns about values that can outlive the region that allocated them. ast must be the bound and typed top-level unit, before transform lowering rewrites its defer and region forms. The call adds warnings to c and does not change ast.

Source: src/regions.x:821

Compiler.region_escapes

List Compiler.region_escapes(Compiler c, List ast, List seed)

The region summaries the functions in ast have and the warnings they produce, read against seed: (NAME FRESH SINKS) rows for the functions other units define. ast must be what Compiler.check_regions takes. The call reports nothing, so a caller that walks a whole project can run it once a pass and report only the last. Returns (region-unit (summaries ROW...) (warnings WARNING...)), where a warning is (warning (at PATH LINE COLUMN) CODE MESSAGE (notes NOTE...)).

Source: src/regions.x:857

Design notes

A region is a $scope() block, a Scope.retain and Scope.release pair, a $scope(&slot) push, a Pool.open bracket, an $auto local, or a Scope local that Scope.destroy ends. The pass reads the typed forms the parser produced, before the transform driver rewrites them, so a region is still the call that opens it and the defer beside it that closes it. It warns when a value born in a region reaches storage that outlives the region, when a region is opened without its close in the same block, and when a local is read after it was freed.

A function’s summary is two facts: whether it returns fresh storage, and where each parameter is sunk. The unit’s functions reach a fixpoint over their summaries. A call into another unit has a summary only through the runtime table, so a unit’s warnings do not depend on which units were translated before it. A tool that holds every unit at once can seed the fixpoint with the other units’ summaries through Compiler.region_escapes.

The warnings name departures from the lexical pattern. Raw C stores, pointer arithmetic, callbacks, and storage the runtime did not allocate stay outside them.