Docs/Language guide

Memory & pointers

Automatic cleanup for owned values, explicit lifetimes for heap pointers.

Owned values clean up at scope exit#

Strings, dynamic arrays, and maps own the memory used for their contents. Ordinary locals, parameters, results, nested owned fields, and temporaries release storage as their scopes end, including early returns and loop exits. This cleanup is emitted into the generated LLVM control flow; there is no garbage collector or reference counting.

Ownership describes which value is responsible for releasing an allocation. Ordinary string, dynamic-array, and map values have that responsibility for their contents. Assignment and parameter passing make independent copies, including owned values nested inside collections or structs. A copied string therefore does not depend on the lifetime of the source variable.

Scope cleanup is part of generated control flow. It runs when the scope is left through an ordinary end, an early return, or a loop exit. Returning an owned value copies it before the function’s local cleanup, so the returned result remains valid.

Ocean
func example() {
    items := int[]{1, 2, 3};
    text := "Ocean";
    // Owned storage is released when this scope ends.
}

No explicit free is needed for the two locals in example. This automatic cleanup covers their owned allocations, not arbitrary heap objects reached through pointer fields. Pointer ownership follows a different rule described below.

Explicit heap allocations#

new(T) allocates zeroed heap memory, initializes the value to zero(T), and returns *T. Pointer variables are non-owning: scope exit does not release their pointees. Call free(pointer) when the allocation is no longer needed.

Use new(T) when an object needs a heap allocation whose lifetime you will manage explicitly. The returned pointer identifies that allocation; copying the pointer does not create a second object and does not create a second owner. Keep track of which part of your program is responsible for freeing it.

free(pointer) releases the allocation created by new(T), along with owned strings, arrays, and maps stored inside the allocated value. It does not recursively follow pointer fields. This prevents the compiler from guessing whether another pointer target is shared, but means that linked allocations need their own cleanup plan.

Ocean
pointer := new(int);
*pointer = 42;
free(pointer);

The allocation starts with an integer value of zero, is updated to 42, and is then released. After free(pointer), neither that pointer nor another copy of its address should be dereferenced. Simply leaving the pointer variable’s scope would not release the allocation.

Addresses and sharing#

&value takes an address; *pointer accesses its pointee. Pointer copies share the same object. Passing an array by value instead makes an independent deep copy. free(value) can release a string or dynamic array’s owned storage before scope exit; the compiler then avoids freeing that storage a second time. Re-create the collection before using it again. This is separate from free(pointer), which releases an explicitly allocated pointee.

Taking an address is a way to borrow access to an existing object without making another object. The borrowed pointer is valid only while the original storage is valid. A pointer to a local variable must not be retained for use after that variable’s lifetime ends.

In a signature, *int means a pointer to an integer. In an expression, *value dereferences a pointer. These related uses of the asterisk are distinguished by context. A pointer parameter lets a function deliberately modify its caller’s storage instead of only a copied argument.

Ocean
func reset(value *int) {
    *value = 0;
}

// Inside a function:
count := 7;
reset(&count);

The call supplies the address of count, so the assignment in reset changes count itself to zero. There is no heap allocation here and no call to free: the variable’s ordinary lexical lifetime owns its storage.

Null is explicit#

Ocean’s null supports pointers, interfaces, and Optional<T>. For pointers it uses a reserved marker. It differs from the zero address stored in a default-initialized Ocean pointer or returned as a null pointer by a C API. Always initialize an optional link explicitly to null. Dereferencing explicit null traps.

This is an important Ocean-specific distinction. An uninitialized pointer receives a zero-address default, and zero(*T) constructs that same default. Explicit null is a separate reserved marker used for explicit pointer absence. Testing for one does not test for the other.

Choose and initialize the representation your code expects. For linked structures whose terminator is checked with == null, write null into every terminating link explicitly. At a C boundary, an address returned as a C null pointer is a zero address instead, so compare it against zero(*T) for the appropriate pointer type, such as zero(*void) for a C void* result.

Ocean
struct Node {
    value int;
    next *Node;
}

// Inside a function:
next: *Node = null;
if (next == null) {
    // No next node.
}

The explicit initializer makes the condition true. Omitting = null would produce a different default value. Neither explicit null nor a zero-address pointer refers to a valid object that can be dereferenced.

Storage layout#

sizeof(Type) returns storage size including alignment and padding. sizeof(value) inspects the type without evaluating the expression. Avoid relying on the internal layout of dynamic arrays or parameterized struct array fields at a C boundary. For arrays and strings, pass their .data buffer and a count instead. Maps have no .data view and should be converted to a representation required by the native API before crossing that boundary.

The size of a type includes any padding and alignment required by its target layout. sizeof(value) uses the type of the expression in parentheses without evaluating that expression; an increment or call written inside it does not run. The result is a storage measurement, not a count of collection elements.

For collections, use len when you mean the number of elements. A sized array includes its size header in its storage layout, while a dynamic array has a header and separately allocated payload. The compiler’s internal representation is not automatically a C-compatible structure definition.

When passing data to C, prefer an explicitly declared buffer pointer and count. In particular, dynamic-array headers and parameterized struct array fields have implementation-specific lowering that should not be used as an assumed native ABI.

Captured variable lifetime#

Function literals share captured variables with their lexical surroundings and sibling closures. A returned closure keeps its captures available after the creating call returns. Copying a function value shares its environment.

The current runtime retains captured cells and closure environments until process exit, then releases their owned contents and backing storage. Programs that repeatedly create escaping closures can therefore retain memory until shutdown. Raw pointer and buffer captures retain their usual borrowing rules; a captured pointer does not extend its pointee’s lifetime.

Ocean
func counter(start int) func() int {
    return func() int {
        start++;
        return start;
    };
}

counter(3) returns a function that keeps access to the start variable from that call. Calling the returned function twice produces 4 and 5. Copying that function value shares the same start; calling counter(3) a second time creates a separate counter.