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

Interface FDBDatabaseRunner

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

FDBDatabaseRunnerImpl, SynchronizedSessionRunner

@API(MAINTAINED)
public interface FDBDatabaseRunner
extends AutoCloseable

A context for running against an FDBDatabase with retrying of transient exceptions.

Implements run(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, ? extends T>) and runAsync(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, java.util.concurrent.CompletableFuture<? extends T>>) methods for executing functions in a new FDBRecordContext and returning their result.

Implements close() in such a way that runAsync will not accidentally do more work afterwards. In particular, in the case of timeouts and transaction retries, it is otherwise possible for a whole new transaction to start at some time in the future and change the database even after the caller has given up, due to a timeout, for example.

 try (FDBDatabaseRunner runner = fdb.newRunner()) {
     CompleteableFuture<Void< future = runner.runAsync(context -> ...);
     fdb.asyncToSync(timer, WAIT_XXX, future);
 }
 

See Also:

FDBDatabase

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	FDBDatabaseRunner.RunnerClosed	Exception thrown when FDBDatabaseRunner has been closed but tries to do work.

Method Summary

Modifier and Type	Method	Description
<T> T	asyncToSync(StoreTimer.Wait event, CompletableFuture<T> async)
void	close()	Close this runner.
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 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.
default Map<String,String>	getMdcContext()	Get the logging context used in record contexts opened by this runner.
long	getMinDelayMillis()	Gets the minimum delay (in milliseconds) that will be applied between attempts to run a transactional database operation.
default FDBTransactionPriority	getPriority()	Get the priority of transactions opened by this runner.
default FDBStoreTimer	getTimer()	Get the timer used in record contexts opened by this runner.
default long	getTransactionTimeoutMillis()	Get the transaction timeout for all transactions started by this runner.
default FDBDatabase.WeakReadSemantics	getWeakReadSemantics()	Get the read semantics used in record contexts opened by this runner.
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.
default <T> T	run(Function<? super FDBRecordContext,? extends T> retriable)	Runs a transactional function against with retry logic.
<T> T	run(Function<? super FDBRecordContext,? extends T> retriable, List<Object> additionalLogMessageKeyValues)	Runs a transactional function against with retry logic.
default <T> CompletableFuture<T>	runAsync(Function<? super FDBRecordContext,CompletableFuture<? extends T>> retriable)	Runs a transactional function asynchronously with retry logic.
default <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)	Runs a transactional function asynchronously 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.
default void	setMdcContext(Map<String,String> mdcContext)	Set the logging context used in record contexts opened by this runner.
default void	setPriority(FDBTransactionPriority priority)	Set the priority of transactions opened by this runner.
default void	setTimer(FDBStoreTimer timer)	Set the timer used in record contexts opened by this runner.
default void	setTransactionTimeoutMillis(long transactionTimeoutMillis)	Set the transaction timeout for all transactions started by this runner.
default void	setWeakReadSemantics(FDBDatabase.WeakReadSemantics weakReadSemantics)	Set the read semantics used in record contexts opened by this runner.
SynchronizedSessionRunner	startSynchronizedSession(Subspace lockSubspace, long leaseLengthMillis)	Synchronous/blocking version of 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.

Method Detail

getDatabase

@Nonnull
FDBDatabase getDatabase()

Get the database against which functions are run.

Returns:

the database used to run

getContextConfigBuilder

@Nonnull
FDBRecordContextConfig.Builder getContextConfigBuilder()

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.

Returns:

configuration to use

setContextConfigBuilder

void setContextConfigBuilder(FDBRecordContextConfig.Builder contextConfigBuilder)

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

Parameters:

contextConfigBuilder - configuration to use

getExecutor

Executor getExecutor()

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

Returns:

the executor to use

getTimer

@Nullable
default FDBStoreTimer getTimer()

Get the timer used in record contexts opened by this runner.

Returns:

timer to use

setTimer

default void setTimer(@Nullable
                      FDBStoreTimer timer)

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

Parameters:

timer - timer to use

See Also:

FDBDatabase.openContext(Map,FDBStoreTimer)

getMdcContext

@Nullable
default Map<String,String> getMdcContext()

Get the logging context used in record contexts opened by this runner.

Returns:

the logging context to use

setMdcContext

default void setMdcContext(@Nullable
                           Map<String,String> mdcContext)

Set the logging context used in record contexts opened by this runner. This will change the executor to be one that restores this new mdcContext.

Parameters:

mdcContext - the logging context to use

See Also:

FDBDatabase.openContext(Map,FDBStoreTimer)

getWeakReadSemantics

@Nullable
default FDBDatabase.WeakReadSemantics getWeakReadSemantics()

Get the read semantics used in record contexts opened by this runner.

Returns:

allowable staleness parameters if caching read versions

setWeakReadSemantics

default void setWeakReadSemantics(@Nullable
                                  FDBDatabase.WeakReadSemantics weakReadSemantics)

Set the read semantics used in record contexts opened by this runner. Within the retry loops run(Function), runAsync(Function), and their variants, only the first context (from the first iteration round the loop) actually sets the created record context's FDBDatabase.WeakReadSemantics to the provided value. This is because there are several reasons why a transaction may fail due to a stale read version (for example, a conflict or expired transaction), and subsequent attempts will fail if their read version is not updated to a newer value.

Parameters:

weakReadSemantics - allowable staleness parameters if caching read versions

See Also:

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

getPriority

@Nonnull
default FDBTransactionPriority getPriority()

Get the priority of transactions opened by this runner.

Returns:

the priority of transactions opened by this runner

See Also:

FDBRecordContext.getPriority()

setPriority

default void setPriority(@Nonnull
                         FDBTransactionPriority priority)

Set the priority of transactions opened by this runner.

Parameters:

priority - the priority of transactions by this runner

See Also:

FDBRecordContext.getPriority()

getTransactionTimeoutMillis

default long getTransactionTimeoutMillis()

Get the transaction timeout for all transactions started by this runner. This will return the value configured for this runner through setTransactionTimeoutMillis(long). Note, however, that if the transaction timeout is set to FDBDatabaseFactory.DEFAULT_TR_TIMEOUT_MILLIS, then the actual timeout set for this transaction will be set to the value in the originating factory.

Returns:

the configured transacation timeout time in milliseconds

See Also:

setTransactionTimeoutMillis(long)

setTransactionTimeoutMillis

default void setTransactionTimeoutMillis(long transactionTimeoutMillis)

Set the transaction timeout for all transactions started by this runner. If set to FDBDatabaseFactory.DEFAULT_TR_TIMEOUT_MILLIS, then this will use the value as set in the originating database's factory. If set to FDBDatabaseFactory.UNLIMITED_TR_TIMEOUT_MILLIS, then no timeout will be imposed on transactions used by this runner.

Note that the error that the transaction hits, FDBExceptions.FDBStoreTransactionTimeoutException, is not retriable, so if the runner encounters such an error, it will terminate.

Parameters:

transactionTimeoutMillis - the transaction timeout time in milliseconds

See Also:

FDBDatabaseFactory.setTransactionTimeoutMillis(long)

getMaxAttempts

int getMaxAttempts()

Gets the maximum number of attempts for a database to make when running a retriable transactional operation. This is used by run(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, ? extends T>) and 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.

Returns:

the maximum number of times to run a transactional database operation

setMaxAttempts

void setMaxAttempts(int maxAttempts)

Sets the maximum number of attempts for a database to make when running a retriable transactional operation. This is used by run(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, ? extends T>) and 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.

Parameters:

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

Throws:

IllegalArgumentException - if a non-positive number is given

getMinDelayMillis

long getMinDelayMillis()

Gets the minimum delay (in milliseconds) that will be applied between attempts to run a transactional database operation. This is used within run(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, ? extends T>) and 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.

Returns:

the minimum delay between attempts when retrying operations

getMaxDelayMillis

long getMaxDelayMillis()

Gets the maximum delay (in milliseconds) that will be applied between attempts to run a transactional database operation. This is used within run(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, ? extends T>) and 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.

Returns:

the maximum delay between attempts when retrying operations

setMaxDelayMillis

void setMaxDelayMillis(long maxDelayMillis)

Sets the maximum delay (in milliseconds) that will be applied between attempts to run a transactional database operation. This is used within run(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, ? extends T>) and 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.

Parameters:

maxDelayMillis - the maximum delay between attempts when retrying operations

Throws:

IllegalArgumentException - if the value is negative or less than the minimum delay

getInitialDelayMillis

long getInitialDelayMillis()

Gets the delay ceiling (in milliseconds) that will be applied between attempts to run a transactional database operation. This is used within run(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, ? extends T>) and 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.

Returns:

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

setInitialDelayMillis

void setInitialDelayMillis(long initialDelayMillis)

Sets the delay ceiling (in milliseconds) that will be applied between attempts to run a transactional database operation. This is used within run(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, ? extends T>) and 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.

Parameters:

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

Throws:

IllegalArgumentException - if the value is negative or greater than the maximum delay

openContext

@Nonnull
FDBRecordContext openContext()

Open a new record context.

Returns:

a new open record context

See Also:

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

run

default <T> T run(@Nonnull
                  Function<? super FDBRecordContext,? extends T> retriable)

Runs a transactional function against with retry logic. This is a blocking call. See the appropriate overload of 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.

Type Parameters:

T - return type of function to run

Parameters:

retriable - the database operation to run transactionally

Returns:

result of function after successful run and commit

See Also:

runAsync(Function)

run

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

Runs a transactional function against with retry logic. This is a blocking call. See the appropriate overload of 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.

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:

runAsync(Function)

runAsync

@Nonnull
default <T> CompletableFuture<T> runAsync(@Nonnull
                                          Function<? super FDBRecordContext,CompletableFuture<? extends T>> retriable)

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

Type Parameters:

T - return type of function to run

Parameters:

retriable - the database operation to run transactionally

Returns:

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

See Also:

run(Function)

runAsync

@Nonnull
default <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)

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

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.

Returns:

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

See Also:

run(Function)

runAsync

@Nonnull
@API(EXPERIMENTAL)
<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)

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

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:

run(Function)

asyncToSync

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

close

void close()

Close this runner.

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

Specified by:

close in interface AutoCloseable

startSynchronizedSessionAsync

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

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.

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

@API(EXPERIMENTAL)
SynchronizedSessionRunner startSynchronizedSession(@Nonnull
                                                   Subspace lockSubspace,
                                                   long leaseLengthMillis)

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

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

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

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

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