Package com.oracle.truffle.api.instrumentation

Class EventContext

java.lang.Object
com.oracle.truffle.api.instrumentation.EventContext
public final class EventContext extends Object
Represents the context of an execution event. Instances of EventContext should be neither stored, cached nor hashed. One exception is when they are stored in ExecutionEventNode implementations. The equality and hashing behavior is undefined.
Since:
0.12
See Also:

  • Method Details

    • hasTag

      public boolean hasTag(Class<? extends Tag> tag)
      Returns true if the underlying instrumented AST is tagged with a particular tag. The return value of hasTag(Class) always returns the same value for a particular tag and EventContext. The method may be used on compiled code paths.
      Parameters:
      tag - the tag to check to check, must not be null.
      Since:
      0.33

    • getNodeObject

      public Object getNodeObject()
      Returns a language provided object that represents the instrumented node properties. The returned is always a valid interop object. The returned object is never null and always returns true for the HAS_KEYS message. Multiple calls to getNodeObject() return the same node object instance.
      Since:
      0.33
      See Also:

    • getInstrumentedSourceSection

      public SourceSection getInstrumentedSourceSection()
      Returns the SourceSection that is being instrumented. The returned source section is final for each EventContext instance. The returned source section may be null if the node does not provide sources section.

      Performance note: this is method may be invoked in compiled code and is guaranteed to always return a compilation constant .

      Since:
      0.12

    • getInstrumentedNode

      public Node getInstrumentedNode()
      Accessor to the instrumented node at which the event occurred. The returned AST must not be mutated by the user.

      Performance note: this is method may be invoked in compiled code and is guaranteed to always return a compilation constant .

      Since:
      0.12

    • isLanguageContextInitialized

      public boolean isLanguageContextInitialized()
      Test if language context of the source of the event is initialized.
      Since:
      0.26

    • lookupExecutionEventNode

      public ExecutionEventNode lookupExecutionEventNode(EventBinding<? extends ExecutionEventNodeFactory> binding)
      Returns the execution event node that was inserted at this location given an event binding. This is useful to disambiguate multiple bindings from each other when installed at the same source location.
      Parameters:
      binding - the binding to lookup
      Since:
      0.17

    • lookupExecutionEventNodes

      public Iterator<ExecutionEventNode> lookupExecutionEventNodes(Collection<EventBinding<? extends ExecutionEventNodeFactory>> bindings)
      Returns all execution event nodes in the insertion order at this location, whose event bindings are contained in the given collection. This is useful to be able to sort out multiple bindings when installed at the same source location.
      Parameters:
      bindings - a collection of bindings to find the event nodes for at this context location
      Since:
      19.0

    • createUnwind

      public ThreadDeath createUnwind(Object info)
      Create an unwind throwable, that when thrown, abruptly breaks execution of a node and unwinds it off the execution stack. This is a a shortcut for createUnwind(Object, EventBinding) with the current binding, only the event listener instance that threw the unwind throwable gets called onUnwind.
      Parameters:
      info - an info that is passed into ExecutionEventListener.onUnwind(EventContext, VirtualFrame, Object) or ExecutionEventNode.onUnwind(VirtualFrame, Object). It can be used for arbitrary client data that help to control the unwind process.
      Since:
      0.31
      See Also:

    • createUnwind

      public ThreadDeath createUnwind(Object info, EventBinding<?> unwindBinding)
      Create an unwind throwable, that when thrown, abruptly breaks execution of a node and unwinds it off the execution stack. It's to be thrown in onEnter, onReturnValue or onReturnExceptional methods of ExecutionEventListener or ExecutionEventNode, to initiate the unwind process. It acts in connection with ExecutionEventListener.onUnwind(EventContext, VirtualFrame, Object) or ExecutionEventNode.onUnwind(VirtualFrame, Object). Only the event listener instance that is associated with the provided unwindBinding gets called onUnwind, use createUnwind(java.lang.Object) to have the current event listener called onUnwind. Other bindings that happen to instrument the unwound nodes get called onReturnExceptional.

      The returned throwable can be kept and thrown again later to repeat the unwind process. A repeating unwind process is possible without deoptimization. A single throwable instance cannot be used on multiple threads concurrently. It can be thrown on a different thread only after the unwind finishes on the last thread.

      Usage example of forced return: 

      protected void onCreate(TruffleInstrument.Env env) {
    // Register a listener that checks the return value to all call nodes
    // If the return value is not 42, it forces to return 42.
    env.getInstrumenter().attachExecutionEventListener(
        SourceSectionFilter.newBuilder().
                            tagIs(StandardTags.CallTag.class).build(),
        new ExecutionEventListener() {
            public void onEnter(EventContext context, VirtualFrame f) { }
            public void onReturnValue(EventContext context,
                                      VirtualFrame f, Object result) {
                if (!Objects.equals(result, 42)) {
                    CompilerDirectives.transferToInterpreter();
                    throw context.createUnwind(42);
                }
            }
            public Object onUnwind(EventContext context,
                                   VirtualFrame f, Object info) {
                // return 42 on unwind
                return info;
            }
            public void onReturnExceptional(EventContext context,
                                            VirtualFrame f, Throwable ex) { }
        });
}

      Usage example of reenter: 

      protected void onCreate(TruffleInstrument.Env env) {
    // Two event bindings are created: one for reenter, one for unwind

    // Listener that reenters on unwind, attached to root nodes.
    EventBinding<ExecutionEventListener> functionReenter =
        env.getInstrumenter().attachExecutionEventListener(
            SourceSectionFilter.newBuilder().
                                tagIs(StandardTags.RootTag.class).build(),
        new ExecutionEventListener() {
            public Object onUnwind(EventContext context,
                                   VirtualFrame f, Object info) {
                // Reenters on unwind.
                return ProbeNode.UNWIND_ACTION_REENTER;
            }
            public void onEnter(EventContext context, VirtualFrame f) { }
            public void onReturnValue(EventContext context,
                                      VirtualFrame f, Object result) { }
            public void onReturnExceptional(EventContext context,
                                            VirtualFrame f, Throwable ex) { }
        });

    // Listener that initiates unwind at line 20, attached to statements.
    env.getInstrumenter().attachExecutionEventListener(
        SourceSectionFilter.newBuilder().
                            tagIs(StandardTags.StatementTag.class).build(),
        new ExecutionEventListener() {
            public void onEnter(EventContext context, VirtualFrame f) {
                SourceSection ss = context.getInstrumentedSourceSection();
                if (ss.getStartLine() == 20) {
                    CompilerDirectives.transferToInterpreter();
                    // Unwind to nodes instrumented by functionReenter
                    throw context.createUnwind(null, functionReenter);
                }
            }
            public void onReturnValue(EventContext context,
                                      VirtualFrame f, Object result) { }
            public void onReturnExceptional(EventContext context,
                                            VirtualFrame f, Throwable ex) { }
        });
}
      Parameters:
      info - an info that is passed into ExecutionEventListener.onUnwind(EventContext, VirtualFrame, Object) or ExecutionEventNode.onUnwind(VirtualFrame, Object). It can be used for arbitrary client data that help to control the unwind process.
      unwindBinding - the binding whose listener's onUnwind is to be called, or null to call the current listener that throws the returned throwable.
      Since:
      0.31

    • createError

      @Deprecated(since="21.3") public RuntimeException createError(RuntimeException e)
      Deprecated.
      No substitute. Runtime exceptions can now be thrown directly and will be observable by the guest language application.
      Creates a runtime exception that when thrown is observable to the guest language application. Be aware that errors propagated to the guest application may significantly alter the behavior of the guest application influencing other instruments which may limit them ability of them to be composed. If not wrapped using this method any exception caused by an execution event instrumentation is printed to the error stream.

      Propagating runtime errors is supported in the following events:

      Errors may not be propagated in ExecutionEventNodeFactory.create(EventContext) as this may lead to unstable ASTs.

      If an error is propagated all other installed execution event listeners will continue to be notified. If multiple listeners propagate errors then the first error will be propagated and later errors will be attached to the first as suppressed exception. The notification order relates to the order the bindings were installed.

      Parameters:
      e - the exception to propagate.
      Since:
      20.0

    • toString

      public String toString()
      Overrides:
      toString in class Object
      Since:
      0.12