Package com.apple.foundationdb.record.provider.foundationdb.synchronizedsession

Class SynchronizedSessionRunner

java.lang.Object

com.apple.foundationdb.record.provider.foundationdb.synchronizedsession.SynchronizedSessionRunner

All Implemented Interfaces:

FDBDatabaseRunner, AutoCloseable

@API(EXPERIMENTAL)
public class SynchronizedSessionRunner
extends Object
implements FDBDatabaseRunner

An FDBDatabaseRunner implementation that performs all work in the context of a SynchronizedSession.

For all variations of run and runAsync methods, the work in the retriable lambda is wrapped by calls that check locks and update leases to ensure that two synchronized sessions are not concurrently running at the same time.

See Also:

SynchronizedSession

Nested Class Summary

Nested classes/interfaces inherited from interface com.apple.foundationdb.record.provider.foundationdb.FDBDatabaseRunner

FDBDatabaseRunner.RunnerClosed

Method Summary

Modifier and Type	Method	Description
<T> T	asyncToSync(StoreTimer.Wait event, CompletableFuture<T> async)
void	close()	Close this runner.
void	endAnySession()	Synchronous/blocking version of endAnySessionAsync().
CompletableFuture<Void>	endAnySessionAsync()	Releases the lock to end any synchronized session on the same lock subspace, no matter whether the current session holds the lock or not.
void	endSession()	Synchronous/blocking version of endSessionAsync().
CompletableFuture<Void>	endSessionAsync()	Releases the lock to end the synchronized session.
FDBRecordContextConfig.Builder	getContextConfigBuilder()	Get the configuration used in record contexts opened by this runner.
FDBDatabase	getDatabase()	Get the database against which functions are run.
Executor	getExecutor()	Get the executor that will be used for FDBDatabaseRunner.runAsync(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, java.util.concurrent.CompletableFuture<? extends T>>).
long	getInitialDelayMillis()	Gets the delay ceiling (in milliseconds) that will be applied between attempts to run a transactional database operation.
int	getMaxAttempts()	Gets the maximum number of attempts for a database to make when running a retriable transactional operation.
long	getMaxDelayMillis()	Gets the maximum delay (in milliseconds) that will be applied between attempts to run a transactional database operation.
long	getMinDelayMillis()	Gets the minimum delay (in milliseconds) that will be applied between attempts to run a transactional database operation.
UUID	getSessionId()
static SynchronizedSessionRunner	joinSession(Subspace lockSubspace, UUID sessionId, long leaseLengthMill, FDBDatabaseRunnerImpl runner)	Produces a new runner, wrapping a given runner, which performs all work in the context of an existing SynchronizedSession.
SynchronizedSessionRunner	joinSynchronizedSession(Subspace lockSubspace, UUID sessionId, long leaseLengthMillis)	Produces a new runner, wrapping this runner, which performs all work in the context of an existing SynchronizedSession.
FDBRecordContext	openContext()	Open a new record context.
<T> T	run(Function<? super FDBRecordContext,? extends T> retriable, List<Object> additionalLogMessageKeyValues)	Runs a transactional function against with retry logic.
<T> CompletableFuture<T>	runAsync(Function<? super FDBRecordContext,CompletableFuture<? extends T>> retriable, BiFunction<? super T,Throwable,? extends org.apache.commons.lang3.tuple.Pair<? extends T,? extends Throwable>> handlePostTransaction, List<Object> additionalLogMessageKeyValues)	Runs a transactional function asynchronously with retry logic.
void	setContextConfigBuilder(FDBRecordContextConfig.Builder contextConfigBuilder)	Set the configuration used in record contexts opened by this runner.
void	setInitialDelayMillis(long initialDelayMillis)	Sets the delay ceiling (in milliseconds) that will be applied between attempts to run a transactional database operation.
void	setMaxAttempts(int maxAttempts)	Sets the maximum number of attempts for a database to make when running a retriable transactional operation.
void	setMaxDelayMillis(long maxDelayMillis)	Sets the maximum delay (in milliseconds) that will be applied between attempts to run a transactional database operation.
static SynchronizedSessionRunner	startSession(Subspace lockSubspace, long leaseLengthMill, FDBDatabaseRunnerImpl runner)	Synchronous/blocking version of startSessionAsync(Subspace, long, FDBDatabaseRunnerImpl).
static CompletableFuture<SynchronizedSessionRunner>	startSessionAsync(Subspace lockSubspace, long leaseLengthMill, FDBDatabaseRunnerImpl runner)	Produces a new runner, wrapping a given runner, which performs all work in the context of a new SynchronizedSession.
SynchronizedSessionRunner	startSynchronizedSession(Subspace lockSubspace, long leaseLengthMillis)	Synchronous/blocking version of FDBDatabaseRunner.startSynchronizedSessionAsync(Subspace, long).
CompletableFuture<SynchronizedSessionRunner>	startSynchronizedSessionAsync(Subspace lockSubspace, long leaseLengthMillis)	Produces a new runner, wrapping this runner, which performs all work in the context of a new SynchronizedSession.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.apple.foundationdb.record.provider.foundationdb.FDBDatabaseRunner

getMdcContext, getPriority, getTimer, getTransactionTimeoutMillis, getWeakReadSemantics, run, runAsync, runAsync, setMdcContext, setPriority, setTimer, setTransactionTimeoutMillis, setWeakReadSemantics

Method Detail

startSessionAsync

public static CompletableFuture<SynchronizedSessionRunner> startSessionAsync(@Nonnull
                                                                             Subspace lockSubspace,
                                                                             long leaseLengthMill,
                                                                             @Nonnull
                                                                             FDBDatabaseRunnerImpl runner)

Produces a new runner, wrapping a given runner, which performs all work in the context of a new SynchronizedSession.

The returned runner will have acquired and started the lease, so care must be taken to ensure that work begins before the lease expiration period.

Parameters:

lockSubspace - the lock for which the session contends

leaseLengthMill - length between last access and lease's end time in milliseconds

runner - the underlying runner

Returns:

a future that will return a runner maintaining a new synchronized session

startSession

public static SynchronizedSessionRunner startSession(@Nonnull
                                                     Subspace lockSubspace,
                                                     long leaseLengthMill,
                                                     @Nonnull
                                                     FDBDatabaseRunnerImpl runner)

Synchronous/blocking version of startSessionAsync(Subspace, long, FDBDatabaseRunnerImpl).

Parameters:

lockSubspace - the lock for which the session contends

leaseLengthMill - length between last access and lease's end time in milliseconds

runner - the underlying runner

Returns:

a runner maintaining a new synchronized session

joinSession

public static SynchronizedSessionRunner joinSession(@Nonnull
                                                    Subspace lockSubspace,
                                                    @Nonnull
                                                    UUID sessionId,
                                                    long leaseLengthMill,
                                                    @Nonnull
                                                    FDBDatabaseRunnerImpl runner)

Produces a new runner, wrapping a given runner, which performs all work in the context of an existing SynchronizedSession.

Parameters:

lockSubspace - the lock for which the session contends

sessionId - session ID

leaseLengthMill - length between last access and lease's end time in milliseconds

runner - the underlying runner

Returns:

a runner maintaining a existing synchronized session

getSessionId

public UUID getSessionId()

endSessionAsync

public CompletableFuture<Void> endSessionAsync()

Releases the lock to end the synchronized session. It does nothing if the current session does not hold the lock. This should not necessarily be called when closing the runner because there can be multiple runners for the same session.

Returns:

a future that will return null when the session is ended

endSession

public void endSession()

Synchronous/blocking version of endSessionAsync().

endAnySessionAsync

public CompletableFuture<Void> endAnySessionAsync()

Releases the lock to end any synchronized session on the same lock subspace, no matter whether the current session holds the lock or not.

Returns:

a future that will return null when the session is ended

See Also:

SynchronizedSession.endAnySession(Transaction, Subspace)

endAnySession

public void endAnySession()

Synchronous/blocking version of endAnySessionAsync().

run

public <T> T run(@Nonnull
                 Function<? super FDBRecordContext,? extends T> retriable,
                 @Nullable
                 List<Object> additionalLogMessageKeyValues)

Description copied from interface: FDBDatabaseRunner

Runs a transactional function against with retry logic. This is a blocking call. See the appropriate overload of FDBDatabaseRunner.runAsync(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, java.util.concurrent.CompletableFuture<? extends T>>) for the non-blocking version of this method.

Specified by:

run in interface FDBDatabaseRunner

Type Parameters:

T - return type of function to run

Parameters:

retriable - the database operation to run transactionally

additionalLogMessageKeyValues - additional key/value pairs to be included in logs

Returns:

result of function after successful run and commit

See Also:

FDBDatabaseRunner.runAsync(Function)

runAsync

@Nonnull
public <T> CompletableFuture<T> runAsync(@Nonnull
                                         Function<? super FDBRecordContext,CompletableFuture<? extends T>> retriable,
                                         @Nonnull
                                         BiFunction<? super T,Throwable,? extends org.apache.commons.lang3.tuple.Pair<? extends T,? extends Throwable>> handlePostTransaction,
                                         @Nullable
                                         List<Object> additionalLogMessageKeyValues)

Description copied from interface: FDBDatabaseRunner

Runs a transactional function asynchronously with retry logic. This is also a non-blocking call.

Specified by:

runAsync in interface FDBDatabaseRunner

Type Parameters:

T - return type of function to run

Parameters:

retriable - the database operation to run transactionally

handlePostTransaction - after the transaction is committed, or fails to commit, this function is called with the result or exception respectively. This handler should return a new pair with either the result to return from runAsync or an exception to be checked whether retriable should be retried.

additionalLogMessageKeyValues - additional key/value pairs to be included in logs

Returns:

future that will contain the result of retriable after successful run and commit

See Also:

FDBDatabaseRunner.run(Function)

getDatabase

@Nonnull
public FDBDatabase getDatabase()

Description copied from interface: FDBDatabaseRunner

Get the database against which functions are run.

Specified by:

getDatabase in interface FDBDatabaseRunner

Returns:

the database used to run

getContextConfigBuilder

public FDBRecordContextConfig.Builder getContextConfigBuilder()

Description copied from interface: FDBDatabaseRunner

Get the configuration used in record contexts opened by this runner. Any changes made to the returned builder will be reflected in contexts opened by this runner.

Specified by:

getContextConfigBuilder in interface FDBDatabaseRunner

Returns:

configuration to use

setContextConfigBuilder

public void setContextConfigBuilder(FDBRecordContextConfig.Builder contextConfigBuilder)

Description copied from interface: FDBDatabaseRunner

Set the configuration used in record contexts opened by this runner.

Specified by:

setContextConfigBuilder in interface FDBDatabaseRunner

Parameters:

contextConfigBuilder - configuration to use

getExecutor

public Executor getExecutor()

Description copied from interface: FDBDatabaseRunner

Get the executor that will be used for FDBDatabaseRunner.runAsync(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, java.util.concurrent.CompletableFuture<? extends T>>).

Specified by:

getExecutor in interface FDBDatabaseRunner

Returns:

the executor to use

getMaxAttempts

public int getMaxAttempts()

Description copied from interface: FDBDatabaseRunner

Gets the maximum number of attempts for a database to make when running a retriable transactional operation. This is used by FDBDatabaseRunner.run(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, ? extends T>) and FDBDatabaseRunner.runAsync(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, java.util.concurrent.CompletableFuture<? extends T>>) to limit the number of attempts that an operation is retried.

Specified by:

getMaxAttempts in interface FDBDatabaseRunner

Returns:

the maximum number of times to run a transactional database operation

setMaxAttempts

public void setMaxAttempts(int maxAttempts)

Description copied from interface: FDBDatabaseRunner

Sets the maximum number of attempts for a database to make when running a retriable transactional operation. This is used by FDBDatabaseRunner.run(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, ? extends T>) and FDBDatabaseRunner.runAsync(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, java.util.concurrent.CompletableFuture<? extends T>>) to limit the number of attempts that an operation is retried.

Specified by:

setMaxAttempts in interface FDBDatabaseRunner

Parameters:

maxAttempts - the maximum number of times to run a transactional database operation

getMinDelayMillis

public long getMinDelayMillis()

Description copied from interface: FDBDatabaseRunner

Gets the minimum delay (in milliseconds) that will be applied between attempts to run a transactional database operation. This is used within FDBDatabaseRunner.run(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, ? extends T>) and FDBDatabaseRunner.runAsync(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, java.util.concurrent.CompletableFuture<? extends T>>) to limit the time spent between successive attempts at completing a database operation. Currently this value is fixed at 2 milliseconds and is not settable.

Specified by:

getMinDelayMillis in interface FDBDatabaseRunner

Returns:

the minimum delay between attempts when retrying operations

getMaxDelayMillis

public long getMaxDelayMillis()

Description copied from interface: FDBDatabaseRunner

Gets the maximum delay (in milliseconds) that will be applied between attempts to run a transactional database operation. This is used within FDBDatabaseRunner.run(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, ? extends T>) and FDBDatabaseRunner.runAsync(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, java.util.concurrent.CompletableFuture<? extends T>>) to limit the time spent between successive attempts at completing a database operation. The default value is 1000 so that there will not be more than 1 second between attempts.

Specified by:

getMaxDelayMillis in interface FDBDatabaseRunner

Returns:

the maximum delay between attempts when retrying operations

setMaxDelayMillis

public void setMaxDelayMillis(long maxDelayMillis)

Description copied from interface: FDBDatabaseRunner

Sets the maximum delay (in milliseconds) that will be applied between attempts to run a transactional database operation. This is used within FDBDatabaseRunner.run(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, ? extends T>) and FDBDatabaseRunner.runAsync(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, java.util.concurrent.CompletableFuture<? extends T>>) to limit the time spent between successive attempts at completing a database operation. The default value is 1000 so that there will not be more than 1 second between attempts.

Specified by:

setMaxDelayMillis in interface FDBDatabaseRunner

Parameters:

maxDelayMillis - the maximum delay between attempts when retrying operations

getInitialDelayMillis

public long getInitialDelayMillis()

Description copied from interface: FDBDatabaseRunner

Gets the delay ceiling (in milliseconds) that will be applied between attempts to run a transactional database operation. This is used within FDBDatabaseRunner.run(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, ? extends T>) and FDBDatabaseRunner.runAsync(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, java.util.concurrent.CompletableFuture<? extends T>>) to determine how long to wait between the first and second attempts at running a database operation. The exponential backoff algorithm will choose an amount of time to wait between zero and the initial delay, and will use that value each successive iteration to determine how long that wait should be. The default value is 10 milliseconds.

Specified by:

getInitialDelayMillis in interface FDBDatabaseRunner

Returns:

the delay ceiling between the first and second attempts at running a database operation

setInitialDelayMillis

public void setInitialDelayMillis(long initialDelayMillis)

Description copied from interface: FDBDatabaseRunner

Sets the delay ceiling (in milliseconds) that will be applied between attempts to run a transactional database operation. This is used within FDBDatabaseRunner.run(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, ? extends T>) and FDBDatabaseRunner.runAsync(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, java.util.concurrent.CompletableFuture<? extends T>>) to determine how long to wait between the first and second attempts at running a database operation. The exponential backoff algorithm will choose an amount of time to wait between zero and the initial delay, and will use that value each successive iteration to determine how long that wait should be. The default value is 10 milliseconds.

Specified by:

setInitialDelayMillis in interface FDBDatabaseRunner

Parameters:

initialDelayMillis - the delay ceiling between the first and second attempts at running a database operation

openContext

@Nonnull
public FDBRecordContext openContext()

Description copied from interface: FDBDatabaseRunner

Open a new record context.

Specified by:

openContext in interface FDBDatabaseRunner

Returns:

a new open record context

See Also:

FDBDatabase.openContext(Map,FDBStoreTimer,FDBDatabase.WeakReadSemantics)

asyncToSync

@Nullable
public <T> T asyncToSync(StoreTimer.Wait event,
                         @Nonnull
                         CompletableFuture<T> async)

Specified by:

asyncToSync in interface FDBDatabaseRunner

close

public void close()

Description copied from interface: FDBDatabaseRunner

Close this runner.

• Disallows starting more transactions
• Closes already open transactions
• Cancels futures returned by runAsync

Specified by:

close in interface AutoCloseable

Specified by:

close in interface FDBDatabaseRunner

startSynchronizedSessionAsync

public CompletableFuture<SynchronizedSessionRunner> startSynchronizedSessionAsync(@Nonnull
                                                                                  Subspace lockSubspace,
                                                                                  long leaseLengthMillis)

Description copied from interface: FDBDatabaseRunner

Produces a new runner, wrapping this runner, which performs all work in the context of a new SynchronizedSession.

The returned runner will have acquired and started the lease, so care must be taken to ensure that work begins before the lease expiration period.

Specified by:

startSynchronizedSessionAsync in interface FDBDatabaseRunner

Parameters:

lockSubspace - the lock for which the session contends

leaseLengthMillis - length between last access and lease's end time in milliseconds

Returns:

a future that will return a runner maintaining a new synchronized session

See Also:

SynchronizedSession

startSynchronizedSession

public SynchronizedSessionRunner startSynchronizedSession(@Nonnull
                                                          Subspace lockSubspace,
                                                          long leaseLengthMillis)

Description copied from interface: FDBDatabaseRunner

Synchronous/blocking version of FDBDatabaseRunner.startSynchronizedSessionAsync(Subspace, long).

Specified by:

startSynchronizedSession in interface FDBDatabaseRunner

Parameters:

lockSubspace - the lock for which the session contends

leaseLengthMillis - length between last access and lease's end time in milliseconds

Returns:

a runner maintaining a new synchronized session

joinSynchronizedSession

public SynchronizedSessionRunner joinSynchronizedSession(@Nonnull
                                                         Subspace lockSubspace,
                                                         @Nonnull
                                                         UUID sessionId,
                                                         long leaseLengthMillis)

Description copied from interface: FDBDatabaseRunner

Produces a new runner, wrapping this runner, which performs all work in the context of an existing SynchronizedSession.

Specified by:

joinSynchronizedSession in interface FDBDatabaseRunner

Parameters:

lockSubspace - the lock for which the session contends

sessionId - session ID

leaseLengthMillis - length between last access and lease's end time in milliseconds

Returns:

a runner maintaining a existing synchronized session

See Also:

SynchronizedSession