Documentation channel: v0.0.5 at compiler commit 2c9c7e8. The latest tagged release is v0.0.5; pages identify APIs that are new in v0.0.5.
Memory
Strut has no tracing garbage collector. Safe ownership is deterministic: T* is the ordinary reference-counted owning pointer, and the object is destroyed when the final owning pointer is released.
Safe owning pointers
User* user := new(User { id: 1, name: "Ada" });
User* second := user;
Copying a safe pointer shares ownership. A null safe pointer traps on dereference rather than becoming native undefined behaviour.
Const pointees and const bindings
Strut keeps one canonical pointer spelling. const T* makes the pointer binding const; T* const makes the pointed-to value const; const T* const applies both.
const User* fixed_owner := user;
User* const read_only := user;
const User* const fixed_read_only := user;
Nested pointers and references
Pointer layers compose normally. T** is a safe pointer to a safe T*, and deeper pointer chains continue the same way. References to pointer bindings are supported with T*&. Pointers to references are deliberately rejected.
int* value := new(7);
int** pointer := new(value);
int*** triple := new(pointer);
int*& binding := ref(value);
print(***triple);
References
T& is non-owning, non-null, and non-rebindable. T& const prevents mutation through the reference. References avoid reference-count churn when ownership is not needed.
function print_user(User& const user) -> void {
print(user.name);
}
Weak pointers
weak_ptr<T> observes an object without keeping it alive. Create it with weak(x), promote it with lock() (which returns an owning T* or null after expiry), and test it with expired(). A successfully promoted pointer keeps the object valid until it is released.
User* user := new(User { id: 1, name: "Ada" });
weak_ptr<User> weak_user := weak(user);
if (!weak_user.expired()) {
User* locked := weak_user.lock();
}
user = null; // final owner dropped
print(weak_user.expired()); // 1 (true)
Weak ownership works for ordinary structs, native handles such as http_server, and structs that contain native handles.
Unsafe raw pointers
raw_ptr<T> is the unmanaged raw-pointer type. Convert a safe pointer with ptr(owner). Raw pointers exist for FFI and specialised low-level work and are restricted to explicit unsafe regions. Both *raw and familiar raw->member access are supported.
unsafe {
raw_ptr<User> raw_user := ptr(user);
print(raw_user->name);
}
Reference cycles
Reference counting cannot automatically collect strong cycles. Use weak_ptr<T> for back-references. The compiler warns for obvious cycles it can identify statically.
A common real cycle is a server whose registered route handler captures the server itself. Capturing the server strongly inside one of its own handlers keeps the server, its routes, and the handler alive forever:
function main() -> int : NetworkError {
app := new(http_server());
app->get("/", (http_request request) => {
app->stop(); // strong capture -> reference cycle
return http_text("bye");
});
app->listen("127.0.0.1", 8080);
return 0;
}
Capture a weak reference instead and promote it only when the handler runs. This breaks the cycle and keeps shutdown leak-free:
function main() -> int : NetworkError {
app := new(http_server());
weak_handle := weak(app); // weak back-reference, does not own
app->get("/", (http_request request) => {
server := weak_handle.lock(); // promotes while the server is alive
if (server != null) {
server->stop();
}
return http_text("bye");
});
app->listen("127.0.0.1", 8080);
return 0;
}
By-value capture semantics are unchanged: a strong capture stays strong, and the compiler never silently weakens a capture.
