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
| Declaration | Meaning | C output |
|---|---|---|
p: *T | Read-only pointer (borrowing) | const T* p |
out p: *T | Mutable pointer (writing) | T* p |
out x: T | Out parameter (multi-return) | T* x (write with *x = ..., pass &x at the call site) |
a: array<T>, m: map<K,V> | Read-only container | const 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 ex | Mutable (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 fnmay return pointers (C interop: malloc, fopen, etc.)- Built-in allocator methods (
.alloc(T)) return*T selfin 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.