Interface InstructionTracer

All Known Implementing Classes:

HistogramInstructionTracer, PrintInstructionTracer

public interface InstructionTracer

A low-overhead callback interface to observe instruction execution in Bytecode DSL interpreters. A tracer receives a notification immediately before the interpreter executes the instruction at a given bytecode index. The callback runs on the language thread that executes the bytecode, on the hot path, and may be invoked at very high frequency.

Tracers for a BytecodeRootNodes instance may be attached via the BytecodeRootNodes.addInstructionTracer(InstructionTracer) method. Attaching tracers to all root node instances of a BytecodeDescriptor is possible using BytecodeDescriptor.addInstructionTracer(TruffleLanguage, InstructionTracer). Note that attaching a tracer requires all affected root nodes to be invalidated and is therefore a very expensive operation. It also potentially requires all root nodes to be re-parsed. As a trade-off, not using an instruction tracer is basically free, except for reserving instructions in the bytecode interpreter, similar to how the @Instrumentation annotation is implemented.

Typical uses include printing a trace, maintaining per-opcode counters, or driving custom debugging or testing utilities. For convenience, the com.oracle.truffle.api.bytecode.debug package provides reference implementations such as a line printer and a histogram tracer.

Performance considerations.

• Instruction tracers are subject to partial evaluation, with the tracer reference being a partial-evaluation constant, allowing the tracer to be optimized.
• Prefer InstructionTracer.InstructionAccess.getTracedOperationCode(BytecodeNode, int) for fast-path logic. In generated interpreters this typically avoids allocating an Instruction object.
• InstructionTracer.InstructionAccess.getTracedInstruction(BytecodeNode, int) materializes an Instruction object and is therefore more expensive. Use it only when metadata is actually needed, for example to print the instruction name or retrieve source sections.

Since:

25.1

See Also:

• BytecodeRootNodes.addInstructionTracer(InstructionTracer)
• BytecodeDescriptor.addInstructionTracer(TruffleLanguage, InstructionTracer)

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	InstructionTracer.InstructionAccess	Accessor for properties of the instruction about to execute.

Method Summary

Modifier and Type	Method	Description
default BytecodeDescriptor<?,?,?>	getExclusiveBytecodeDescriptor()	Returns the BytecodeDescriptor that this tracer is exclusive for, or null if this instruction tracer may be used with any bytecode descriptor.
void	onInstructionEnter(InstructionTracer.InstructionAccess access, BytecodeNode bytecode, int bytecodeIndex, Frame frame)	Called immediately before executing the instruction at bytecodeIndex of the given bytecode node.

Method Details

onInstructionEnter

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

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

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

getExclusiveBytecodeDescriptor

default BytecodeDescriptor<?,?,?> getExclusiveBytecodeDescriptor()

Returns the BytecodeDescriptor that this tracer is exclusive for, or null if this instruction tracer may be used with any bytecode descriptor.

Since:

25.1