Class ConstructSnapshot
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
static interface
static interface
static interface
Interface used to control snapshot behavior, including previous value usage and consistency testing.static interface
static class
Exception thrown for "fail-fast" purposes when it's been detected that a snapshot will fail.static interface
static final class
An implementation ofConstructSnapshot.SnapshotControl
for sources that cannot update.static interface
Interface forConstructSnapshot.UsePreviousValues.usePreviousValues(long)
. -
Field Summary
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionstatic LogOutput
appendConcurrentAttemptClockInfo
(@NotNull LogOutput logOutput) Append clock info that pertains to the concurrent attempt state tologOutput
.static long
callDataSnapshotFunction
(@NotNull 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 untilMAX_CONCURRENT_ATTEMPTS
orMAX_CONCURRENT_ATTEMPT_DURATION_MILLIS
are exceeded.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 untilMAX_CONCURRENT_ATTEMPTS
orMAX_CONCURRENT_ATTEMPT_DURATION_MILLIS
are exceeded.static boolean
Test that determines whether the currently-active concurrent snapshot attempt has become inconsistent.static BarrageMessage
constructBackplaneSnapshot
(@NotNull Object logIdentityObject, @NotNull BaseTable<?> table) Create asnapshot
of the specified table including all columns and rows.static BarrageMessage
constructBackplaneSnapshotInPositionSpace
(@NotNull Object logIdentityObject, @NotNull BaseTable<?> table, @Nullable BitSet columnsToSerialize, @Nullable RowSequence positionsToSnapshot, @Nullable RowSequence reversePositionsToSnapshot) Create asnapshot
of the specified table using a set of requested columns and positions.static BarrageMessage
constructBackplaneSnapshotInPositionSpace
(@NotNull Object logIdentityObject, @NotNull BaseTable<?> table, @Nullable BitSet columnsToSerialize, @Nullable RowSequence positionsToSnapshot, @Nullable RowSequence reversePositionsToSnapshot, @NotNull ConstructSnapshot.SnapshotControl control) Create asnapshot
of the specified table using a set of requested columns and positions.static InitialSnapshot
constructInitialSnapshot
(@NotNull Object logIdentityObject, @NotNull BaseTable<?> table) Create asnapshot
of the entire table specified.static InitialSnapshot
constructInitialSnapshot
(@NotNull Object logIdentityObject, @NotNull BaseTable<?> table, @Nullable BitSet columnsToSerialize, @Nullable RowSet keysToSnapshot) Create asnapshot
of the specified table using a set of requested columns and keys.static InitialSnapshot
constructInitialSnapshotInPositionSpace
(@NotNull Object logIdentityObject, @NotNull BaseTable<?> table, @Nullable BitSet columnsToSerialize, @Nullable RowSet positionsToSnapshot) Create asnapshot
of the specified table using a set of requested columns and positions.static List<InitialSnapshot>
constructInitialSnapshots
(@NotNull Object logIdentityObject, @NotNull BaseTable<?>... tables) ConstructsInitialSnapshot
s for the entirety of the tables.static long
estimateSnapshotSize
(@NotNull Table table) Estimate the size of a complete table snapshot in bytes.static long
estimateSnapshotSize
(@NotNull TableDefinition tableDefinition, @NotNull BitSet columns, long rowCount) Make a rough guess at the size of a snapshot, using the column types and common column names.static void
Check that fails if the currently-active concurrent snapshot attempt has become inconsistent.static long
Return the currently-active concurrent snapshot attempt's "before" clock value, or zero if there is no concurrent attempt active.makeSnapshotControl
(boolean notificationAware, boolean refreshing, @NotNull NotificationStepSource source) Make a defaultConstructSnapshot.SnapshotControl
for a single source.makeSnapshotControl
(boolean notificationAware, boolean refreshing, @NotNull NotificationStepSource... sources) Make a defaultConstructSnapshot.SnapshotControl
for one or more sources.makeSnapshotControl
(@NotNull UpdateGraph updateGraph, @NotNull ConstructSnapshot.UsePreviousValues usePreviousValues, @NotNull ConstructSnapshot.SnapshotConsistent snapshotConsistent, @Nullable ConstructSnapshot.SnapshotCompletedConsistently snapshotCompletedConsistently) Make aConstructSnapshot.SnapshotControl
from individual function objects.static void
maybeWaitForSatisfaction
(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.static ConstructSnapshot.State
state()
Get the currently-active snapshot state.
-
Field Details
-
SNAPSHOT_CHUNK_SIZE
public static final int SNAPSHOT_CHUNK_SIZE
-
-
Constructor Details
-
ConstructSnapshot
public ConstructSnapshot()
-
-
Method Details
-
state
Get the currently-active snapshot state.- Returns:
- the currently-active snapshot state
-
concurrentAttemptInconsistent
public static boolean concurrentAttemptInconsistent()Test that determines whether the currently-active concurrent snapshot attempt has become inconsistent. Always returnsfalse
if there is no snapshot attempt active, or if there is a locked attempt active (necessarily at lower depth than the lowest concurrent attempt).Equivalent to
state().concurrentAttemptInconsistent()
.- Returns:
- Whether the clock or sources have changed in such a way as to make the currently-active concurrent snapshot attempt inconsistent
- See Also:
-
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).Equivalent to
state().failIfConcurrentAttemptInconsistent()
.- Throws:
ConstructSnapshot.SnapshotInconsistentException
- If the currently-active concurrent snapshot attempt has become inconsistent- See Also:
-
maybeWaitForSatisfaction
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).Equivalent to
state().maybeWaitForSatisfaction(dependency)
.- 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- See Also:
-
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.Equivalent to
state().getConcurrentAttemptClockValue()
.- Returns:
- The concurrent snapshot attempt's "before" clock value, or zero
- See Also:
-
appendConcurrentAttemptClockInfo
Append clock info that pertains to the concurrent attempt state tologOutput
.Equivalent to
state().appendConcurrentAttemptClockInfo(logOutput)
.- Parameters:
logOutput
- TheLogOutput
- Returns:
logOutput
- See Also:
-
constructInitialSnapshot
public static InitialSnapshot constructInitialSnapshot(@NotNull @NotNull Object logIdentityObject, @NotNull @NotNull BaseTable<?> table) Create asnapshot
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(@NotNull @NotNull Object logIdentityObject, @NotNull @NotNull BaseTable<?> table, @Nullable @Nullable BitSet columnsToSerialize, @Nullable @Nullable RowSet keysToSnapshot) Create asnapshot
of the specified table using a set of requested columns and keys. Note that this method uses a RowSet 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
- ABitSet
of columns to include, null for allkeysToSnapshot
- An RowSet of keys within the table to include, null for all- Returns:
- a snapshot of the entire base table.
-
constructInitialSnapshotInPositionSpace
public static InitialSnapshot constructInitialSnapshotInPositionSpace(@NotNull @NotNull Object logIdentityObject, @NotNull @NotNull BaseTable<?> table, @Nullable @Nullable BitSet columnsToSerialize, @Nullable @Nullable RowSet positionsToSnapshot) Create asnapshot
of the specified table using a set of requested columns and positions. Note that this method uses a RowSet 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
- ABitSet
of columns to include, null for allpositionsToSnapshot
- An RowSet of positions within the table to include, null for all- Returns:
- a snapshot of the entire base table.
-
constructBackplaneSnapshot
public static BarrageMessage constructBackplaneSnapshot(@NotNull @NotNull Object logIdentityObject, @NotNull @NotNull BaseTable<?> table) Create asnapshot
of the specified table including all columns and rows. 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.
-
constructBackplaneSnapshotInPositionSpace
public static BarrageMessage constructBackplaneSnapshotInPositionSpace(@NotNull @NotNull Object logIdentityObject, @NotNull @NotNull BaseTable<?> table, @Nullable @Nullable BitSet columnsToSerialize, @Nullable @Nullable RowSequence positionsToSnapshot, @Nullable @Nullable RowSequence reversePositionsToSnapshot) Create asnapshot
of the specified table using a set of requested columns and positions. Note that this method uses a RowSet 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
- ABitSet
of columns to include, null for allpositionsToSnapshot
- An RowSet of positions within the table to include, null for all- Returns:
- a snapshot of the entire base table.
-
constructBackplaneSnapshotInPositionSpace
public static BarrageMessage constructBackplaneSnapshotInPositionSpace(@NotNull @NotNull Object logIdentityObject, @NotNull @NotNull BaseTable<?> table, @Nullable @Nullable BitSet columnsToSerialize, @Nullable @Nullable RowSequence positionsToSnapshot, @Nullable @Nullable RowSequence reversePositionsToSnapshot, @NotNull @NotNull ConstructSnapshot.SnapshotControl control) Create asnapshot
of the specified table using a set of requested columns and positions. Note that this method uses a RowSet that is in position space.- Parameters:
logIdentityObject
- An object used to prepend to log rows.table
- the table to snapshot.columnsToSerialize
- ABitSet
of columns to include, null for allpositionsToSnapshot
- A RowSequence of positions within the table to include, null for allreversePositionsToSnapshot
- A RowSequence of reverse positions within the table to include, null for allcontrol
- AConstructSnapshot.SnapshotControl
to define the parameters and consistency for this snapshot- Returns:
- a snapshot of the entire base table.
-
constructInitialSnapshots
public static List<InitialSnapshot> constructInitialSnapshots(@NotNull @NotNull Object logIdentityObject, @NotNull @NotNull BaseTable<?>... tables) ConstructsInitialSnapshot
s 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 messagetables
- tables to snapshot- Returns:
- list of the resulting
InitialSnapshot
s
-
makeSnapshotControl
public static ConstructSnapshot.SnapshotControl makeSnapshotControl(@NotNull @NotNull UpdateGraph updateGraph, @NotNull @NotNull ConstructSnapshot.UsePreviousValues usePreviousValues, @NotNull @NotNull ConstructSnapshot.SnapshotConsistent snapshotConsistent, @Nullable @Nullable ConstructSnapshot.SnapshotCompletedConsistently snapshotCompletedConsistently) Make aConstructSnapshot.SnapshotControl
from individual function objects.- Parameters:
updateGraph
- TheUpdateGraph
for the snapshotusePreviousValues
- TheConstructSnapshot.UsePreviousValues
to usesnapshotConsistent
- TheConstructSnapshot.SnapshotConsistent
to usesnapshotCompletedConsistently
- TheConstructSnapshot.SnapshotCompletedConsistently
to use, or null to usesnapshotConsistent
-
makeSnapshotControl
public static ConstructSnapshot.SnapshotControl makeSnapshotControl(boolean notificationAware, boolean refreshing, @NotNull @NotNull NotificationStepSource source) Make a defaultConstructSnapshot.SnapshotControl
for a single source.- Parameters:
notificationAware
- Whether the result should be concerned with not missing notificationsrefreshing
- Whether the data source (usually aTable
table) is refreshing (vs static)source
- The source- Returns:
- An appropriate
ConstructSnapshot.SnapshotControl
-
makeSnapshotControl
public static ConstructSnapshot.SnapshotControl makeSnapshotControl(boolean notificationAware, boolean refreshing, @NotNull @NotNull NotificationStepSource... sources) Make a defaultConstructSnapshot.SnapshotControl
for one or more sources.- Parameters:
notificationAware
- Whether the result should be concerned with not missing notificationsrefreshing
- Whether any of the data sources (usuallytables
) are refreshing (vs static)sources
- The sources- Returns:
- An appropriate
ConstructSnapshot.SnapshotControl
-
callDataSnapshotFunction
public static long callDataSnapshotFunction(@NotNull @NotNull String logPrefix, @NotNull @NotNull ConstructSnapshot.SnapshotControl control, @NotNull @NotNull ConstructSnapshot.SnapshotFunction function) Invokes the snapshot function in a loop until it succeeds with provably consistent results, or untilMAX_CONCURRENT_ATTEMPTS
orMAX_CONCURRENT_ATTEMPT_DURATION_MILLIS
are exceeded. Falls back to acquiring a shared update graph lock for a final attempt.- Parameters:
logPrefix
- A prefix for our log messagescontrol
- AConstructSnapshot.SnapshotControl
to define the parameters and consistency for this snapshotfunction
- The function to execute- Returns:
- The logical clock step that applied to this snapshot
-
callDataSnapshotFunction
public static long callDataSnapshotFunction(@NotNull @NotNull LogOutputAppendable logPrefix, @NotNull @NotNull ConstructSnapshot.SnapshotControl control, @NotNull @NotNull ConstructSnapshot.SnapshotFunction function) Invokes the snapshot function in a loop until it succeeds with provably consistent results, or untilMAX_CONCURRENT_ATTEMPTS
orMAX_CONCURRENT_ATTEMPT_DURATION_MILLIS
are exceeded. Falls back to acquiring a shared update graph lock for a final attempt.The supplied
ConstructSnapshot.SnapshotControl
'susePreviousValues
will be invoked at the start of any snapshot attempt, and itssnapshotCompletedConsistently
will be invoked at the end of any snapshot attempt that is not provably inconsistent.If the supplied
ConstructSnapshot.SnapshotControl
provides a nullUpdateGraph
, then this method will perform a static snapshot without locks or retrying. In this case, theConstructSnapshot.SnapshotControl
'susePreviousValues
must returnfalse
,snapshotCompletedConsistently
must returntrue
, and theNULL_CLOCK_VALUE
will be supplied tousePreviousValues
andsnapshotCompletedConsistently
.- Parameters:
logPrefix
- A prefix for our log messagescontrol
- AConstructSnapshot.SnapshotControl
to define the parameters and consistency for this snapshotfunction
- The function to execute- Returns:
- The logical clock step that applied to this snapshot; -1L for static snapshots
-
estimateSnapshotSize
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(@NotNull @NotNull TableDefinition tableDefinition, @NotNull @NotNull 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 definitioncolumns
- a bitset indicating which columns are includedrowCount
- how many rows of this data we'll be snapshotting- Returns:
- the estimated size of the snapshot
-