Package io.deephaven.engine.table.impl.perf

Interface QueryPerformanceRecorder

All Known Implementing Classes:
QueryPerformanceRecorderImpl
public interface QueryPerformanceRecorder
Query performance instrumentation tools. Manages a hierarchy of QueryPerformanceNugget instances.

  • Field Details

  • Method Details

    • getInstance

      static QueryPerformanceRecorder getInstance()

    • getNugget

      @FinalDefault default QueryPerformanceNugget getNugget(@NotNull @NotNull String name)
      Create a nugget at the top of the user stack. May return a QueryPerformanceNugget.DUMMY_NUGGET if no recorder is installed.
      Parameters:
      name - the nugget name
      Returns:
      A new QueryPerformanceNugget to encapsulate user query operations. QueryPerformanceNugget.close() must be called on the nugget.

    • getNugget

      QueryPerformanceNugget getNugget(@NotNull @NotNull String name, long inputSize)
      Create a nugget at the top of the user stack. May return a QueryPerformanceNugget.DUMMY_NUGGET if no recorder is installed.
      Parameters:
      name - the nugget name
      inputSize - the nugget's input size
      Returns:
      A new QueryPerformanceNugget to encapsulate user query operations. QueryPerformanceNugget.close() must be called on the nugget.

    • getCompilationNugget

      QueryPerformanceNugget getCompilationNugget(@NotNull @NotNull String name)
      Create a nugget at the top of the user stack for a compilation task. May return a QueryPerformanceNugget.DUMMY_NUGGET if no recorder is installed.
      Parameters:
      name - the nugget name
      Returns:
      A new QueryPerformanceNugget to encapsulate the compilation. QueryPerformanceNugget.close() must be called on the nugget.

    • getEnclosingNugget

      QueryPerformanceNugget getEnclosingNugget()
      This is the nugget enclosing the current operation. It may belong to the dummy recorder, or a real one.
      Returns:
      Either a "catch-all" nugget, or the top of the user nugget stack.

    • supplyQueryData

      void supplyQueryData(@NotNull @NotNull QueryPerformanceRecorder.QueryDataConsumer consumer)
      Provide current query data via the consumer.
      Parameters:
      consumer - a callback to receive query data

    • getCallerLine

      static String getCallerLine()
      Returns:
      The current callsite. This is the last set callsite or the line number of the user's detected callsite.

    • setCallsite

      static boolean setCallsite(@NotNull @NotNull String callsite)
      Attempt to set the thread local callsite so that invocations of getCallerLine() will not spend time trying to recompute.

      This method returns a boolean if the value was successfully set. In the event this returns true, it's the responsibility of the caller to invoke clearCallsite() when the operation is complete.

      It is good practice to do this with try{} finally{} block 

       final boolean shouldClear = QueryPerformanceRecorder.setCallsite("CALLSITE");
 try {
     // Do work
 } finally {
     if (shouldClear) {
         QueryPerformanceRecorder.clearCallsite();
     }
 }
      Parameters:
      callsite - The call site to use.
      Returns:
      true if successfully set, false otherwise

    • setCallsite

      static boolean setCallsite()
      Attempt to compute and set the thread local callsite so that invocations of getCallerLine() will not spend time trying to recompute.

      Users should follow the best practice as described by setCallsite(String)

      Returns:
      true if the callsite was computed and set.

    • clearCallsite

      static void clearCallsite()
      Clear any previously set callsite. See setCallsite(String)

    • newQuery

      static QueryPerformanceRecorder newQuery(@NotNull @NotNull String description, @Nullable @Nullable String sessionId, @NotNull QueryPerformanceNugget.Factory nuggetFactory)
      Construct a QueryPerformanceRecorder for a top-level query.
      Parameters:
      description - the query description
      nuggetFactory - the nugget factory
      Returns:
      a new QueryPerformanceRecorder

    • newSubQuery

      static QueryPerformanceRecorder newSubQuery(@NotNull @NotNull String description, @Nullable @Nullable QueryPerformanceRecorder parent, @NotNull QueryPerformanceNugget.Factory nuggetFactory)
      Construct a QueryPerformanceRecorder for a sub-level query.
      Parameters:
      description - the query description
      nuggetFactory - the nugget factory
      Returns:
      a new QueryPerformanceRecorder

    • recordPoolAllocation

      static <RESULT_TYPE> RESULT_TYPE recordPoolAllocation(@NotNull @NotNull Supplier<RESULT_TYPE> operation)
      Record a single-threaded operation's allocations as "pool" allocated memory attributable to the current thread.
      Parameters:
      operation - The operation to record allocation for
      Returns:
      The result of the operation.

    • getState

      QueryState getState()
      Return the query's current state
      Returns:
      the query's state

    • startQuery

      SafeCloseable startQuery()
      Starts a query.

      A query is RUNNING if it has been started or resumed without a subsequent end, suspend, or abort.

      Throws:
      IllegalStateException - if the query state isn't NOT_STARTED or another query is running on this thread

    • endQuery

      boolean endQuery()
      End a query.

      A query is RUNNING if it has been started or resumed without a subsequent end, suspend, or abort.

      Returns:
      whether the query should be logged
      Throws:
      IllegalStateException - if the query state isn't RUNNING, INTERRUPTED, or was not running on this thread

    • suspendQuery

      void suspendQuery()
      Suspends a query.

      A query is RUNNING if it has been started or resumed without a subsequent end, suspend, or abort.

      Throws:
      IllegalStateException - if the query state isn't RUNNING or was not running on this thread

    • resumeQuery

      SafeCloseable resumeQuery()
      Resumes a suspend query.

      A query is RUNNING if it has been started or resumed without a subsequent end, suspend, or abort.

      Throws:
      IllegalStateException - if the query state isn't SUSPENDED or another query is running on this thread

    • abortQuery

      void abortQuery()
      Abort a query.

      A query is RUNNING if it has been started or resumed without a subsequent end, suspend, or abort.

      Note that this method is invoked out-of-band and does not throw if the query has been completed.

    • getQueryLevelPerformanceData

      QueryPerformanceNugget getQueryLevelPerformanceData()
      Returns:
      the query level performance data

    • getOperationLevelPerformanceData

      List<QueryPerformanceNugget> getOperationLevelPerformanceData()
      This getter should be called by exclusive owners of the recorder, and never concurrently with mutators.
      Returns:
      A list of loggable operation performance data.

    • accumulate

      void accumulate(@NotNull @NotNull QueryPerformanceRecorder subQuery)
      Accumulate performance information from another recorder into this one. The provided recorder will not be mutated.
      Parameters:
      subQuery - the recorder to accumulate into this

    • hasSubQueries

      boolean hasSubQueries()
      Returns:
      whether a sub-query was ever accumulated into this recorder

    • withNugget

      static void withNugget(String name, Runnable r)
      Surround the given code with a Performance Nugget
      Parameters:
      name - the nugget name
      r - the stuff to run

    • withNugget

      static <T> T withNugget(String name, Supplier<T> r)
      Surround the given code with a Performance Nugget
      Parameters:
      name - the nugget name
      r - the stuff to run
      Returns:
      the result of the stuff to run

    • withNuggetThrowing

      static <T extends Exception> void withNuggetThrowing(String name, ThrowingRunnable<T> r) throws T
      Surround the given code with a Performance Nugget
      Parameters:
      r - the stuff to run
      Throws:
      T - exception of type T

    • withNuggetThrowing

      static <R, ExceptionType extends Exception> R withNuggetThrowing(String name, ThrowingSupplier<R,ExceptionType> r) throws ExceptionType
      Surround the given code with a Performance Nugget
      Parameters:
      name - the nugget name
      r - the stuff to run
      Returns:
      the result of the stuff to run
      Throws:
      ExceptionType - exception of type ExceptionType

    • withNugget

      static void withNugget(String name, long inputSize, Runnable r)
      Surround the given code with a Performance Nugget
      Parameters:
      name - the nugget name
      r - the stuff to run

    • withNugget

      static <T> T withNugget(String name, long inputSize, Supplier<T> r)
      Surround the given code with a Performance Nugget
      Parameters:
      name - the nugget name
      r - the stuff to run
      Returns:
      the result of the stuff to run

    • withNuggetThrowing

      static <T extends Exception> void withNuggetThrowing(String name, long inputSize, ThrowingRunnable<T> r) throws T
      Surround the given code with a Performance Nugget
      Parameters:
      r - the stuff to run
      Throws:
      T - exception of type T

    • withNuggetThrowing

      static <R, ExceptionType extends Exception> R withNuggetThrowing(String name, long inputSize, ThrowingSupplier<R,ExceptionType> r) throws ExceptionType
      Surround the given code with a Performance Nugget
      Parameters:
      name - the nugget name
      r - the stuff to run
      Returns:
      the result of the stuff to run
      Throws:
      ExceptionType - exception of type ExceptionType