Out Parameters

Design Decision

GX does not allow returning pointers from GX functions (extern functions are exempt). Instead, GX uses out parameters for mutation and multi-return patterns. All pointer parameters without out are read-only (const in generated C).

Rules

DeclarationMeaningC output
p: *TRead-only pointer (borrowing)const T* p
out p: *TMutable pointer (writing)T* p
out x: TOut parameter (multi-return)T* x (write with *x = ..., pass &x at the call site)
a: array<T>, m: map<K,V>Read-only containerconst ec_array a (shares the caller’s buffer)
out a: array<T>, out m: map<K,V>, out c: chan<T>The caller’s container (pass &a; use it as a)ec_array* a
self in exMutable (special case)T* self

Why No Pointer Returns?

In real systems code, the caller allocates and the caller cleans up. Functions receive pointers and either read or write through them. This makes ownership explicit and eliminates “who frees this?” bugs.

// Caller allocates, caller owns, caller cleans up
fn main() {
    var arena: Arena
    arena.init(4096)
    defer arena.destroy()

    var player:*Player = arena.alloc(Player)
    init_player(player, "Alice")    // out p: *Player — fills it in
    update_player(player, 0.016)    // out p: *Player — modifies it
    render_player(player)           // p: *Player — reads it (const)
}

Exemptions

  • extern fn may return pointers (C interop: malloc, fopen, etc.)
  • Built-in allocator methods (.alloc(T)) return *T
  • self in extension methods is always mutable

Multiple Return Values

Use out parameters instead of returning structs or tuples:

fn parse_int:bool(input: str, out value: i32, out consumed: i32) {
    *value = 42          // an out parameter is a pointer: store through it
    *consumed = 2
    return true
}

var v: i32
var n: i32
if (parse_int("42abc", &v, &n)) {    // pass the address
    print("Got {v}\n")
}

Inside the function an out x: T parameter is a pointer to the caller’s variable: write *x = ... to store and *x to read. At the call site pass the address with &.

An out p: *T parameter takes a pointer: a *T you already hold (for example from arena.alloc(T)) is passed as is, a local struct as &local. Inside the function its fields are reached with plain p.field.

Errors the compiler reports

Only the constant 0 and null convert to a pointer. Before v0.8.7 any integer expression did, so assigning to an out parameter without *, or passing a value without &, compiled and silently did the wrong thing. Both are now compile errors that say what to write:

error: 'value' is an 'out' parameter (a pointer). Write '*value = ...' to store the value
error: Argument 2: expected *i32 for an 'out' parameter, got i32. Pass '&v'

An out x: T parameter does not accept the constant 0 either: x = 0 inside the function and f(0) at the call site are the same two errors, since neither stores a value.

The read-only rule also covers containers, both a container inside a struct that is reached through a read-only pointer and a container parameter that is not out (see Containers as Parameters). A modifying method (push, set, clear, remove, sort, free, …), a write to an element and ++ / -- on one are errors; mark the parameter out:

error: Cannot call 'push' on a read-only parameter. Add 'out' to the parameter to allow modification.
error: Cannot write to read-only parameter 'g'. Add 'out' to the parameter to allow modification.

Something read-only cannot be made writable by passing it on. A read-only parameter, or the address of a place inside it, is not accepted by an out parameter:

fn bump(out v: i32) { *v = *v + 1 }
fn first(p: *Counter) { bump(&p.hits) }      // error
error: Argument 1: read-only parameter 'p' cannot be passed to an 'out' parameter. Add 'out' to it to allow modification.

Future Consideration

context<T> — a fat pointer carrying allocator info ({ptr: *T, alloc: *void}) was considered for cases where allocation happens inside called functions. Deferred because the common pattern (allocate at top, pass down) doesn’t need it.