com.apple.foundationdb.record.provider.foundationdb

Class FDBDatabase

java.lang.Object

com.apple.foundationdb.record.provider.foundationdb.FDBDatabase

@API(value=STABLE)
public class FDBDatabase
extends Object

A known FDB Database, associated with a cluster file location.

All reads and writes to the database are transactional: an open FDBRecordContext is needed. An FDBDatabase is needed to open an FDBRecordContext.

 final FDBDatabase fdb = FDBDatabaseFactory.instance().getDatabase();
 try (FDBRecordContext ctx = fdb.openContext()) {
     ...
 }
 

See Also:

FDBDatabaseFactory

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	FDBDatabase.ExceptionMapper Function for mapping an underlying exception to a synchronous failure.
static class	FDBDatabase.WeakReadSemantics 1.

Field Summary

Fields

Modifier and Type	Field and Description
protected static String	BLOCKING_FOR_FUTURE_MESSAGE Message that is logged when one joins on a future and expects it to be completed, but it is not yet done.
protected static String	BLOCKING_IN_ASYNC_CONTEXT_MESSAGE Text of message that is logged or exception that is thrown when a blocking API call (asyncToSync(), join(CompletableFuture), or get(CompletableFuture)) is called from within a CompletableFuture completion state.
protected static String	BLOCKING_RETURNING_ASYNC_MESSAGE Message that is logged when it is detected that a blocking call is being made in a method that may be producing a future (specifically a method that ends in "Async").
static int	DEFAULT_MAX_REVERSE_CACHE_ENTRIES
static int	DEFAULT_RESOLVER_STATE_CACHE_REFRESH_SECONDS

Constructor Summary

Constructors

Constructor and Description
FDBDatabase(FDBDatabaseFactory factory, String clusterFile)

Method Summary

Modifier and Type	Method and Description
<T> T	asyncToSync(FDBStoreTimer timer, StoreTimer.Wait event, CompletableFuture<T> async)
void	clearAsyncToSyncTimeout()
void	clearCaches()
void	clearForwardDirectoryCache()
void	clearReverseDirectoryCache()
void	close()
Transaction	createTransaction(Executor executor, Map<String,String> mdcContext, boolean transactionIsTraced)
Database	database() Get the underlying FDB database.
<T> T	get(CompletableFuture<T> future) Get a future, following the same logic that asyncToSync() uses to validate that the operation isn't blocking in an asynchronous context.
Function<StoreTimer.Wait,org.apache.commons.lang3.tuple.Pair<Long,TimeUnit>>	getAsyncToSyncTimeout()
org.apache.commons.lang3.tuple.Pair<Long,TimeUnit>	getAsyncToSyncTimeout(StoreTimer.Wait event)
BlockingInAsyncDetection	getBlockingInAsyncDetection()
String	getClusterFile() Get the path to the cluster file that this database was created with.
String	getDatacenterId()
com.google.common.cache.Cache<ScopedValue<String>,ResolverResult>	getDirectoryCache(int atVersion)
com.google.common.cache.CacheStats	getDirectoryCacheStats()
int	getDirectoryCacheVersion()
Executor	getExecutor()
protected FDBDatabaseFactory	getFactory() Get the factory that produced this database.
FDBLocalityProvider	getLocalityProvider() Get the locality provider that is used to discover the server location of the keys.
CompletableFuture<Long>	getReadVersion(FDBRecordContext context) Get the read version (GRV) for the given context.
long	getResolverStateCacheRefreshTime()
FDBReverseDirectoryCache	getReverseDirectoryCache()
com.google.common.cache.Cache<ScopedValue<Long>,String>	getReverseDirectoryInMemoryCache()
CompletableFuture<ResolverStateProto.State>	getStateForResolver(LocatableResolver resolver, Supplier<CompletableFuture<ResolverStateProto.State>> loader)
FDBRecordStoreStateCache	getStoreStateCache() Get the store state cache for this database.
boolean	hasAsyncToSyncTimeout()
protected CompletableFuture<Void>	injectLatency(FDBLatencySource fdbLatencySource) Given a specific FDB API call, a future is returned that is delayed by the number of milliseconds that was computed by the installed latency injector (FDBDatabaseFactory.setLatencyInjector(Function)).
boolean	isTrackLastSeenVersion()
boolean	isTrackLastSeenVersionOnCommit()
boolean	isTrackLastSeenVersionOnRead()
<T> T	join(CompletableFuture<T> future) Join a future, following the same logic that asyncToSync() uses to validate that the operation isn't blocking in an asynchronous context.
<T> T	joinNow(CompletableFuture<T> future) Join a future but validate that the future is already completed.
CompletableFuture<Tuple>	loadBoundaryKeys(FDBTransactionContext context, Tuple key)
protected RuntimeException	mapAsyncToSyncException(Throwable ex)
FDBDatabaseRunner	newRunner() Create an FDBDatabaseRunner for use against this database.
FDBDatabaseRunner	newRunner(FDBStoreTimer timer, Map<String,String> mdcContext) Create an FDBDatabaseRunner for use against this database.
FDBDatabaseRunner	newRunner(FDBStoreTimer timer, Map<String,String> mdcContext, FDBDatabase.WeakReadSemantics weakReadSemantics) Create an FDBDatabaseRunner for use against this database.
FDBRecordContext	openContext() Open a new record context with a new transaction begun on the underlying FDB database.
FDBRecordContext	openContext(Map<String,String> mdcContext, FDBStoreTimer timer) Open a new record context with a new transaction begun on the underlying FDB database.
FDBRecordContext	openContext(Map<String,String> mdcContext, FDBStoreTimer timer, FDBDatabase.WeakReadSemantics weakReadSemantics) Open a new record context with a new transaction begun on the underlying FDB database.
protected void	openFDB()
void	performNoOp() Perform a no-op against FDB to check network thread liveness.
void	performNoOp(FDBStoreTimer timer) Perform a no-op against FDB to check network thread liveness.
void	performNoOp(Map<String,String> mdcContext, FDBStoreTimer timer) Perform a no-op against FDB to check network thread liveness.
CompletableFuture<Void>	performNoOpAsync() Perform a no-op against FDB to check network thread liveness.
CompletableFuture<Void>	performNoOpAsync(FDBStoreTimer timer) Perform a no-op against FDB to check network thread liveness.
CompletableFuture<Void>	performNoOpAsync(Map<String,String> mdcContext, FDBStoreTimer timer) Perform a no-op against FDB to check network thread liveness.
<T> T	run(FDBStoreTimer timer, Map<String,String> mdcContext, FDBDatabase.WeakReadSemantics weakReadSemantics, Function<? super FDBRecordContext,? extends T> retriable) Runs a transactional function against this FDBDatabase with retry logic.
<T> T	run(FDBStoreTimer timer, Map<String,String> mdcContext, Function<? super FDBRecordContext,? extends T> retriable) Runs a transactional function against this FDBDatabase with retry logic.
<T> T	run(Function<? super FDBRecordContext,? extends T> retriable) Runs a transactional function against this FDBDatabase with retry logic.
<T> CompletableFuture<T>	runAsync(FDBStoreTimer timer, Map<String,String> mdcContext, FDBDatabase.WeakReadSemantics weakReadSemantics, Function<? super FDBRecordContext,CompletableFuture<? extends T>> retriable) Runs a transactional function asynchronously against this FDBDatabase with retry logic.
<T> CompletableFuture<T>	runAsync(FDBStoreTimer timer, Map<String,String> mdcContext, Function<? super FDBRecordContext,CompletableFuture<? extends T>> retriable) Runs a transactional function asynchronously against this FDBDatabase with retry logic.
<T> CompletableFuture<T>	runAsync(Function<? super FDBRecordContext,CompletableFuture<? extends T>> retriable) Runs a transactional function asynchronously against this FDBDatabase with retry logic.
void	setAsyncToSyncExceptionMapper(FDBDatabase.ExceptionMapper asyncToSyncExceptionMapper)
void	setAsyncToSyncTimeout(Function<StoreTimer.Wait,org.apache.commons.lang3.tuple.Pair<Long,TimeUnit>> asyncToSyncTimeout)
void	setAsyncToSyncTimeout(long asyncToSyncTimeout, TimeUnit asyncToSyncTimeoutUnit)
void	setDatacenterId(String datacenterId)
void	setDirectoryCacheSize(int size)
void	setResolverStateRefreshTimeMillis(long resolverStateRefreshTimeMillis)
void	setStoreStateCache(FDBRecordStoreStateCache storeStateCache) Set the store state cache for this database.
void	setTrackLastSeenVersion(boolean trackLastSeenVersion)
void	setTrackLastSeenVersionOnCommit(boolean trackLastSeenVersion)
void	setTrackLastSeenVersionOnRead(boolean trackLastSeenVersion)
void	updateLastSeenFDBVersion(long startTime, long readVersion)

Methods inherited from class java.lang.Object

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

Field Detail

BLOCKING_IN_ASYNC_CONTEXT_MESSAGE

protected static final String BLOCKING_IN_ASYNC_CONTEXT_MESSAGE

Text of message that is logged or exception that is thrown when a blocking API call (asyncToSync(), join(CompletableFuture), or get(CompletableFuture)) is called from within a CompletableFuture completion state.

See Also:

Constant Field Values

BLOCKING_RETURNING_ASYNC_MESSAGE

protected static final String BLOCKING_RETURNING_ASYNC_MESSAGE

Message that is logged when it is detected that a blocking call is being made in a method that may be producing a future (specifically a method that ends in "Async").

See Also:

Constant Field Values

BLOCKING_FOR_FUTURE_MESSAGE

protected static final String BLOCKING_FOR_FUTURE_MESSAGE

Message that is logged when one joins on a future and expects it to be completed, but it is not yet done.

See Also:

Constant Field Values

DEFAULT_MAX_REVERSE_CACHE_ENTRIES

public static final int DEFAULT_MAX_REVERSE_CACHE_ENTRIES

See Also:

Constant Field Values

DEFAULT_RESOLVER_STATE_CACHE_REFRESH_SECONDS

public static final int DEFAULT_RESOLVER_STATE_CACHE_REFRESH_SECONDS

See Also:

Constant Field Values

Constructor Detail

FDBDatabase

public FDBDatabase(@Nonnull
                   FDBDatabaseFactory factory,
                   @Nullable
                   String clusterFile)

Method Detail

openFDB

protected void openFDB()

setDirectoryCacheSize

public void setDirectoryCacheSize(int size)

setDatacenterId

public void setDatacenterId(String datacenterId)

getDatacenterId

public String getDatacenterId()

getLocalityProvider

@Nonnull
public FDBLocalityProvider getLocalityProvider()

Get the locality provider that is used to discover the server location of the keys.

Returns:

the locality provider

setTrackLastSeenVersionOnRead

public void setTrackLastSeenVersionOnRead(boolean trackLastSeenVersion)

isTrackLastSeenVersionOnRead

public boolean isTrackLastSeenVersionOnRead()

setTrackLastSeenVersionOnCommit

public void setTrackLastSeenVersionOnCommit(boolean trackLastSeenVersion)

isTrackLastSeenVersionOnCommit

public boolean isTrackLastSeenVersionOnCommit()

setTrackLastSeenVersion

public void setTrackLastSeenVersion(boolean trackLastSeenVersion)

isTrackLastSeenVersion

public boolean isTrackLastSeenVersion()

getClusterFile

@Nullable
public String getClusterFile()

Get the path to the cluster file that this database was created with. May return null if using the default cluster file.

Returns:

The path to the cluster file.

getFactory

@Nonnull
protected FDBDatabaseFactory getFactory()

Get the factory that produced this database.

Returns:

the database factory

database

@Nonnull
public Database database()

Get the underlying FDB database.

Returns:

the FDB database

openContext

@Nonnull
public FDBRecordContext openContext()

Open a new record context with a new transaction begun on the underlying FDB database.

Returns:

a new record context

See Also:

Database.createTransaction()

openContext

@Nonnull
public FDBRecordContext openContext(@Nullable
                                             Map<String,String> mdcContext,
                                             @Nullable
                                             FDBStoreTimer timer)

Open a new record context with a new transaction begun on the underlying FDB database.

Parameters:

mdcContext - logger context to set in running threads

timer - the timer to use for instrumentation

Returns:

a new record context

See Also:

Database.createTransaction()

openContext

@Nonnull
public FDBRecordContext openContext(@Nullable
                                             Map<String,String> mdcContext,
                                             @Nullable
                                             FDBStoreTimer timer,
                                             @Nullable
                                             FDBDatabase.WeakReadSemantics weakReadSemantics)

Open a new record context with a new transaction begun on the underlying FDB database.

Parameters:

mdcContext - logger context to set in running threads

timer - the timer to use for instrumentation

weakReadSemantics - allowable staleness information if caching read versions

Returns:

a new record context

See Also:

Database.createTransaction()

performNoOpAsync

@Nonnull
public CompletableFuture<Void> performNoOpAsync()

Perform a no-op against FDB to check network thread liveness. See performNoOp(Map, FDBStoreTimer) for more information. This will use the default MDC for running threads and will not instrument the operation.

Returns:

a future that will complete after being run by the FDB network thread

See Also:

performNoOp(Map, FDBStoreTimer)

performNoOpAsync

@Nonnull
public CompletableFuture<Void> performNoOpAsync(@Nullable
                                                         FDBStoreTimer timer)

Perform a no-op against FDB to check network thread liveness. See performNoOp(Map, FDBStoreTimer) for more information. This will use the default MDC for running threads.

Parameters:

timer - the timer to use for instrumentation

Returns:

a future that will complete after being run by the FDB network thread

See Also:

performNoOp(Map, FDBStoreTimer)

performNoOpAsync

@Nonnull
public CompletableFuture<Void> performNoOpAsync(@Nullable
                                                         Map<String,String> mdcContext,
                                                         @Nullable
                                                         FDBStoreTimer timer)

Perform a no-op against FDB to check network thread liveness. This operation will not change the underlying data in any way, nor will it perform any I/O against the FDB cluster. However, it will schedule some amount of work onto the FDB client and wait for it to complete. The FoundationDB client operates by scheduling onto an event queue that is then processed by a single thread (the "network thread"). This method can be used to determine if the network thread has entered a state where it is no longer processing requests or if its time to process requests has increased. If the network thread is busy, this operation may take some amount of time to complete, which is why this operation returns a future.

If the provided FDBStoreTimer is not null, then this will update the FDBStoreTimer.Events.PERFORM_NO_OP operation with related timing information. This can then be monitored to detect instances of client saturation where the performance bottleneck lies in scheduling work to run on the FDB event queue.

Parameters:

mdcContext - logger context to set in running threads

timer - the timer to use for instrumentation

Returns:

a future that will complete after being run by the FDB network thread

performNoOp

public void performNoOp()

Perform a no-op against FDB to check network thread liveness. This is a blocking version of performNoOpAsync(). Note that the future is expected to complete relatively quickly in most circumstances, but it may take a long time if the network thread has been saturated, e.g., if there is a lot of work being scheduled to run in FDB.

See Also:

performNoOpAsync()

performNoOp

public void performNoOp(@Nullable
                        FDBStoreTimer timer)

Perform a no-op against FDB to check network thread liveness. This is a blocking version of performNoOpAsync(FDBStoreTimer). Note that the future is expected to complete relatively quickly in most circumstances, but it may take a long time if the network thread has been saturated, e.g., if there is a lot of work being scheduled to run in FDB.

Parameters:

timer - the timer to use for instrumentation

See Also:

performNoOpAsync(FDBStoreTimer)

performNoOp

public void performNoOp(@Nullable
                        Map<String,String> mdcContext,
                        @Nullable
                        FDBStoreTimer timer)

Perform a no-op against FDB to check network thread liveness. This is a blocking version of performNoOpAsync(Map, FDBStoreTimer). Note that the future is expected to complete relatively quickly in most circumstances, but it may take a long time if the network thread has been saturated, e.g., if there is a lot of work being scheduled to run in FDB.

Parameters:

mdcContext - logger context to set in running threads

timer - the timer to use for instrumentation

See Also:

performNoOpAsync(Map, FDBStoreTimer)

getResolverStateCacheRefreshTime

public long getResolverStateCacheRefreshTime()

setResolverStateRefreshTimeMillis

public void setResolverStateRefreshTimeMillis(long resolverStateRefreshTimeMillis)

getStateForResolver

@Nonnull
 @API(value=INTERNAL)
public CompletableFuture<ResolverStateProto.State> getStateForResolver(@Nonnull
                                                                                                      LocatableResolver resolver,
                                                                                                      @Nonnull
                                                                                                      Supplier<CompletableFuture<ResolverStateProto.State>> loader)

getReadVersion

public CompletableFuture<Long> getReadVersion(@Nonnull
                                              FDBRecordContext context)

Get the read version (GRV) for the given context. An explicit get read version is no more expensive than the implicit one that every operation will entail. Measuring it explicitly gives an indication of the cluster's GRV latency, which is driven by its rate keeping.

Parameters:

context - transaction to use to access the database

Returns:

a future that will be completed with the read version of the current transaction

updateLastSeenFDBVersion

@API(value=INTERNAL)
public void updateLastSeenFDBVersion(long startTime,
                                                          long readVersion)

getReverseDirectoryCache

@Nonnull
 @API(value=INTERNAL)
public FDBReverseDirectoryCache getReverseDirectoryCache()

getDirectoryCacheVersion

@API(value=INTERNAL)
public int getDirectoryCacheVersion()

getDirectoryCacheStats

public com.google.common.cache.CacheStats getDirectoryCacheStats()

getDirectoryCache

@Nonnull
 @API(value=INTERNAL)
public com.google.common.cache.Cache<ScopedValue<String>,ResolverResult> getDirectoryCache(int atVersion)

getReverseDirectoryInMemoryCache

@Nonnull
 @API(value=INTERNAL)
public com.google.common.cache.Cache<ScopedValue<Long>,String> getReverseDirectoryInMemoryCache()

clearForwardDirectoryCache

@API(value=INTERNAL)
public void clearForwardDirectoryCache()

clearReverseDirectoryCache

@API(value=INTERNAL)
public void clearReverseDirectoryCache()

getStoreStateCache

@Nonnull
public FDBRecordStoreStateCache getStoreStateCache()

Get the store state cache for this database. This cache will be used when initializing record stores associated with this database.

Returns:

the store state cache for this database

See Also:

FDBRecordStoreStateCache

setStoreStateCache

public void setStoreStateCache(@Nonnull
                               FDBRecordStoreStateCache storeStateCache)

Set the store state cache for this database. The provided cache will be used when initializing record stores with this database. Note that the store state cache should not be set with a store state cache that is used by a different database.

Parameters:

storeStateCache - the store state cache

clearCaches

@API(value=INTERNAL)
public void clearCaches()

close

public void close()

getExecutor

@Nonnull
public Executor getExecutor()

createTransaction

public Transaction createTransaction(Executor executor,
                                     @Nullable
                                     Map<String,String> mdcContext,
                                     boolean transactionIsTraced)

newRunner

@Nonnull
public FDBDatabaseRunner newRunner()

Create an FDBDatabaseRunner for use against this database.

Returns:

a new runner

newRunner

@Nonnull
public FDBDatabaseRunner newRunner(@Nullable
                                            FDBStoreTimer timer,
                                            @Nullable
                                            Map<String,String> mdcContext)

Create an FDBDatabaseRunner for use against this database.

Parameters:

timer - the timer to use for instrumentation

mdcContext - logger context to set in running threads

Returns:

a new runner

newRunner

@Nonnull
public FDBDatabaseRunner newRunner(@Nullable
                                            FDBStoreTimer timer,
                                            @Nullable
                                            Map<String,String> mdcContext,
                                            @Nullable
                                            FDBDatabase.WeakReadSemantics weakReadSemantics)

Create an FDBDatabaseRunner for use against this database.

Parameters:

timer - the timer to use for instrumentation

mdcContext - logger context to set in running threads

weakReadSemantics - allowable staleness information if caching read versions

Returns:

a new runner

run

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

Runs a transactional function against this FDBDatabase with retry logic. This creates a new runner and closes it when complete. To better control the lifetime / sharing of the runner, create it separately.

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:

newRunner(), FDBDatabaseRunner.run(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, ? extends T>)

run

public <T> T run(@Nullable
                 FDBStoreTimer timer,
                 @Nullable
                 Map<String,String> mdcContext,
                 @Nonnull
                 Function<? super FDBRecordContext,? extends T> retriable)

Runs a transactional function against this FDBDatabase with retry logic. This creates a new runner and closes it when complete. To better control the lifetime / sharing of the runner, create it separately.

Type Parameters:

T - return type of function to run

Parameters:

timer - the timer to use for instrumentation

mdcContext - logger context to set in running threads

retriable - the database operation to run transactionally

Returns:

result of function after successful run and commit

See Also:

newRunner(FDBStoreTimer, Map), FDBDatabaseRunner.run(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, ? extends T>)

run

public <T> T run(@Nullable
                 FDBStoreTimer timer,
                 @Nullable
                 Map<String,String> mdcContext,
                 @Nullable
                 FDBDatabase.WeakReadSemantics weakReadSemantics,
                 @Nonnull
                 Function<? super FDBRecordContext,? extends T> retriable)

Runs a transactional function against this FDBDatabase with retry logic. This will run the function and commit the transaction associated with it until the function either completes successfully or encounters a non-retriable error. An error is considered retriable if it is a RecordCoreRetriableTransactionException, a retriable FDBException, or is an exception caused by a retriable error. The function will not be run more than the number of times specified by FDBDatabaseFactory.getMaxAttempts(). It also important that the function provided is idempotent as the function may be applied multiple times successfully if the transaction commit returns a commit_unknown_result error.

If this FDBDatabase is configured to cache read versions, one can specify that this function should use the cached version by supplying a non-null FDBDatabase.WeakReadSemantics object to the weakReadSemantics parameter. Each time that the function is retried, the cached read version is checked again, so each retry might get different read versions.

This is a blocking call, and this function will not return until the database has synchronously returned a response as to the success or failure of this operation. If one wishes to achieve the same functionality in a non-blocking manner, see runAsync().

This creates a new runner and closes it when complete. To better control the lifetime / sharing of the runner, create it separately.

Type Parameters:

T - return type of function to run

Parameters:

timer - the timer to use for instrumentation

mdcContext - logger context to set in running threads

weakReadSemantics - allowable staleness parameters if caching read versions

retriable - the database operation to run transactionally

Returns:

result of function after successful run and commit

See Also:

newRunner(FDBStoreTimer, Map, WeakReadSemantics), FDBDatabaseRunner.run(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, ? extends T>)

runAsync

@Nonnull
 @API(value=MAINTAINED)
public <T> CompletableFuture<T> runAsync(@Nonnull
                                                                          Function<? super FDBRecordContext,CompletableFuture<? extends T>> retriable)

Runs a transactional function asynchronously against this FDBDatabase with retry logic. This creates a new runner and closes it when complete. To better control the lifetime / sharing of the runner, create it separately.

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 function after successful run and commit

See Also:

newRunner(), FDBDatabaseRunner.runAsync(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, java.util.concurrent.CompletableFuture<? extends T>>)

runAsync

@Nonnull
 @API(value=MAINTAINED)
public <T> CompletableFuture<T> runAsync(@Nullable
                                                                          FDBStoreTimer timer,
                                                                          @Nullable
                                                                          Map<String,String> mdcContext,
                                                                          @Nonnull
                                                                          Function<? super FDBRecordContext,CompletableFuture<? extends T>> retriable)

Runs a transactional function asynchronously against this FDBDatabase with retry logic. This creates a new runner and closes it when complete. To better control the lifetime / sharing of the runner, create it separately.

Type Parameters:

T - return type of function to run

Parameters:

timer - the timer to use for instrumentation

mdcContext - logger context to set in running threads

retriable - the database operation to run transactionally

Returns:

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

See Also:

newRunner(FDBStoreTimer, Map), FDBDatabaseRunner.runAsync(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, java.util.concurrent.CompletableFuture<? extends T>>)

runAsync

@Nonnull
 @API(value=MAINTAINED)
public <T> CompletableFuture<T> runAsync(@Nullable
                                                                          FDBStoreTimer timer,
                                                                          @Nullable
                                                                          Map<String,String> mdcContext,
                                                                          @Nullable
                                                                          FDBDatabase.WeakReadSemantics weakReadSemantics,
                                                                          @Nonnull
                                                                          Function<? super FDBRecordContext,CompletableFuture<? extends T>> retriable)

Runs a transactional function asynchronously against this FDBDatabase with retry logic. This will run the function and commit the transaction associated with it until the function either completes successfully or encounters a non-retriable error. An error is considered retriable if it is a RecordCoreRetriableTransactionException, a retriable FDBException, or is an exception caused by a retriable error. The function will not be run more than the number of times specified by FDBDatabaseFactory.getMaxAttempts(). It also important that the function provided is idempotent as the function may be applied multiple times successfully if the transaction commit returns a commit_uknown_result error.

If this FDBDatabase is configured to cache read versions, one can specify that this function should use the cached version by supplying a non-null FDBDatabase.WeakReadSemantics object to the weakReadSemantics parameter. Each time that the function is retried, the cached read version is checked again, so each retry might get different read versions.

This is a non-blocking call, and this function will return immediately with a future that will not be ready until the database has returned a response as to the success or failure of this operation. If one wishes to achieve the same functionality in a blocking manner, see run().

This creates a new runner and closes it when complete. To better control the lifetime / sharing of the runner, create it separately.

Type Parameters:

T - return type of function to run

Parameters:

timer - the timer to use for instrumentation

mdcContext - logger context to set in running threads

weakReadSemantics - allowable staleness information if caching read versions

retriable - the database operation to run transactionally

Returns:

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

See Also:

newRunner(FDBStoreTimer, Map, WeakReadSemantics), FDBDatabaseRunner.runAsync(java.util.function.Function<? super com.apple.foundationdb.record.provider.foundationdb.FDBRecordContext, java.util.concurrent.CompletableFuture<? extends T>>)

hasAsyncToSyncTimeout

public boolean hasAsyncToSyncTimeout()

getAsyncToSyncTimeout

@Nullable
public org.apache.commons.lang3.tuple.Pair<Long,TimeUnit> getAsyncToSyncTimeout(StoreTimer.Wait event)

getAsyncToSyncTimeout

@Nullable
public Function<StoreTimer.Wait,org.apache.commons.lang3.tuple.Pair<Long,TimeUnit>> getAsyncToSyncTimeout()

setAsyncToSyncTimeout

public void setAsyncToSyncTimeout(@Nullable
                                  Function<StoreTimer.Wait,org.apache.commons.lang3.tuple.Pair<Long,TimeUnit>> asyncToSyncTimeout)

setAsyncToSyncTimeout

public void setAsyncToSyncTimeout(long asyncToSyncTimeout,
                                  @Nonnull
                                  TimeUnit asyncToSyncTimeoutUnit)

clearAsyncToSyncTimeout

public void clearAsyncToSyncTimeout()

setAsyncToSyncExceptionMapper

public void setAsyncToSyncExceptionMapper(@Nonnull
                                          FDBDatabase.ExceptionMapper asyncToSyncExceptionMapper)

mapAsyncToSyncException

protected RuntimeException mapAsyncToSyncException(@Nonnull
                                                   Throwable ex)

asyncToSync

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

join

public <T> T join(CompletableFuture<T> future)

Join a future, following the same logic that asyncToSync() uses to validate that the operation isn't blocking in an asynchronous context.

Type Parameters:

T - the type of the value produced by the future

Parameters:

future - the future to be completed

Returns:

the result value

joinNow

public <T> T joinNow(CompletableFuture<T> future)

Join a future but validate that the future is already completed. This can be used to unwrap a completed future while allowing for bugs caused by inadvertently waiting on incomplete futures to be caught. In particular, this will throw an exception if the BlockingInAsyncDetection behavior is set to throw an exception on incomplete futures and otherwise just log that future was waited on.

Type Parameters:

T - the type of the value produced by the future

Parameters:

future - the future that should already be completed

Returns:

the result value

get

public <T> T get(CompletableFuture<T> future)
          throws InterruptedException,
                 ExecutionException

Get a future, following the same logic that asyncToSync() uses to validate that the operation isn't blocking in an asynchronous context.

Type Parameters:

T - the type of the value produced by the future

Parameters:

future - the future to be completed

Returns:

the result value

Throws:

CancellationException - if the future was cancelled

ExecutionException - if the future completed exceptionally

InterruptedException - if the current thread was interrupted

getBlockingInAsyncDetection

@API(value=INTERNAL)
public BlockingInAsyncDetection getBlockingInAsyncDetection()

injectLatency

protected CompletableFuture<Void> injectLatency(FDBLatencySource fdbLatencySource)

Given a specific FDB API call, a future is returned that is delayed by the number of milliseconds that was computed by the installed latency injector (FDBDatabaseFactory.setLatencyInjector(Function)).

Parameters:

fdbLatencySource - the call for which the latency is to be computed

Returns:

a future that will be delayed by the configured injection millis

loadBoundaryKeys

public CompletableFuture<Tuple> loadBoundaryKeys(@Nonnull
                                                 FDBTransactionContext context,
                                                 Tuple key)