On this page
Scripting
Errors, limits and objects
Errors and limits
error("message") and failed asserts raise errors, as does any mistake at run time
(a type mismatch, an overflow, an unknown global and so on). An error that isn't caught
ends the run, and the run's error shows the line it happened on and the calls that led
there.
pcall. pcall(f, …) calls f and returns true followed by all of f's
results, or false and the error: the value passed to error (any value), or the
message of a run-time error. xpcall(f, handler) passes the error to handler first.
Error messages don't start with a file and line: pcall gives exactly the text passed to
error, and the position is reported with the run's error instead. One rule keeps both
safe:
- Can be caught:
error()andassert, and mistakes in values:typeMismatch,unknownGlobal,notCallable,invalidArgument,arithmeticOverflow,moduleNotFound,moduleErrorand similar. - Can't be caught: running out of a limit, or CoCoCo stopping the run. These pass
straight through
pcall:instructionLimitExceeded,callDepthExceeded,memoryLimitExceeded,tableLimitExceeded,stringLimitExceeded,timeoutExceeded,logLimitExceeded,hostResourceLimitExceededandcancelledByHost. A script can never outlast its limits by catching them.
local ok, err = pcall(function() error({ code = 42 }) end)
ok --> false
type(err) == "table" and err.code --> 42
local _, plain = pcall(function() error("boom") end)
plain --> "boom"
local fine, why = xpcall(function() error("boom", 0) end, function(e) return "handled " .. e end)
fine --> false
why --> "handled boom"Every run has limits (Limits lists them for each kind of script): on
instructions, call depth, memory, entries per table, bytes per string, output, modules
loaded and objects (Objects from CoCoCo). Running
out of one ends the run with an error naming it (instructionLimitExceeded,
callDepthExceeded and so on) at a predictable point: the same script with the same
input stops at the same place every time, on every platform. Write scripts that do a
bounded amount of work: a loop over a large amount of data is stopped, not slowed down.
Objects from CoCoCo
CoCoCo can give you objects: a function creates one, and you call its methods with
:. Behind the object is something CoCoCo keeps for you, such as a stored template or a
device connection.
local invoice = ctx.template.get("invoice") -- CoCoCo's function creates the object
invoice:name() --> "invoice"
local ok, text = invoice:render({ number = "1042" })
text --> "Invoice 1042"What an object is, precisely:
type(obj) == "table". The table is frozen (writing to it is an error) and holds an entry called__handle, a small sequence number, plus any fields CoCoCo chooses to show; that is allpairs,inspectand returned values ever see. There is no identity or address, ever: the same script produces the same numbers on every run.- The real object stays with CoCoCo, and you reach it only through its methods. Binary data works the same way: it reaches your script as objects, never as raw bytes.
- An object lasts for one run. Objects from an earlier run mean nothing, and CoCoCo releases them when the run ends, whether it succeeded or failed.
- Methods can take callbacks, and a callback can call methods on the same object while the outer method is still running. This is allowed, and limited like any nesting (the call-depth and other limits in Errors and limits all apply inside).
- Errors are ordinary. A made-up or out-of-date object, an object of the wrong kind,
or a bad argument is an
invalidArgumenterror you can catch. Creating too many objects runs out of a limit, which can't be caught. - The checker knows objects' types: each kind of object has a type name (for example
local d: Device), unknown methods and wrong arguments are reported, and a method that chains returns the same type again. - A method can return a different type for a name you pass it, so
client:getAction("refund")andclient:getAction("charge")may give different shapes. The checker uses this only when the name is written as a string literal; with the name in a variable, you get the method's general type. - A method that reads a device, the database or the network can give different results
on different runs, as any
ctxfunction can.
local invoice = ctx.template.get("invoice")
invoice:rendr({}) -- reported: no such methodFunctions that wait on the outside world
Many ctx functions do real work outside your script: reading the database, calling a
device or another service. To your script they look like any other call, and each one
returns a pair, (ok, res):
local ok, record = ctx.store.get("sync-state") -- waits while CoCoCo reads the record
ok --> true
if ok and type(record) == "table" then
record.data.cursor --> 42
end
local found, err = ctx.store.get("other")
found --> false
err --> "store unavailable"While CoCoCo works, your run pauses, then carries on exactly where it left off.
There is no await keyword and no callback. Things to know:
- Always
(ok, res). On successokistrueandresis the value; on a failure you can recover from,okisfalseandresis the error. If you take only one value (local ok = ctx.store.get(...)), you get just thetrueorfalse. - Each call has its own time limit. If a call takes too long, it is a
hostCallTimeouterror that you can catch withpcalland recover from. Time spent waiting does not usually count towards your script's own time limit. - The reference shows which functions wait: they return
ok, result(The ctx reference). From your side they just work when you call them; there's nothing to switch on.