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

Class FDBDatabase

java.lang.Object

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

@API(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	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	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	Description
FDBDatabase(FDBDatabaseFactory factory, String clusterFile)

Method Summary

Modifier and Type	Method	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)	Deprecated. use openContext() instead
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.
protected long	getLatencyToInject(FDBLatencySource fdbLatencySource)	Given a specific FDB API call, computes an amount of latency (in milliseconds) that should be injected prior to performing the actual operation.
FDBLocalityProvider	getLocalityProvider()	Get the locality provider that is used to discover the server location of the keys.
CompletableFuture<Long>	getReadVersion(FDBRecordContext context)	Deprecated. use FDBRecordContext.getReadVersionAsync() instead
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()
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)
protected Executor	newContextExecutor(Map<String,String> mdcContext)
FDBDatabaseRunner	newRunner()	Create an FDBDatabaseRunner for use against this database.
FDBDatabaseRunner	newRunner(FDBRecordContextConfig.Builder contextConfigBuilder)	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(FDBRecordContextConfig contextConfig)	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.
FDBRecordContext	openContext(Map<String,String> mdcContext, FDBStoreTimer timer, FDBDatabase.WeakReadSemantics weakReadSemantics, FDBTransactionPriority priority)	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, FDBTransactionPriority priority, String transactionId)	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(long asyncToSyncTimeout, TimeUnit asyncToSyncTimeoutUnit)
void	setAsyncToSyncTimeout(Function<StoreTimer.Wait,org.apache.commons.lang3.tuple.Pair<Long,TimeUnit>> asyncToSyncTimeout)
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)
protected void	trackOpenContext(FDBRecordContext context)
protected void	untrackOpenContext(FDBRecordContext context)
void	updateLastSeenFDBVersion(long startTime, long readVersion)
int	warnAndCloseOldTrackedOpenContexts(long minAgeSeconds)	Log warning and close tracked contexts that have been open for too long.

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. Will return null if using the default cluster file. To get the resolved cluster file path for databases created with the default path, use FDBSystemOperations.getClusterFilePath(FDBDatabaseRunner) instead.

Returns:

The path to the cluster file.

See Also:

FDBSystemOperations.getClusterFilePath(FDBDatabaseRunner)

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.

If the logger context includes "uuid" as a key, the value associated with that key will be associated with the returned transaction as its debug identifier. See openContext(Map, FDBStoreTimer, WeakReadSemantics, FDBTransactionPriority, String) for more details.

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.

If the logger context includes "uuid" as a key, the value associated with that key will be associated with the returned transaction as its debug identifier. See openContext(Map, FDBStoreTimer, WeakReadSemantics, FDBTransactionPriority, String) for more details.

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()

openContext

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

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

If the logger context includes "uuid" as a key, the value associated with that key will be associated with the returned transaction as its debug identifier. See openContext(Map, FDBStoreTimer, WeakReadSemantics, FDBTransactionPriority, String) for more details.

Parameters:

mdcContext - logger context to set in running threads

timer - the timer to use for instrumentation

weakReadSemantics - allowable staleness information if caching read versions

priority - the priority of the transaction being created

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,
                                    @Nonnull
                                    FDBTransactionPriority priority,
                                    @Nullable
                                    String transactionId)

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

If the passed transactionId is null, then this method will set the transaction ID of the given transaction to the value of the "uuid" key in the MDC context if present. The transaction ID should typically consist solely of printable ASCII characters and should not exceed 100 bytes. The ID may be truncated or dropped if the ID will not fit in 100 bytes. See FDBRecordContext.getTransactionId() for more details.

Parameters:

mdcContext - logger context to set in running threads

timer - the timer to use for instrumentation

weakReadSemantics - allowable staleness information if caching read versions

priority - the priority of the transaction being created

transactionId - the transaction ID to associate with this transaction

Returns:

a new record context

See Also:

Database.createTransaction()

openContext

@Nonnull
public FDBRecordContext openContext(@Nonnull
                                    FDBRecordContextConfig contextConfig)

Open a new record context with a new transaction begun on the underlying FDB database. Various options on the transaction will be informed based on the passed context.

Parameters:

contextConfig - a configuration object specifying various options on the returned context

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(INTERNAL)
public CompletableFuture<ResolverStateProto.State> getStateForResolver(@Nonnull
                                                                       LocatableResolver resolver,
                                                                       @Nonnull
                                                                       Supplier<CompletableFuture<ResolverStateProto.State>> loader)

getReadVersion

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

Deprecated.

use FDBRecordContext.getReadVersionAsync() instead

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(INTERNAL)
public void updateLastSeenFDBVersion(long startTime,
                                     long readVersion)

getReverseDirectoryCache

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

getDirectoryCacheVersion

@API(INTERNAL)
public int getDirectoryCacheVersion()

getDirectoryCacheStats

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

getDirectoryCache

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

getReverseDirectoryInMemoryCache

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

clearForwardDirectoryCache

@API(INTERNAL)
public void clearForwardDirectoryCache()

clearReverseDirectoryCache

@API(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(INTERNAL)
public void clearCaches()

close

public void close()

getExecutor

@Nonnull
public Executor getExecutor()

newContextExecutor

protected Executor newContextExecutor(@Nullable
                                      Map<String,String> mdcContext)

createTransaction

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

Deprecated.

use openContext() instead

Creates a new transaction against the database.

Parameters:

executor - the executor to be used for asynchronous operations

mdcContext - if not [@code null} and tracing is enabled, information in the context will be included in tracing log messages

transactionIsTraced - unused

Returns:

newly created transaction

newRunner

@Nonnull
public FDBDatabaseRunner newRunner(@Nonnull
                                   FDBRecordContextConfig.Builder contextConfigBuilder)

Create an FDBDatabaseRunner for use against this database. Changes made to contextConfigBuilder subsequently will continue to be reflected in contexts opened by the runner.

Parameters:

contextConfigBuilder - options for contexts opened by the new runner

Returns:

a new runner

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(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(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(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

warnAndCloseOldTrackedOpenContexts

public int warnAndCloseOldTrackedOpenContexts(long minAgeSeconds)

Log warning and close tracked contexts that have been open for too long.

Parameters:

minAgeSeconds - number of seconds above which to warn

Returns:

number of such contexts found

trackOpenContext

protected void trackOpenContext(FDBRecordContext context)

untrackOpenContext

protected void untrackOpenContext(FDBRecordContext context)

getBlockingInAsyncDetection

@API(INTERNAL)
public BlockingInAsyncDetection getBlockingInAsyncDetection()

getLatencyToInject

protected long getLatencyToInject(FDBLatencySource fdbLatencySource)

Given a specific FDB API call, computes an amount of latency (in milliseconds) that should be injected prior to performing the actual operation. This latency is computed via an installed latency injector via FDBDatabaseFactory.setLatencyInjector(Function).

Parameters:

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

Returns:

the amount of delay, in milliseconds, to inject for the provided operation

loadBoundaryKeys

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