Package com.illumon.iris.db.v2.remote

Class ConstructSnapshot

java.lang.Object
com.illumon.iris.db.v2.remote.ConstructSnapshot
public class ConstructSnapshot extends Object
A Set of static utilities for computing values from a table while avoiding the use of the LTM lock. This class supports snapshots in both position space and key space.

  • Constructor Details

    • ConstructSnapshot

      public ConstructSnapshot()

  • Method Details

    • concurrentAttemptInconsistent

      public static boolean concurrentAttemptInconsistent()
      Test that determines whether the currently-active concurrent snapshot attempt has become inconsistent. Always returns false if there is no snapshot attempt active, or if there is a locked attempt active (necessarily at lower depth than the lowest concurrent attempt).
      Returns:
      Whether the clock or sources have changed in such a way as to make the currently-active concurrent snapshot attempt inconsistent

    • failIfConcurrentAttemptInconsistent

      public static void failIfConcurrentAttemptInconsistent()
      Check that fails if the currently-active concurrent snapshot attempt has become inconsistent. source. This is a no-op if there is no snapshot attempt active, or if there is a locked attempt active (necessarily at lower depth than the lowest concurrent attempt).
      Throws:
      ConstructSnapshot.SnapshotInconsistentException - If the currently-active concurrent snapshot attempt has become inconsistent

    • maybeWaitForSatisfaction

      public static void maybeWaitForSatisfaction(@Nullable NotificationQueue.Dependency dependency)
      Wait for a dependency to become satisfied on the current cycle if we're trying to use current values for the currently-active concurrent snapshot attempt. This is a no-op if there is no snapshot attempt active, or if there is a locked attempt active (necessarily at lower depth than the lowest concurrent attempt).
      Parameters:
      dependency - The dependency, which may be null in order to avoid redundant checks in calling code
      Throws:
      ConstructSnapshot.SnapshotInconsistentException - If we cannot wait for this dependency on the current step because the step changed

    • getConcurrentAttemptClockValue

      public static long getConcurrentAttemptClockValue()
      Return the currently-active concurrent snapshot attempt's "before" clock value, or zero if there is no concurrent attempt active.
      Returns:
      The concurrent snapshot attempt's "before" clock value, or zero

    • appendConcurrentAttemptClockInfo

      public static com.fishlib.base.log.LogOutput appendConcurrentAttemptClockInfo(@NotNull com.fishlib.base.log.LogOutput logOutput)
      Append clock info that pertains to the concurrent attempt state to logOutput.
      Parameters:
      logOutput - The LogOutput
      Returns:
      logOutput

    • constructInitialSnapshot

      public static InitialSnapshot constructInitialSnapshot(Object logIdentityObject, @NotNull BaseTable table)
      Create a snapshot of the entire table specified. Note that this method is notification-oblivious, i.e. it makes no attempt to ensure that notifications are not missed.
      Parameters:
      logIdentityObject - An object used to prepend to log rows.
      table - the table to snapshot.
      Returns:
      a snapshot of the entire base table.

    • constructInitialSnapshot

      public static InitialSnapshot constructInitialSnapshot(Object logIdentityObject, @NotNull BaseTable table, BitSet columnsToSerialize, Index keysToSnapshot)
      Create a snapshot of the specified table using a set of requested columns and keys. Note that this method uses an index that is in Key space, and that it is notification-oblivious, i.e. it makes no attempt to ensure that notifications are not missed.
      Parameters:
      logIdentityObject - An object used to prepend to log rows.
      table - the table to snapshot.
      columnsToSerialize - a bitset of columns to include in the snapshot
      keysToSnapshot - an Index of keys to include in the snapshot
      Returns:
      a snapshot of the entire base table.

    • constructInitialSnapshotInPositionSpace

      public static InitialSnapshot constructInitialSnapshotInPositionSpace(Object logIdentityObject, @NotNull BaseTable table, BitSet columnsToSerialize, Index positionsToSnapshot)
      Create a snapshot of the specified table using a set of requested columns and positions. Note that this method uses an index that is in Position space, and that it is notification-oblivious, i.e. it makes no attempt to ensure that notifications are not missed.
      Parameters:
      logIdentityObject - An object used to prepend to log rows.
      table - the table to snapshot.
      columnsToSerialize - a bitset of columns to include in the snapshot
      positionsToSnapshot - an Index of keys to include in the snapshot
      Returns:
      a snapshot of the entire base table.

    • constructInitialSnapshots

      public static List<InitialSnapshot> constructInitialSnapshots(Object logIdentityObject, BaseTable... tables)
      Constructs InitialSnapshots for the entirety of the tables. Note that this method is notification-oblivious, i.e. it makes no attempt to ensure that notifications are not missed.
      Parameters:
      logIdentityObject - identifier prefixing the log message
      tables - tables to snapshot
      Returns:
      list of the resulting InitialSnapshots

    • makeSnapshotControl

      public static ConstructSnapshot.SnapshotControl makeSnapshotControl(@NotNull ConstructSnapshot.UsePreviousValues usePreviousValues, @NotNull ConstructSnapshot.SnapshotConsistent snapshotConsistent, @Nullable ConstructSnapshot.SnapshotCompletedConsistently snapshotCompletedConsistently)

    • makeSnapshotControl

      public static ConstructSnapshot.SnapshotControl makeSnapshotControl(boolean notificationAware, @NotNull NotificationStepSource source)
      Make a default ConstructSnapshot.SnapshotControl for a single source.
      Parameters:
      notificationAware - Whether the result should be concerned with not missing notifications
      source - The source
      Returns:
      An appropriate ConstructSnapshot.SnapshotControl

    • makeSnapshotControl

      public static ConstructSnapshot.SnapshotControl makeSnapshotControl(boolean notificationAware, @NotNull NotificationStepSource... sources)
      Make a default ConstructSnapshot.SnapshotControl for one or more sources.
      Parameters:
      notificationAware - Whether the result should be concerned with not missing notifications
      sources - The sources
      Returns:
      An appropriate ConstructSnapshot.SnapshotControl

    • callDataSnapshotFunction

      public static long callDataSnapshotFunction(@NotNull String logPrefix, @NotNull ConstructSnapshot.SnapshotControl control, @NotNull ConstructSnapshot.SnapshotFunction function)
      Invokes the snapshot function in a loop until it succeeds with provably consistent results, or until MAX_CONCURRENT_ATTEMPTS or MAX_CONCURRENT_ATTEMPT_DURATION_MILLIS are exceeded. Falls back to acquiring a shared LTM lock for a final attempt.
      Parameters:
      logPrefix - A prefix for our log messages
      control - A ConstructSnapshot.SnapshotControl to define the parameters and consistency for this snapshot
      function - The function to execute
      Returns:
      The logical clock step that applied to this snapshot

    • callDataSnapshotFunction

      public static long callDataSnapshotFunction(@NotNull com.fishlib.base.log.LogOutputAppendable logPrefix, @NotNull ConstructSnapshot.SnapshotControl control, @NotNull ConstructSnapshot.SnapshotFunction function)
      Invokes the snapshot function in a loop until it succeeds with provably consistent results, or until MAX_CONCURRENT_ATTEMPTS or MAX_CONCURRENT_ATTEMPT_DURATION_MILLIS are exceeded. Falls back to acquiring a shared LTM lock for a final attempt.
      Parameters:
      logPrefix - A prefix for our log messages
      control - A ConstructSnapshot.SnapshotControl to define the parameters and consistency for this snapshot
      function - The function to execute
      Returns:
      The logical clock step that applied to this snapshot

    • serializeAllTable

      public static boolean serializeAllTable(boolean usePrev, InitialSnapshot snapshot, BaseTable table, Object logIdentityObject, BitSet columnsToSerialize, Index keysToSnapshot)

      Populate an InitialSnapshot with the specified keys and columns to snapshot.

      Note that care must be taken while using this method to ensure the underlying table is locked or does not change, otherwise the resulting snapshot may be inconsistent. In general users should instead use constructInitialSnapshot(java.lang.Object, com.illumon.iris.db.v2.BaseTable) for simple use cases or callDataSnapshotFunction(int, com.illumon.iris.db.v2.remote.ConstructSnapshot.SnapshotControl, com.illumon.iris.db.v2.remote.ConstructSnapshot.SnapshotFunction) for more advanced uses.

      Parameters:
      usePrev - Whether to use previous values
      snapshot - The snapshot to populate
      logIdentityObject - An object for use with log() messages
      columnsToSerialize - A BitSet of columns to include, null for all
      keysToSnapshot - An Index of keys within the table to include, null for all
      Returns:
      Whether the snapshot succeeded

    • estimateSnapshotSize

      public static long estimateSnapshotSize(Table table)
      Estimate the size of a complete table snapshot in bytes.
      Parameters:
      table - the table to estimate
      Returns:
      the estimated snapshot size in bytes.

    • estimateSnapshotSize

      public static long estimateSnapshotSize(TableDefinition tableDefinition, BitSet columns, long rowCount)
      Make a rough guess at the size of a snapshot, using the column types and common column names. The use case is when a user requests something from the GUI; we'd like to know if it is ridiculous before actually doing it.
      Parameters:
      tableDefinition - the table definitionm
      columns - a bitset indicating which columns are included
      rowCount - how many rows of this data we'll be snapshotting
      Returns:
      the estimated size of the snapshot