Package io.deephaven.engine.updategraph

Interface UpdateGraph

All Superinterfaces:
LogOutputAppendable, NotificationQueue, NotificationQueue.Dependency, UpdateSourceRegistrar
All Known Implementing Classes:
BaseUpdateGraph, EventDrivenUpdateGraph, PeriodicUpdateGraph, PoisonedUpdateGraph
public interface UpdateGraph extends UpdateSourceRegistrar, NotificationQueue, NotificationQueue.Dependency

  • Method Details

    • getName

      String getName()
      Returns:
      The name of this UpdateGraph

    • sharedLock

      AwareFunctionalLock sharedLock()
      Returns:
      The shared AwareFunctionalLock to use with this update graph

    • exclusiveLock

      AwareFunctionalLock exclusiveLock()
      Returns:
      The exclusive AwareFunctionalLock to use with this update graph

    • clock

      LogicalClock clock()
      Returns:
      The LogicalClock to use with this update graph

    • parallelismFactor

      int parallelismFactor()
      Retrieve the number of independent update propagation tasks this UpdateGraph can process concurrently.

      For example, an implementation using a fixed-size thread pool of update task workers should return the size of the thread pool.

      This is exposed in order to allow users to determine the ideal way to partition their queries for maximum parallelism without undue overhead.

      Returns:
      number of independent update propagation tasks this UpdateGraph can process concurrently

    • cast

      default <UG_TYPE extends UpdateGraph> UG_TYPE cast()
      Cast this to a more specific UpdateGraph type, in order to access implementation-specific methods.
      Type Parameters:
      UG_TYPE - The UpdateGraph type to cast to
      Returns:
      this

    • logDependencies

      LogEntry logDependencies()
      Returns:
      A LogEntry that may be prefixed with UpdateGraph information

    • currentThreadProcessesUpdates

      boolean currentThreadProcessesUpdates()
      Test if the current thread is involved in processing updates for this UpdateGraph. If so, non-terminal user notifications on the current thread must not attempt to lock this UpdateGraph.
      Returns:
      Whether the current thread is involved in processing updates for this UpdateGraph

    • serialTableOperationsSafe

      boolean serialTableOperationsSafe()
      Test if engine code executing on the current thread should assume safety for serial table operations. Operations annotated as concurrent are always safe.
      Returns:
      Whether code on this thread should assume serial table operation safety
      See Also:

    • setSerialTableOperationsSafe

      boolean setSerialTableOperationsSafe(boolean newValue)
      User or engine code that makes its own determination about the safety of initiating serial table operations on the current thread may use this method to override default behavior. The previous value should be restored immediately after use, typically with the following pattern: 
       boolean oldValue = assumeSerialTableOperations(true);
 try {
     // ... safe table operations here
 } finally {
     assumeSerialTableOperations(oldValue);
 }
      Parameters:
      newValue - the new value
      Returns:
      the old value
      See Also:

    • allowSerialTableOperations

      default <RETURN_TYPE> RETURN_TYPE allowSerialTableOperations(@NotNull @NotNull Supplier<RETURN_TYPE> operation)
      User or engine code that is certain a particular table operation is safe to execute with respect to this UpdateGraph may use this method to follow the prescribed pattern for declaring safety and reinstating the priority safety parameters.
      Type Parameters:
      RETURN_TYPE - The return type of the operation
      Parameters:
      operation - The safe operation to perform
      Returns:
      The result of operation
      See Also:

    • allowSerialTableOperations

      default <RETURN_TYPE, EXCEPTION_TYPE extends Exception> RETURN_TYPE allowSerialTableOperations(@NotNull @NotNull ThrowingSupplier<RETURN_TYPE,EXCEPTION_TYPE> operation) throws EXCEPTION_TYPE
      User or engine code that is certain a particular table operation is safe to execute with respect to this UpdateGraph may use this method to follow the prescribed pattern for declaring safety and reinstating the priority safety parameters.
      Type Parameters:
      RETURN_TYPE - The return type of the operation
      EXCEPTION_TYPE - The exception type the operation might throw
      Parameters:
      operation - The safe operation to perform
      Returns:
      The result of operation
      Throws:
      EXCEPTION_TYPE - if operation throws
      See Also:

    • checkInitiateSerialTableOperation

      default void checkInitiateSerialTableOperation()
      If we initiate a serial (not annotated as concurrent) table operation that should update using this UpdateGraph without holding the appropriate lock, then we are likely committing a grievous error, but one that will only occasionally result in us getting the wrong answer or if we are lucky an assertion. This method is called from various table operations that should not be established without locking their UpdateGraph.

      Threads that process this UpdateGraph's updates are assumed to be safe; if dependencies are tracked correctly, these threads will only initiate table operations when they can proceed.

      User or engine code may bypass this check using setSerialTableOperationsSafe(boolean) or the related wrapper methods.

      See Also:

    • stop

      void stop()
      Attempt to stop this update graph, and cease processing further notifications.

    • supportsRefreshing

      boolean supportsRefreshing()
      Returns:
      Whether this UpdateGraph has a mechanism that supports refreshing

    • requestRefresh

      void requestRefresh()
      Request that this UpdateGraph process any pending updates as soon as practicable. Updates "hurried" in this way are otherwise processed as normal.
      Specified by:
      requestRefresh in interface UpdateSourceRegistrar

    • requestSignal

      default void requestSignal(Condition exclusiveLockCondition)
      Request that a Condition derived from this UpdateGraph's exclusiveLock() be signalled in a safe manner. This may take place asynchronously.
      Parameters:
      exclusiveLockCondition - The condition to signal

    • runWhenIdle

      @FinalDefault default void runWhenIdle(@NotNull @NotNull Runnable task)
      Run task immediately if this UpdateGraph is currently idle, else schedule task to run at a later time when it has become idle.
      Parameters:
      task - The task to run when idle