Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions Release Notes/_index.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,11 @@
"type": "ContentText",
"body": "<p>Io uses date-based versioning. This page collects the notable changes of the last twelve months &mdash; a period in which the VM was rewritten around a stackless evaluator and re-targeted from native binaries to WebAssembly. Entries marked <em>tagged</em> correspond to release tags in the <a href=\"https://github.com/IoLanguage/io\">repository</a>; the rest are development milestones on the road between them. For the longer arc, see the <a href=\"../Timeline/index.html\">Timeline</a>.</p>"
},
{
"type": "ContentText",
"title": "Unreleased",
"body": "<p>On <code>master</code>, not yet tagged.</p><ul><li><strong>Backtraces are back</strong> &mdash; an uncaught error prints the calls that led to it, with file and line, instead of &ldquo;nothing on stack&rdquo;. An exception records its trace when it is raised: <code>Exception stackTraceLines</code> returns it as a list, and <code>pass</code> keeps the original.</li><li><strong>Build</strong> &mdash; <code>make</code> rebuilds the objects that include a changed header; a clean build is no longer needed after editing one (<a href=\"https://github.com/IoLanguage/io/pull/515\">#515</a>).</li></ul>"
},
{
"type": "ContentText",
"title": "2026.11.18 — Long-running programs stop growing",
Expand Down
4 changes: 2 additions & 2 deletions Release Notes/index.html

Large diffs are not rendered by default.

16 changes: 8 additions & 8 deletions agents/wasm/Plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,14 +24,14 @@ The goal is to **target WASM as Io's only platform**, eliminating all OS-specifi

### Recommended next

1. **VM bugs found while building the scheduler, not yet fixed.** All of them
are in the native build too. (Fixed since: syntax errors crashing the VM,
#511; the retain-stack growth in loops and coroutines, see
[../stackless/Debug_Loop_Leak.md](../stackless/Debug_Loop_Leak.md).)
- **Backtraces** say "nothing on stack" for most errors.
- **`make` doesn't track header dependencies**, and `make` alone doesn't
regenerate `IoVMInit.c`. After changing a `.h` or a core `.io` file:
`rm -rf build/obj build/obj-p2 && make regenerate && make`.
1. **VM bugs found while building the scheduler: all fixed.** Syntax errors
crashing the VM (#511); the retain-stack growth in loops and coroutines
([../stackless/Debug_Loop_Leak.md](../stackless/Debug_Loop_Leak.md), #513);
`make` not tracking header dependencies (#515); and backtraces saying
"nothing on stack". An exception now records its trace from the frame
chain when it is raised (`Exception stackTrace`, `stackTraceLines`;
`IoState_recordStackTraceOn_`). Known limit: a tail call reuses its
caller's frame, so the caller of a method's last call has no entry.
2. **The Io-side handle table is fixed at 1024 entries**
(`IO_HANDLES_MAX`, `browser/io_js_bridge.c`): Io objects JS holds, plus
Promises not yet settled. When it is full a new Promise is rejected with
Expand Down
8 changes: 8 additions & 0 deletions browser/test/vm.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,14 @@ test("a syntax error gives status 1 and the VM carries on", async () => {
assert.equal((await io.eval("list(1, 2, 3) map(x, x * x) sum")).output, "==> 14\n");
});

test("an uncaught error prints the calls that led to it", async () => {
const src = "btInner := method(r := 1 + nil; r)\nbtOuter := method(r := btInner; r)\nbtOuter";
const { status, output } = await io.eval(src);
assert.equal(status, 1);
assert.match(output, /Number \+ .* 1\n\s+Object btInner .* 2\n\s+Object btOuter .* 3\n/);
assert.doesNotMatch(output, /nothing on stack|hostEval/);
});

test("state persists between evals", async () => {
await io.eval("counter := 41");
assert.equal((await io.eval("counter + 1")).output, "==> 42\n");
Expand Down
18 changes: 18 additions & 0 deletions docs/Guide/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -1051,6 +1051,24 @@ e catch(Exception,

The first argument to catch indicates which types of exceptions will be caught. catch() returns the exception if it doesn't match and nil if it does.

An exception records where it was raised. `showStack` prints the error and the calls that led to it, innermost first, and `stackTraceLines` returns the same lines as a list:

```
Account := Object clone
Account withdraw := method(n, r := balance - n; r)
e := try(Account withdraw(10))
e showStack
```

```
Exception: Account does not respond to 'balance'
---------
Account balance bank.io 2
Account withdraw bank.io 3
```

Each line names the target's type and the message, then the file and line the message was sent from. When a method's last expression is a call, that call takes over the method's frame (a tail call), so the method itself does not appear in the trace.




Expand Down
10 changes: 8 additions & 2 deletions docs/Guide/index.html

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion docs/index.html

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions index.html

Large diffs are not rendered by default.

69 changes: 51 additions & 18 deletions libs/iovm/io/Exception.io
Original file line number Diff line number Diff line change
Expand Up @@ -323,25 +323,10 @@ Coroutine do(
if(exception, buf appendSeq("\n ", exception type, ": ", exception error, "\n"))

//writeln("backTraceString 2\n")
if(callStack size > 0) then(
traceLines := if(exception, exception stackTraceLines, list())
if(traceLines size > 0) then(
buf appendSeq(" ---------\n")

if(exception and exception ?caughtMessage,
buf appendSeq(" ", exception caughtMessage description, "\n")
)

frames := callStack

if(exception and exception originalCall,
index := frames indexOf(exception originalCall)
if(index,
frames sliceInPlace(index)
)
)

frames foreach(v,
buf appendSeq(" ", v description, "\n")
)
traceLines foreach(line, buf appendSeq(" ", line, "\n"))
buf appendSeq("\n")
) else(
buf appendSeq(" ---------\n")
Expand Down Expand Up @@ -595,6 +580,54 @@ MyErrorType := Error clone
newSlot("originalCall")
//doc Exception originalCall Returns the call object associated with the exception.

newSlot("stackTrace")
/*doc Exception stackTrace
Where the exception was raised, recorded by the VM when it is raised: a
flat List with two items per entry, innermost first, the Message being
evaluated and the type name of its target. nil if never raised. See
stackTraceLines for a readable form.
*/

stackTraceIgnoredNames := list("raiseException", "rawSignalException")
//doc Exception stackTraceIgnoredNames Names of the VM's own raising steps, left out of the top of stackTraceLines.

stackTraceLines := method(
/*doc Exception stackTraceLines
Returns the stack trace as a List of strings, innermost call first,
each "TargetType messageName file line". The VM's own raising
steps and the command line's frames are left out. A
method that was the last call in its caller replaces it (a tail
call), so such callers do not appear.
*/
lines := list()
trace := self stackTrace
if(trace isNil, return lines)
atTop := true
first := nil
i := 0
while(i < trace size,
m := trace at(i)
typeName := trace at(i + 1)
i = i + 2
if(atTop and stackTraceIgnoredNames contains(m name), continue)
atTop = false
file := m label lastPathComponent
// The host's own frames: the command line, or the browser's eval
if(file == "CLI.io" or m label == "IoState_runCLI()", break)
if(m name == "hostEval" and typeName == "Scheduler", break)
lines append((typeName .. " " .. m name) alignLeft(36) .. " " .. file .. " " .. m lineNumber)
if(first isNil, first = m)
)
// The message that failed is missing from the frames when a tail
// call replaced its frame (a forward method raising) or when the
// error came from C. originalCall and caughtMessage still have it.
failed := if(originalCall, originalCall message, caughtMessage)
if(failed and failed != first,
lines prepend(if(originalCall, originalCall description, failed description))
)
lines
)

raise := method(error, nestedException,
//doc Exception raise(error, optionalNestedException) Raise an exception with the specified error message.
coro := Scheduler currentCoroutine
Expand Down
6 changes: 5 additions & 1 deletion libs/iovm/source/IoCoroutine.c
Original file line number Diff line number Diff line change
Expand Up @@ -638,7 +638,11 @@ IO_METHOD(IoCoroutine, rawSignalException) {

IoState *state = IOSTATE;
// The exception is already set on this coroutine (by raiseException).
// Signal the eval loop to unwind frames.
// Record where it was raised, then signal the eval loop to unwind frames.
{
IoObject *e = IoCoroutine_rawException(self);
if (e && !ISNIL(e)) IoState_recordStackTraceOn_(state, e);
}
state->errorRaised = 1;
return self;
}
Expand Down
54 changes: 54 additions & 0 deletions libs/iovm/source/IoState_exceptions.c
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ bootstrap failures where no Io-visible error path exists yet.
#include "IoCoroutine.h"
#include "IoSeq.h"
#include "IoEvalFrame.h"
#include "IoList.h"
#include <stdio.h>

//#define IOSTATE_SHOW_ERRORS 1
Expand All @@ -36,6 +37,58 @@ void IoState_fatalError_(IoState *self, char *error) {
exit(-1);
}

// Longest stack trace recorded on an exception, in entries.
#define IO_STACK_TRACE_MAX 64

/*cdoc State IoState_recordStackTraceOn_(self, exception)
Records where an exception was raised, as a List in its stackTrace slot.
The eval loop unwinds the frames before anything can print them, so the
trace has to be taken here, while the frame chain is intact.

The list is flat, two items per entry, innermost first: the message being
evaluated and the type name of its target. The entries are the frame that
raised, then each frame waiting on a method or block it called. A frame
reused by a tail call has only its latest call, so tail calls leave no
entry for their caller. An exception that already has a trace keeps it,
so re-raising with pass still shows where it first came from.
*/
void IoState_recordStackTraceOn_(IoState *self, IoObject *exception) {
IoSymbol *slotName = IoState_symbolWithCString_(self, "stackTrace");
IoSymbol *typeSlot = self->typeSymbol;
IoObject *existing;
IoList *trace;
IoEvalFrame *frame = self->currentFrame;
int isTop = 1;
int count = 0;

if (!exception) return;
existing = IoObject_rawGetSlot_(exception, slotName);
if (existing && ISLIST(existing)) return;

trace = IoList_new(self);
IoObject_setSlot_to_(exception, slotName, trace);

while (frame && count < IO_STACK_TRACE_MAX) {
IoEvalFrameData *fd = FRAME_DATA(frame);
if (fd->message && (isTop || fd->state == FRAME_STATE_ACTIVATE)) {
// The target's type slot when it is a string (no new
// symbol needed), else its tag name, as IoObject_name does.
IoObject *typeName =
fd->target ? IoObject_rawGetSlot_(fd->target, typeSlot) : NULL;
if (!typeName || !ISSEQ(typeName)) {
typeName = IoState_symbolWithCString_(
self, fd->target ? IoTag_name(IoObject_tag(fd->target))
: "?");
}
IoList_rawAppend_(trace, fd->message);
IoList_rawAppend_(trace, typeName);
count++;
}
isTop = 0;
frame = fd->parent;
}
}

/*cdoc State IoState_error_(self, m, format, ...)
Raises an Io-level exception without longjmp. Formats the description
with printf-style vargs, clones the current coroutine's Exception proto,
Expand Down Expand Up @@ -113,6 +166,7 @@ void IoState_error_(IoState *self, IoMessage *m, const char *format, ...) {
IoObject_setSlot_to_(e,
IoState_symbolWithCString_(self, "coroutine"), coroutine);
IoCoroutine_rawSetException_(coroutine, e);
IoState_recordStackTraceOn_(self, e);
}
}

Expand Down
1 change: 1 addition & 0 deletions libs/iovm/source/IoState_exceptions.h
Original file line number Diff line number Diff line change
Expand Up @@ -6,5 +6,6 @@

IOVM_API void IoState_fatalError_(IoState *self, char *error);

IOVM_API void IoState_recordStackTraceOn_(IoState *self, IoObject *exception);
IOVM_API void IoState_error_(IoState *self, IoMessage *m, const char *format,
...);
87 changes: 87 additions & 0 deletions libs/iovm/tests/correctness/BacktraceTest.io
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
BacktraceTest := UnitTest clone do(
// An exception records where it was raised (Exception stackTrace), taken
// from the frame chain when it is raised. Backtraces used to be built from
// Call objects on the retain stack, which the stackless evaluator no
// longer leaves there, so nearly every error printed "nothing on stack".
//
// Each helper ends with a plain value so its call is not a tail call: a
// tail call reuses its caller's frame, and the caller then has no entry.

Thing := Object clone do(
type := "Thing"
outer := method(x, r := self inner(x); r)
inner := method(x, r := x + nil; r)
raiser := method(Exception raise("boom"); nil)
missing := method(r := 1 noSuchMethod; r)
looper := method(list(1, 2) foreach(v, if(v == 2, self inner(v))); nil)
)

// "Type name" of each trace line, without the file and line columns
calls := method(e,
e stackTraceLines map(line, line exSlice(0, 36) asMutable strip)
)

testErrorFromCShowsCallChain := method(
e := try(Thing outer(1))
assertEquals(list("Number +", "Thing inner", "Thing outer"), calls(e) slice(0, 3))
)

testRaiseShowsCallChain := method(
e := try(Thing raiser)
assertEquals(list("Exception raise", "Thing raiser"), calls(e) slice(0, 2))
)

testMissingMethodShowsFailedMessage := method(
e := try(Thing missing)
assertEquals(list("Number noSuchMethod", "Thing missing"), calls(e) slice(0, 2))
)

testCallsInsideLoopsAndBranches := method(
e := try(Thing looper)
assertEquals(list("Number +", "Thing inner", "Thing looper"), calls(e) slice(0, 3))
)

testLinesNameFileAndLine := method(
e := try(Thing outer(1))
// each line gives where that message was sent from
assertTrue(e stackTraceLines at(0) containsSeq("BacktraceTest.io 13"))
assertTrue(e stackTraceLines at(1) containsSeq("BacktraceTest.io 12"))
)

testPassKeepsTheOriginalTrace := method(
e := try(Thing outer(1))
e2 := try(e pass)
assertTrue(e == e2)
assertEquals(list("Number +", "Thing inner", "Thing outer"), calls(e2) slice(0, 3))
)

testBackTraceStringIncludesTheTrace := method(
e := try(Thing outer(1))
s := e coroutine backTraceString
assertTrue(s containsSeq("Thing inner"))
assertFalse(s containsSeq("nothing on stack"))
)

testCoroutineErrorHasItsOwnTrace := method(
o := Object clone
o caught := nil
o handleActorException := method(e, self caught = e)
o thing := Thing
o work := method(r := thing outer(1); r)
o @@work
5 repeat(yield)
assertTrue(o caught != nil)
assertEquals(list("Number +", "Thing inner", "Thing outer"), calls(o caught) slice(0, 3))
)

testNeverRaisedHasNoTrace := method(
assertEquals(list(), Exception clone stackTraceLines)
)

testDeepRecursionIsCapped := method(
down := method(n, r := if(n == 0, 1 + nil, down(n - 1)); r)
e := try(down(500))
assertTrue(e stackTrace size <= 128)
assertEquals("Number +", calls(e) first)
)
)
27 changes: 26 additions & 1 deletion llms-full.txt
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Io — Full Documentation

Site build: Io · 2026-11-16 · 6db971fd
Site build: Io · 2026-11-17 · 257b352a

Io is a dynamic, prototype-based language built on a few simple ideas taken from Smalltalk (all values are objects), Self (prototypes, not classes), NewtonScript (differential inheritance), Act1 (actors and futures for concurrency), Lisp (code is a runtime-inspectable message tree), and Lua (small and embeddable).

Expand Down Expand Up @@ -3020,6 +3020,24 @@ e catch(Exception,

The first argument to catch indicates which types of exceptions will be caught. catch() returns the exception if it doesn't match and nil if it does.

An exception records where it was raised. `showStack` prints the error and the calls that led to it, innermost first, and `stackTraceLines` returns the same lines as a list:

```
Account := Object clone
Account withdraw := method(n, r := balance - n; r)
e := try(Account withdraw(10))
e showStack
```

```
Exception: Account does not respond to 'balance'
---------
Account balance bank.io 2
Account withdraw bank.io 3
```

Each line names the target's type and the message, then the file and line the message was sent from. When a method's last expression is a call, that call takes over the method's frame (a tail call), so the method itself does not appear in the trace.




Expand Down Expand Up @@ -7044,6 +7062,13 @@ Notable changes in Io over the past twelve months.

Io uses date-based versioning. This page collects the notable changes of the last twelve months — a period in which the VM was rewritten around a stackless evaluator and re-targeted from native binaries to WebAssembly. Entries marked *tagged* correspond to release tags in the [repository](https://github.com/IoLanguage/io); the rest are development milestones on the road between them. For the longer arc, see the [Timeline](../Timeline/index.html).

## Unreleased

On `master`, not yet tagged.

- **Backtraces are back** — an uncaught error prints the calls that led to it, with file and line, instead of “nothing on stack”. An exception records its trace when it is raised: `Exception stackTraceLines` returns it as a list, and `pass` keeps the original.
- **Build** — `make` rebuilds the objects that include a changed header; a clean build is no longer needed after editing one ([#515](https://github.com/IoLanguage/io/pull/515)).

## 2026.11.18 — Long-running programs stop growing

*Tagged `2026.11.18`.* A memory fix for programs that never return to the top level: servers, actors, and long-lived coroutines.
Expand Down
2 changes: 1 addition & 1 deletion llms.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

> A small, prototype-based programming language — now targeting WASM/WASI.

Site build: Io · 2026-11-16 · 6db971fd
Site build: Io · 2026-11-17 · 257b352a

## Documentation

Expand Down
Loading