Luau module error handling¶
How the rtype::luau module reports failures. The goal is one rule, so a caller can tell from a
signature whether a call can fail at run time and how.
The rule¶
A failure is reported in one of two ways, depending on who caused it.
| Cause | Examples | Reported as |
|---|---|---|
| The script, the data or the environment | compile or runtime error in a script, a value of the wrong type, a value that belongs to another Lua state, the Lua stack that cannot grow, out of memory, a timeout | Result<T> holding an Error |
| A bug in the calling C++ code (API misuse) | a null lua_State*, a moved-from handle, an operation the object does not support |
an exception derived from exceptions::Base |
In short: if a correct program can still hit it, it is a Result; if only a wrong program can hit it, it
throws.
Result<T> for recoverable failures¶
- The function returns
Result<T>(Result<void>when there is no value) and is marked[[nodiscard]]. - It never throws for these failures. Build the error with
Failure{ErrorKind::..., message}; useforwardError<T>()to pass on the error of a sub-operation. - Pick the
ErrorKindthat matches the cause (kRuntime,kSyntax,kTypeMismatch,kStackOverflow,kOutOfMemory...). A stack that cannot grow iskStackOverflow, not an exception. - Document the failures in
@return("or a Failure of kindkTypeMismatchif...").
Exceptions for API misuse¶
- The exceptions live in
Exceptions.hppand all derive fromexceptions::Base:InvalidState(null state),InvalidRef(empty or moved-from handle),InvalidOperation(an operation the object does not support). - They signal a programmer error. Callers are not expected to catch them, and a program that never misuses the API never sees one.
- Document them with
@throws. A@throwsof a recoverable failure (such as a stack overflow) is a sign the function should return aResultinstead.
Constructors¶
A constructor cannot return a Result, so a type whose creation can fail has a static factory returning
Result<T> (Runtime::create, Table::create, detail::readTable). The real constructor is private and
noexcept when it can be: the factory does everything that can fail first, then hands the finished parts to it.
No instance of the type is ever half built.
When a private constructor has to run code that can throw, the factory catches at its boundary and turns the
exception into a Failure (see Runtime::create).
A plain value type whose construction cannot fail (Value, ValuePack) keeps ordinary public constructors.
The native function boundary¶
A native function bound to Luau (Function) is the one place where C++ code is called from a script. It must
not let a C++ exception unwind through Luau, so:
- a handler reports a failure by throwing an
exceptions::Base, which becomes a Lua error with its message; - anything else a handler throws is turned into a generic Lua error;
- a
Failuremet while reading the arguments or pushing the results becomes a Lua error too.
In the other direction, Function::call runs the script in protected mode and returns the script's error as a
Failure of kind kRuntime.
Adding a function¶
- Can a correct program see this failure (script, data, environment)? Return
Result<T>. - Is it a mistake in the calling code? Throw from
exceptions/, document it with@throws, and check it before touching the Lua stack, so the stack is left as it was. - Either way, leave the Lua stack as it was found when the call fails.