Package org.graalvm.polyglot.management

Class ExecutionListener.Builder

java.lang.Object
org.graalvm.polyglot.management.ExecutionListener.Builder
Enclosing class:
ExecutionListener
public final class ExecutionListener.Builder extends Object
A builder used to construct execution events. Builder instances are not thread-safe and may not be used from multiple threads at the same time.
Since:
19.0
See Also:

  • Method Details

    • onEnter

      public ExecutionListener.Builder onEnter(Consumer<ExecutionEvent> listener)
      Set a listener that is notified when an execution of an element is entered.
      Since:
      19.0

    • onReturn

      public ExecutionListener.Builder onReturn(Consumer<ExecutionEvent> listener)
      Set a listener that is notified when an execution of an element was entered and completed.
      Since:
      19.0

    • sourceFilter

      public ExecutionListener.Builder sourceFilter(Predicate<Source> predicate)
      Set an addition filter that filters execution events by source. By default all sources are included. Source predicates must be stable, i.e. always return the same result for a source. The filter predicate may be invoked on multiple threads at the same time.
      Parameters:
      predicate - the source predicate that returns true for a source to be included and false otherwise.
      Since:
      19.0

    • rootNameFilter

      public ExecutionListener.Builder rootNameFilter(Predicate<String> predicate)
      Set an addition filter execution events by root name. By default all root names are included. Root name predicates must be stable and always return the same result for source. The filter predicate may be invoked on multiple threads at the same time.
      Since:
      19.0

    • roots

      public ExecutionListener.Builder roots(boolean enabled)
      Include program locations that are marked as root of a function, method or closure. By default no source elements are included.
      Parameters:
      enabled - true if enabled, else false
      Since:
      19.0
      See Also:

    • statements

      public ExecutionListener.Builder statements(boolean enabled)
      Include program locations that are marked as statements. By default no source elements are included.
      Parameters:
      enabled - true if enabled, else false
      Since:
      19.0
      See Also:

    • expressions

      public ExecutionListener.Builder expressions(boolean enabled)
      Include program locations that are marked as expressions. By default no source elements are included.
      Parameters:
      enabled - true if enabled, else false
      Since:
      19.0
      See Also:

    • collectInputValues

      public ExecutionListener.Builder collectInputValues(boolean enabled)
      Collect additional execution event data for input values. The input values may be accessed in OnReturn events with ExecutionEvent.getInputValues().

      If additional event data is collected then the peak performance overhead of execution listeners is significant. It is not recommended to collect additional event data when running production workloads.

      Parameters:
      enabled - true if enabled, else false
      Since:
      19.0

    • collectReturnValue

      public ExecutionListener.Builder collectReturnValue(boolean enabled)
      Collect additional execution event data about return values. The return value may be accessed in OnReturn events with ExecutionEvent.getReturnValue().

      If additional event data is collected then the peak performance overhead of execution listeners is significant. It is not recommended to collect additional event data when running production workloads.

      Parameters:
      enabled - true if enabled, else false
      Since:
      19.0

    • collectExceptions

      public ExecutionListener.Builder collectExceptions(boolean enabled)
      Collect additional execution event data about errors. The error may be accessed in OnReturn events with ExecutionEvent.getException().

      If additional event data is collected then the peak performance overhead of execution listeners is significant. It is not recommended to collect additional event data when running production workloads.

      Parameters:
      enabled - true if enabled, else false
      Since:
      19.0

    • attach

      public ExecutionListener attach(Engine engine)
      Creates a new execution listener using the current builder configuration and attaches it to an engine. The same builder configuration may be used to attach multiple listeners.

      Execution listeners cannot be attached to engines that were statically looked up using Context.getCurrent().getEngine() . For security reasons only the original creator of the context or engine is allowed to perform this action.

      Attaching and closing execution listeners are expensive operations and typically require to traverse through all loaded code. Code that was previously optimized will be deoptimized in the process. It is most efficient to attach an execution listener before any code is executed and let execution listeners automatically close with the engine.

      Parameters:
      engine - the engine to attach to
      Returns:
      the attached closable execution listener.
      Throws:
      PolyglotException - if one of the provided filter predicate fails.
      Since:
      19.0