Errors
Schedule deferred cleanup, recover panics, and forward failures to callers.
Panic diagnostics#
panic accepts a string expression and interrupts normal execution. Ocean then unwinds the call stack: it runs the relevant deferred calls while passing the panic outward through callers. Deferred calls run before the panic propagates to callers. If no deferred function recovers it, execution stops with status 1 and a report containing a source excerpt and call trace.
return panic skips the current function’s deferred calls and attributes the failure to its immediate caller, or to the statement itself when used in main. A caller that does not forward the panic runs its deferred calls and can recover it. For a routine failure the caller is expected to handle, return a status or Result<T> instead of interrupting execution with a panic.
func requirePositive(value int) int {
if (value <= 0) return panic "expected a positive number";
return value;
}
A call such as requirePositive(-1) fails at that call site with the message expected a positive number. Source excerpts are embedded in the executable, so the runtime report does not depend on finding the original file on disk.
Forward panic diagnostics#
Use forward panic <statement> in a wrapper to report a returned panic at the wrapper’s caller. The statement can be a single statement or a block. A single statement keeps its usual semicolon; a block needs no trailing semicolon.
Forwarding applies only to a failure created by return panic "message";. The return in that form is part of Ocean’s panic-reporting behavior, not a normal returned error value. An ordinary panic "message"; always reports where it occurs, even inside a forwarding block. Forwarding changes the diagnostic location; it does not catch a panic or allow execution to continue. Successful calls behave normally, and the original message and full call trace are preserved.
func leaf() int {
return panic "invalid input";
}
func wrapper() int {
forward panic return leaf();
}
func main() int {
return wrapper(); // Diagnostic points to this call.
}
For several calls, write forward panic { first(); second(); }. Forwarding applies to calls in the annotated statement, including conditions and arguments. Consecutive forwarding callers move the location outward until a caller does not forward or the outermost call site is reached. Nested forwarding blocks in the same function do not skip extra frames. A wrapped declaration, such as forward panic x := leaf();, remains visible in its enclosing scope.
For example, forward panic { panic "hi"; } reports at panic "hi"; it is never forwarded. Use return panic "hi"; when creating a failure that should be attributed to the caller and may be forwarded by its wrappers.
Forwarding a returned panic skips the wrapper’s deferred calls. The first caller that does not forward runs its deferred calls and can recover the panic. An ordinary panic from a called function, or a direct panic inside a forwarding block, runs local deferred calls.
Deferred calls and recovery#
defer cleanup(arg); evaluates the receiver and arguments immediately and runs the call when the enclosing function exits. A defer inside a nested block still waits until the enclosing function exits; it does not run merely because that block ends. If several calls are deferred, the most recently registered call runs first. Calls registered in loops follow the same rule. Return expressions are evaluated before deferred calls; deferred calls can change named results through pointers. Ocean's usual value-copy rules apply to captured arguments; pointers retain their aliasing behavior.
recover() returns any. Called directly in a deferred Ocean function during panic unwinding, it returns the panic message as a boxed string and stops the panic. After recovery, the panicking function finishes any remaining deferred calls and returns to its caller. It does not resume at the statement after panic. Its named result variables supply the returned values; unnamed results receive their types’ defaults. Outside that context, including an indirect helper call or a normally returning function's deferred call, recover() returns null. A second call after recovery also returns null; defer recover(); does not recover a panic.
An ordinary panic runs the function's defers, then its callers' defers as it propagates. return panic skips the originating function's defers. A caller that forwards that returned panic with forward panic also skips its defers; the first caller that does not forward runs its defers and can recover. Further propagation runs callers' defers normally. A direct panic inside forward panic { panic "hi"; } runs local defers, as does an ordinary panic from a called function. An unrecovered panic prints its diagnostic and exits with status 1. A new panic in a deferred call starts unwinding from that call.
func work() {
defer func() {
message := recover();
if (message != null) {
// Inspect message.(string).
}
}();
panic "operation failed";
}
The function literal is registered before work panics. During unwinding, it calls recover() directly in its own body and receives the boxed message "operation failed". After that deferred call and any remaining deferred calls finish, work returns normally to its caller.