Make toString() side-effect-free, so stepping through the runtime does not mutate it

[lagergren]

The problem: you cannot currently debug the runtime without changing it

A debugger does not ask permission before calling toString(). IntelliJ, Eclipse and jdb render every variable in the Variables pane, every watch expression and every hover — automatically, on every step. Rendering is not something a developer opts into; it is the ambient cost of having a breakpoint.

Today, several of the runtime's toString() implementations mutate the program while rendering it. Not slowly — observably. The root is ObjectHandle.toString(), which every handle inherits:

ObjectHandle.toString():354  →  clz.getType().isImmutable()
  → TerminalTypeConstant.isImmutable()  → resolveTypedefs()
    → ensureResolvedConstant()          → m_constId = constId = resolved;

That last line is a write, performed because a debugger drew a line of text. Every handle in the frame, on every step.

It is not the only one:

rendering this	did this
DeferredArrayHandle	freeze() interned a fresh ImmutableTypeConstant on every render
xRTType.TypeHandle, xClass.ClassHandle, Proxy.ProxyHandle	augmentType() / freeze() → interning
PropertyBody	getAnnotationClass() → getImplicitlyImportedIdentity populated f_implicits and interned package/class constants; getPropertyAnnotations() forced buildAnnotationArrays()
Component.Contribution	resolveTypedefs()
TypeInfo	toString() was the full member dump — hovering a TypeInfo walked every method and property it has

Why startup is the worst place for this, and the reason for the "especially startup" in the title

Three things compound during startup, and each makes the others worse.

Nothing is cached yet, so every intern is a real intern. Later in a run most of these constants already exist and the mutation is invisible. During startup the pool is still filling, so rendering does the maximum amount of work at exactly the moment you most want to watch what is happening.

Structures are half-built, and the display path did not tolerate that. ExceptionHandle.toString() called getField(null, "text"), which allocates a DeferredCallHandle when the property is absent and throws when the field layout has not been computed. Put a breakpoint in container startup, look at the Variables pane, and you get errors where values should be — not because your program is broken, but because the renderer demanded state that does not exist yet. ObjectHandle.toString() likewise NPE'd on a composition-less handle.

TypeInfo construction is memoized, so a debugger can permanently change what the program computed. Forcing a TypeInfo to be built early — at a breakpoint, in a different order than production would have — caches that result. TypeInfo building also interns constants and invalidates stale TypeInfos (hence openRuntimeSynthesisWindow). Doing that from a debugger thread is not merely slow; it changes the artifact.

The practical effect is the one every developer knows and hates: a bug that reproduces without the debugger and not with it. When observation and mutation are the same operation, stepping through startup is not a diagnostic technique, it is a second experiment.

This is not only about debuggers

WrapperException is the Java exception the runtime throws to carry an XTC exception, and its toString() (ObjectHandle.java:690) is:

public String toString() {
    return getExceptionHandle().toString();
}

which reaches ExceptionHandle.toString() and its getField(null, "text"). So the allocating, layout-dependent path ran on every printed stack trace involving a runtime exception, not only under a debugger.

xFuture.FutureHandle.toString() had its own version: on the failure branch it called Utils.translate(e), allocating an exception handle in the owning container from the rendering thread, and it NPE'd when FutureTupleHandle.getFuture() returned null. (To be accurate: the get() there is guarded by isDone(), so it does not block — it is an allocation and a null hazard, not a hang.)

The change

One rule, stated once, on TypeInfo.toString() as the family contract: toString() is guaranteed side-effect-free and safe for a debugger to call implicitly; dump() is the explicit "give me the full thing" call.

dump() takes no argument. The old toString(boolean fRuntime) selected the runtime-optimized view — and fRuntime was the only thing that made rendering side-effecting, via ensureOptimizedMethodChain. It had zero callers anywhere in the repo. toString(boolean) is retained as a final @Deprecated delegate rather than removed, since it is a public abstract method on a public abstract class and an out-of-repo subclass could exist.

Production diff is 399 lines across 21 files — mostly a non-interning peek* variant added beside an existing method, and a render path switched onto it. Type.dump() still returns the full member dump through the Ecstasy-visible API.

Safety of the TerminalTypeConstant.getValueString() change

Worth stating up front, because it is the one edit that changes a widely-used method: the rendered string is provably identical.

• master: resolved != constId && resolved != null → return resolved (and write it back); otherwise return constId.
• branch: resolved == null → constId; otherwise resolved.

Three cases, all returning the same object: resolved == null → both constId; resolved == constId → master returns constId, branch returns resolved, which is constId; resolved != constId && != null → both return resolved. The only behavioural difference is that the display path no longer writes back to m_constId, and no longer runs the assert !constId.containsUnresolved().

Residual risk, stated honestly: anything relying on getValueString() to advance resolution would now behave differently. Resolution is not starved — 45 other call sites of ensureResolvedConstant() remain in that class — and depending on a display method to advance state would itself be the bug this PR is about.

Tests, and what they do and do not prove

DisplayPurityCensusTest enumerates every ObjectHandle subclass declaring its own toString() and requires each to be exercised or listed in NOT_EXERCISED with a reason, failing on a stale exclusion too. The enumeration walks the compiled class output — getProtectionDomain().getCodeSource(), then isAssignableFrom and getDeclaredMethod("toString"). No source text is read.

That matters: an earlier draft scanned .java source and found 48 classes. The classfile scan finds 49, because it sees anonymous classes source-scanning could only guess at — including ObjectHandle$1, the DEFAULT singleton, whose toString() was being silently attributed to the base class.

The purity assertion renders 20+ live handles and attributes any pool growth to the exact class. Three details make it real rather than decorative:

• it does not warm up first. An ensure*Constant intern is idempotent, so a handle that interns on its first render and then finds the constant present is invisible to a check that only looks at repeat renders — and the first render is the one a debugger performs;
• it renders everything a second time, to catch anything interning fresh on every call;
• a negative control interns a fresh parameterized type and asserts the pool grew, so a green run cannot mean the instrument is dead.

What this does not prove

Each of the 18 production hunks was reverted individually and the suite re-run. Nine turn something red; nine turn nothing red — PropertyBody.toString, Component.Contribution.toString, the ensureCaches() avoidance in TypeInfoReal.toString, ExceptionHandle.toString, Proxy.ProxyHandle.toString, xRTType.TypeHandle.toString, xClass.ClassHandle.toString, xFuture.FutureHandle.toString, xString.StringHandle.toString. Half of this branch is verified by reading the call chain, not by a failing test, and that list is in the census's javadoc rather than only here.

The reason is structural for the reflection handles: constructing an xRTType.TypeHandle or xClass.ClassHandle runs ensureClass/resolveClass, which interns the very type toString() would have frozen — so the novelty is consumed before you can render. That was established by reverting those files and confirming the tests stayed green, not assumed.

Purity coverage is 13 of 49 exercised, 36 excluded with reasons. The enumeration half is a true ratchet; the purity half proves the 13 a fixture can reach.

Two tests that were green for the wrong reason

Both found by the revert sweep, both fixed, and worth stating because they are the reason to trust the rest:

• an early census draft warmed up before measuring, which hid one-shot interning — it passed against the unfixed code;
• renderingAHandleNeverAsksItsCompositionForATypeConstant did not catch its own revert: the old body was m_fMutable || clz.getType().isImmutable(), so on a mutable handle the || short-circuits and getType() is never reached. A sibling caught it by accident. Fixed by freezing the handle under test.

The suite was consolidated on that evidence — 8 files/1491 lines down to 5 files/1406, merging tests whose reverts were caught by others and deleting one that was the unique catcher for nothing. No surviving assertion was loosened.

:javatools:test 455 → 470, same 42 pre-existing skips, ./gradlew build green, and an end-to-end xcc + xec run confirms Type.dump() still returns the full member list.

[ggleyzer]

Too complex and risky at the moment. My recommendation is to sit on this one unless it becomes a blocker.

[lagergren]

I seriously want to be able to attach and debug in the IDE, and this keeps getting so much in the way with mysterious "it just stopped working IDK - there's an exception somewhere due to bootstrapping/first call to toString modified state."

I can try to resubmit this as different smaller PRs, @cpurdy and @ggleyzer, but I really think the problems with complexity/debuggability are worse now than they would be with this fix.

[lagergren]

It is also very challenging to understand the constant pool at runtime (but same issue at compile time, but somewhat easier to pin down), if just stepping in the debugger in vscode has side effects. The waveform collapsed on observation, so to speak. I very much doubt that I will be the last newcomer to the XTC code base who will feel a bit impared that just stepping through the code - not necessarily hunting for a bug - but just trying to understand how it works, can break the world I was hoping to explore. _