Lua Academy · Lesson

Resource Limits and Instrumentation

Use debug.sethook to count instructions and enforce CPU budgets.

Resource Limits and Instrumentation is a free Lua Academy lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Lua Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why Resource Limits?

Untrusted code can cause DoS by running forever (CPU), allocating huge amounts of memory, or generating excessive output. Resource limits protect the host.

CPU Limit via debug.sethook

Count executed instructions and abort when the limit is exceeded.

local function withCPULimit(fn, maxOps)
  local ops = 0
  debug.sethook(function()
    ops = ops + 1
    if ops > maxOps then error("CPU limit exceeded", 2) end
  end, "", 50)  -- check every 50 instructions
  local ok, result = pcall(fn)
  debug.sethook()
  return ok, result
end

Granularity of Counting

The third argument to sethook (count) controls how often the hook fires. Smaller values = more accurate but more overhead. 50-500 is a common range.

Memory Limit via collectgarbage

Check memory usage inside the hook and abort if it exceeds a threshold.

local MEM_LIMIT_KB = 1024  -- 1 MB
debug.sethook(function()
  if collectgarbage("count") > MEM_LIMIT_KB then
    error("Memory limit exceeded")
  end
end, "", 200)

Wall Clock Limit

Combine with os.clock() to limit wall time rather than (or in addition to) instruction count.

local deadline = os.clock() + 0.5  -- 500ms
debug.sethook(function()
  if os.clock() > deadline then
    error("Time limit exceeded")
  end
end, "", 100)

Output Limit

Wrap the sandbox's print function to count bytes written and refuse further output after a limit.

local totalOutput = 0
local OUTPUT_LIMIT = 10240  -- 10 KB
env.print = function(...)
  local s = table.concat({...}, "\t") .. "\n"
  totalOutput = totalOutput + #s
  if totalOutput > OUTPUT_LIMIT then
    error("Output limit exceeded")
  end
  output[#output+1] = s
end

Instrumentation for Profiling

Use the "call" and "return" hook events to build an instrumented call graph of sandboxed code.

local callGraph = {}
debug.sethook(function(event)
  local info = debug.getinfo(2, "Sn")
  local name = info.name or info.short_src
  if event == "call" then callGraph[name] = (callGraph[name] or 0) + 1 end
end, "c")

Coroutine Hooks

debug.sethook limits apply per-thread. Set hooks on each coroutine individually if sandboxed code spawns coroutines.

Reporting Resource Usage

After sandbox execution, report: instructions executed, memory used, output length, time elapsed. Useful for abuse detection and quota enforcement.

Nested Sandboxes

If a sandboxed plugin can itself create sub-sandboxes, ensure that the parent sandbox's resource limits are inherited or tightened for the child.

Production Tooling

Tools: luasandbox (LuaJIT), Lua Docker containers with seccomp, custom allocators that hard-limit memory. Combine with OS-level cgroups for strong guarantees.

Resource Limits Question

How does debug.sethook enforce a CPU limit?

Recap: Resource Limits and Instrumentation

Use debug.sethook to enforce CPU limits (instruction count), memory limits (collectgarbage check), and time limits (os.clock). Wrap print to limit output. Report usage after execution for monitoring and quota enforcement.

Frequently asked questions

Is the “Resource Limits and Instrumentation” lesson free?

Yes — the full text of “Resource Limits and Instrumentation” is free to read here on the web, and the Lua Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Lua Academy course, upgrade to CoddyKit PRO.

What will I learn in “Resource Limits and Instrumentation”?

Use debug.sethook to count instructions and enforce CPU budgets. You practise Lua Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Lua Academy?

No prior experience is required. Lua Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Resource Limits and Instrumentation” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Lua Academy lesson?

Yes. Every Lua Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Lua Academy