Class PrintInstructionTracer

java.lang.Object

com.oracle.truffle.api.bytecode.debug.PrintInstructionTracer

All Implemented Interfaces:

InstructionTracer

public final class PrintInstructionTracer
extends Object
implements InstructionTracer

An InstructionTracer implementation that prints a textual trace of executed bytecode instructions.

Each time an instruction is about to execute, this tracer formats a single line containing:

• a monotonically increasing instruction counter,
• the qualified root name of the BytecodeNode being interpreted, and
• a human readable representation of the instruction at the current bytecode index.

Output is delivered to a user-supplied Consumer<String> (for example, System.out::println) or to a PrintStream via the newBuilder(PrintStream) convenience factory.

A tracer may optionally be restricted to a subset of bytecode roots by installing a filter predicate. If a BytecodeNode does not match the filter, its instructions are skipped.

This tracer is intended for debugging and profiling during development. It runs on the language execution thread and executes on the hot path before every instruction; it should not be left enabled in production code.

Since:

25.1

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	PrintInstructionTracer.Builder	Builder for PrintInstructionTracer instances.

Nested classes/interfaces inherited from interface InstructionTracer

InstructionTracer.InstructionAccess

Method Summary

Modifier and Type	Method	Description
static PrintInstructionTracer.Builder	newBuilder(PrintStream out)	Convenience overload of newBuilder(Consumer) that writes to a PrintStream.
static PrintInstructionTracer.Builder	newBuilder(Consumer<String> out)	Creates a new PrintInstructionTracer.Builder that will emit trace lines to the given consumer.
void	onInstructionEnter(InstructionTracer.InstructionAccess access, BytecodeNode bytecode, int bytecodeIndex, Frame frame)	Called immediately before executing the instruction at bytecodeIndex of the given bytecode node.
void	reset()	Resets the internal instruction counter back to zero.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface InstructionTracer

getExclusiveBytecodeDescriptor

Method Details

onInstructionEnter

public void onInstructionEnter(InstructionTracer.InstructionAccess access,
 BytecodeNode bytecode,
 int bytecodeIndex,
 Frame frame)

Called immediately before executing the instruction at bytecodeIndex of the given bytecode node.

This implementation formats and emits a single trace line for the current instruction, unless the BytecodeNode is excluded by the active filter.

Specified by:

onInstructionEnter in interface InstructionTracer

Parameters:

access - accessor to query information about the current instruction, valid only during this call

bytecode - the BytecodeNode currently being interpreted

bytecodeIndex - the bytecode index (BCI) of the instruction to be executed

frame - the current frame for the root being interpreted

Since:

25.1

reset

public void reset()

Resets the internal instruction counter back to zero.

This only affects the counter included in the printed trace lines. It does not clear any output sink or filter configuration.

Since:

25.1

newBuilder

public static PrintInstructionTracer.Builder newBuilder(Consumer<String> out)

Creates a new PrintInstructionTracer.Builder that will emit trace lines to the given consumer.

Each generated line is already formatted. The consumer is typically a logger or System.out::println, but any Consumer is accepted.

Parameters:

out - sink for formatted trace lines

Returns:

a new builder

Since:

25.1

newBuilder

public static PrintInstructionTracer.Builder newBuilder(PrintStream out)

Convenience overload of newBuilder(Consumer) that writes to a PrintStream.

The resulting tracer will call PrintStream.println(String) for every traced instruction.

Parameters:

out - a print stream (for example System.out)

Returns:

a new builder

Since:

25.1