@API(value=MAINTAINED) public interface FDBDatabaseRunner extends AutoCloseable
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);
}
FDBDatabase
Modifier and Type | Interface and Description |
---|---|
static class |
FDBDatabaseRunner.RunnerClosed
Exception thrown when
FDBDatabaseRunner has been closed but tries to do work. |
Modifier and Type | Method and Description |
---|---|
<T> T |
asyncToSync(StoreTimer.Wait event,
CompletableFuture<T> async) |
void |
close()
Close this runner.
|
FDBDatabase |
getDatabase()
Get the database against which functions are run.
|
Executor |
getExecutor()
|
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.
|
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.
|
FDBTransactionPriority |
getPriority()
Get the priority of transactions opened by this runner.
|
FDBStoreTimer |
getTimer()
Get the timer used in record contexts opened by this runner.
|
long |
getTransactionTimeoutMillis()
Get the transaction timeout for all transactions started by this runner.
|
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 |
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.
|
void |
setMdcContext(Map<String,String> mdcContext)
Set the logging context used in record contexts opened by this runner.
|
void |
setPriority(FDBTransactionPriority priority)
Set the priority of transactions opened by this runner.
|
void |
setTimer(FDBStoreTimer timer)
Set the timer used in record contexts opened by this runner.
|
void |
setTransactionTimeoutMillis(long transactionTimeoutMillis)
Set the transaction timeout for all transactions started by this runner.
|
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 . |
@Nonnull FDBDatabase getDatabase()
Executor getExecutor()
runAsync(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, java.util.concurrent.CompletableFuture<? extends T>>)
.@Nullable FDBStoreTimer getTimer()
void setTimer(@Nullable FDBStoreTimer timer)
timer
- timer to useFDBDatabase.openContext(Map,FDBStoreTimer)
@Nullable Map<String,String> getMdcContext()
void setMdcContext(@Nullable Map<String,String> mdcContext)
mdcContext
.mdcContext
- the logging context to useFDBDatabase.openContext(Map,FDBStoreTimer)
@Nullable FDBDatabase.WeakReadSemantics getWeakReadSemantics()
void setWeakReadSemantics(@Nullable FDBDatabase.WeakReadSemantics weakReadSemantics)
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.weakReadSemantics
- allowable staleness parameters if caching read versionsFDBDatabase.openContext(Map,FDBStoreTimer,FDBDatabase.WeakReadSemantics)
@Nonnull FDBTransactionPriority getPriority()
FDBRecordContext.getPriority()
void setPriority(@Nonnull FDBTransactionPriority priority)
priority
- the priority of transactions by this runnerFDBRecordContext.getPriority()
int getMaxAttempts()
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.void setMaxAttempts(int maxAttempts)
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.maxAttempts
- the maximum number of times to run a transactional database operationIllegalArgumentException
- if a non-positive number is givenlong getMinDelayMillis()
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.long getMaxDelayMillis()
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.void setMaxDelayMillis(long maxDelayMillis)
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.maxDelayMillis
- the maximum delay between attempts when retrying operationsIllegalArgumentException
- if the value is negative or less than the minimum delaylong getInitialDelayMillis()
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.void setInitialDelayMillis(long initialDelayMillis)
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.initialDelayMillis
- the delay ceiling between the first and second attempts at running a database operationIllegalArgumentException
- if the value is negative or greater than the maximum delayvoid setTransactionTimeoutMillis(long transactionTimeoutMillis)
FDBDatabaseFactory.DEFAULT_TR_TIMEOUT_MILLIS
,
then this will use the value of 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.
transactionTimeoutMillis
- the transaction timeout time in millisecondsFDBDatabaseFactory.setTransactionTimeoutMillis(long)
long getTransactionTimeoutMillis()
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.setTransactionTimeoutMillis(long)
@Nonnull FDBRecordContext openContext()
FDBDatabase.openContext(Map,FDBStoreTimer,FDBDatabase.WeakReadSemantics)
default <T> T run(@Nonnull Function<? super FDBRecordContext,? extends T> retriable)
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.T
- return type of function to runretriable
- the database operation to run transactionallyrunAsync(Function)
@API(value=EXPERIMENTAL) <T> T run(@Nonnull Function<? super FDBRecordContext,? extends T> retriable, @Nullable List<Object> additionalLogMessageKeyValues)
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.T
- return type of function to runretriable
- the database operation to run transactionallyadditionalLogMessageKeyValues
- additional key/value pairs to be included in logsrunAsync(Function)
@Nonnull default <T> CompletableFuture<T> runAsync(@Nonnull Function<? super FDBRecordContext,CompletableFuture<? extends T>> retriable)
run(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, ? extends T>)
for the blocking version of this method.T
- return type of function to runretriable
- the database operation to run transactionallyretriable
after successful run and commitrun(Function)
@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)
T
- return type of function to runretriable
- the database operation to run transactionallyhandlePostTransaction
- 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.retriable
after successful run and commitrun(Function)
@Nonnull @API(value=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)
T
- return type of function to runretriable
- the database operation to run transactionallyhandlePostTransaction
- 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 logsretriable
after successful run and commitrun(Function)
@Nullable <T> T asyncToSync(StoreTimer.Wait event, @Nonnull CompletableFuture<T> async)
void close()
runAsync
close
in interface AutoCloseable
@API(value=EXPERIMENTAL) CompletableFuture<SynchronizedSessionRunner> startSynchronizedSessionAsync(@Nonnull Subspace lockSubspace, long leaseLengthMillis)
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.
lockSubspace
- the lock for which the session contendsleaseLengthMillis
- length between last access and lease's end time in millisecondsSynchronizedSession
@API(value=EXPERIMENTAL) SynchronizedSessionRunner startSynchronizedSession(@Nonnull Subspace lockSubspace, long leaseLengthMillis)
startSynchronizedSessionAsync(Subspace, long)
.lockSubspace
- the lock for which the session contendsleaseLengthMillis
- length between last access and lease's end time in milliseconds@API(value=EXPERIMENTAL) SynchronizedSessionRunner joinSynchronizedSession(@Nonnull Subspace lockSubspace, @Nonnull UUID sessionId, long leaseLengthMillis)
SynchronizedSession
.lockSubspace
- the lock for which the session contendssessionId
- session IDleaseLengthMillis
- length between last access and lease's end time in millisecondsSynchronizedSession