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.