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

src/regions/regions.x

Values that can outlive the region that allocated them.

Functions

Compiler

Compiler.audit_regions

Map Compiler.audit_regions( Compiler c, List ast, Map seed, Map effects, Array findings)

Computes one unit’s region summaries and findings for an optional project audit. seed contains prior project-round summaries indexed by the emitted names visible in this unit. effects adds audit-only native contracts; neither input changes ordinary translation. Findings carry their function name and are returned without compiler diagnostics.

Source: src/regions/analysis.x:166

Compiler.check_meta_regions

void Compiler.check_meta_regions(Compiler c, List fn)

Rejects a meta function whose body breaks the rule Compiler.check_regions warns about. A compile-time call frees its locals when it returns, so an address of one that is returned or stored into a static, a parameter’s object, or an unknown pointer would read freed memory. The first finding is reported as an error. fn must be the bound and typed definition. The walk reads the summaries of the meta functions installed before fn and records the summary of fn in meta_regions.

Source: src/regions/analysis.x:147

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/analysis.x:126

Compiler.has_region_row

int Compiler.has_region_row(String name)

Reports whether the runtime table proves the lifetime effects of the native function name.

Source: src/regions/runtime.x:188

Compiler.region_effect

Var Compiler.region_effect(String name)

The runtime table’s effect row for the operation name, such as (open scope) or (exit), or void when the table has no row.

Source: src/regions/runtime.x:192

Compiler.region_result

Symbol Compiler.region_result(String name)

The owner of the storage the runtime operation name returns: <scope> for the active Scope, <slot> for the Scope its first argument names, <pool> for the canonical-value pool, or 0 when nothing is known. What the operation does to its arguments is a separate fact.

Source: src/regions/runtime.x:172

Compiler.region_wrapper

int Compiler.region_wrapper(String name)

Reports whether the runtime operation name returns its argument’s storage unchanged, as a Var box or its unboxing does.

Source: src/regions/runtime.x:184

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, a Scope local that Scope.destroy ends, or the function’s own storage, which an address taken with & borrows. 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 and when a local is read after it was freed.

A function’s summary is two facts: which owner supplies fresh returned 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 warnings do not depend on which units were translated before it. A meta function is walked when it is defined, against the summaries of the meta functions before it, and a finding there is an error, because a compile-time call frees its locals when it returns.

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