Rule 8.25

Chapter 8, Functions and entry points Test

A parameter declared Ref<T> names the caller’s place, and the call passes it as ref(place): reading the parameter reads that place, and assigning to it, or to a field, component or element of it, writes it, for the call. A Ref<T> parameter belongs to a function declared at the top of the file or of a namespace; an entry, a method, a constructor, an accessor, a local function, a function written as an argument and a generic function take their parameters by value, and Ref<T> written anywhere but on such a parameter (a return type, a field, a local, a module declaration) must be refused. ref(place) takes what a method that changes its object takes as that object (Rule 8.10): a let, a const whose initializer built its value (Rule 6.10), a module variable, an element of a read_write storage binding, this where it may be written, a Ref<T> parameter, or a field or an element of one of those, of exactly the type T; a value parameter, any other const, a read-only binding, a literal, a value nothing holds and a component of a vector must be refused with the edit; a column of a matrix is a place. A Ref<T> parameter the function holds is passed on as itself or as ref of it, and ref(...) written anywhere but as such an argument must be refused. The place is the one the argument names when the call is made: an index is evaluated once, before the body runs, and a write the call makes to it moves nothing. One call must not take two references whose places share a root (the local, module variable or binding they are reached through) when the callee writes either, nor a reference to a module variable or a binding the callee reads or writes by its name when either side is written; a method’s object and a variable a local function writes count as references (Rules 8.10 and 8.17). A local function must not capture a Ref<T> parameter. A reference reaches each target as its own spelling of the parameter the callee writes through: a pointer on WGSL, ptr<AS, T> with &place at the call and one copy of the function for each address space its calls use, an inout parameter on GLSL ES 3.00, and on the CPU a copy in and a store back to the same place on return.

The rule text and the parts under it are the compiler's own English, as the design document writes them.

Rationale

a function that changes its argument is what a GLSL or HLSL helper with inout does, and what an author porting one writes; the model is the one TypeShade already gives this (Rule 8.10), so no new syntax and no new IR reach the surface, and a reference is told apart from a value by the parameter’s declared type, as GLSL tells inout from in. A reference lives for one call because a target copies only there: GLSL ES 3.00 copies an inout argument in at the call and out at the return, in an order it leaves undefined, so two references to one place in one call are the one way two targets could disagree, and WGSL’s alias analysis refuses exactly those calls. A vector’s component is no place WGSL takes the address of; a matrix’s column is one, and the CPU paths read and store it back through their column helpers, as they write m[i] = v.

Derives from

change 0040 in changes/; Alias analysis and Function calls in the WGSL specification; the GLSL ES 3.00 specification, section 6.1.1.

How it is verified

Checked by a test. A test, a gate script or a CI workflow names this rule, and the traceability check fails when a file listed below stops naming it.

Where the rule says the compiler enforces it:

TS8073 REFERENCE and TS8074 REFERENCE_ALIAS in src/compiler/ts/lower/references.ts, whose comment records the alias rule measured on Tint; the store back to a field or an element in src/core/oracle.ts, src/core/cpu-codegen.ts and src/core/debug/interp.ts; pinned by src/compiler/ts/reference-parameters.test.ts, which reads each program in the compiler and the editor, and examples/reference-parameters.shade.ts through the compile gate.

The files that verify it at commit c66579bf, each at the first line that names the rule:

Explained in

The sections of the surface document that explain this rule, at commit c66579bf:

§70 Reference parameters: Ref<T> and ref(x)

Error codes that enforce it

The diagnostic codes the rule names under Enforced by, or whose registry text names the rule:

TS8073 REFERENCE: A reference parameter written or passed where this version does not take one (Rule 8.25, surface §70, proposal 0040): a Ref<T> parameter handed a value rather than ref(x); ref(...) handed something that is not a place a function may write (a value parameter, a const that may share its value, a read-only binding, a literal, a temporary, a component of a vector); ref(...) anywhere but as the argument of a Ref<T> parameter, and handed to a parameter that takes a value; Ref<T> anywhere but as a parameter of a function declared at the top of the file or of a namespace (a return, a field, a local, a method's, a local function's, an entry's, a generic function's); and a local function that captures a Ref<T> parameter.
TS8074 REFERENCE_ALIAS: Two references to one place in one call (Rule 8.25, surface §70, proposal 0040): two arguments a callee takes by reference whose places share a root (swap(ref(x), ref(x)), swap(ref(o.a), ref(o.b))), a method's object or a variable a local function writes beside a ref(...) of the same root, and a ref(...) of a module variable or binding that the callee also reads or writes directly.

Source

The rule at commit c66579bf:

docs/language-design.md:908 (the design document)
reqs/rules/RULE-0825.md (its traceability item)

Edit this page Report a problem