Scope modes

Read Copies, moves, and references first. Scope modes explicitly enable facilities in a function or block. explc and opt serve different purposes.

Choose the annotation and its location

Annotation	Location	Purpose
#![explc]	Immediately before a function	Use explicit references in that function.
#scope[explc] { ... }	A block inside a function	Use explicit references within that block.
#scope[opt] { ... }	A block inside a function	Mark code for the selected optimization option.

let mut allows a variable to change. explc allows explicit references. Neither replaces the other.

Change an original value inside a block

Save this as scope_modes.xen. append_shared declares a reference parameter, so it has #![explc]. In main, only the part that creates and passes the reference is enclosed in #scope[explc].

scope_modes.xen

#![explc]
fn append_shared(values: &mut Vec<Int>) {
    values.push(3);
}
fn main() {
    let mut values = [1, 2];
    #scope[explc] {
        append_shared(&mut values);
    }
    println(values);
    let mut total = 0;
    #scope[opt] {
        for value in 1..5 {
            total = total + value;
        }
    }
    println(total);
}

xen check scope_modes.xen
xen run scope_modes.xen

scope_modes.stdout

[1, 2, 3]
10

The caller’s vector now contains 3. Unlike passing a value and changing an independent copy, &mut values refers to the caller’s original. The sum calculation is marked separately with opt.

When explicit references are used throughout a function, you can also put #![explc] immediately before main. Choose the function or block boundary to match where references are needed.

A callee’s annotation does not annotate its caller

This program deliberately fails. Run xen check scope_error.xen:

scope_error.xen

#![explc]
fn append_shared(values: &mut Vec<Int>) { values.push(3); }
fn main() {
    let mut values = [1, 2];
    append_shared(&mut values);
}

scope_error.stderr

passing references requires #![explc]

Annotating append_shared does not enable &mut values inside main. Enclose the call in #scope[explc], as in the working program, or annotate main with #![explc]. Check both the function declaring reference parameters and the caller creating references.

explc preserves borrowing restrictions. You cannot change or move an original while shared references remain in use, or access it through another path while a mutable reference remains in use. Borrowing a temporary directly, returning references, and storing references in struct fields are unavailable.

Run opt blocks with different options

Run the same program with optimization disabled and enabled:

xen run scope_modes.xen --opt=off
xen run scope_modes.xen --opt=basic
xen run scope_modes.xen --opt=basic --opt-report
xen build scope_modes.xen --opt=basic --opt-cache=.xen-opt-cache -o scope-modes

The first two commands produce the standard output shown above. --opt-report writes application information separately to stderr. Do not use report line counts or internal identifiers as part of your program’s output contract.

build, run, and test default to --opt=basic. Optimization applies to code marked with #scope[opt]; unmarked code is unaffected. --opt-report and --opt-cache require basic and are unavailable for check. Checking does not execute the program or measure performance.

This small example teaches annotation placement and the execution workflow. Marking a block does not by itself establish a speed improvement.

bb and this release’s documentation boundary

bb is a low-level facility for raw memory and operating-system calls. The user documentation included in this release does not define its detailed syntax, APIs, or guarantees, so this chapter does not supply an executable usage recipe. Use the standard library for files, I/O, and paths.

Look up rules in the scope modes reference and options in the CLI reference.

Try it

Remove the #scope[explc] block while retaining the call, then check the program. Fix it by annotating main instead. Explain why changing optimization options cannot fix a reference-use error.