Class FDBDatabase
- java.lang.Object
-
- com.apple.foundationdb.record.provider.foundationdb.FDBDatabase
-
@API(STABLE) public class FDBDatabase extends Object
A known FDBDatabase
, associated with a cluster file location.All reads and writes to the database are transactional: an open
FDBRecordContext
is needed. AnFDBDatabase
is needed to open anFDBRecordContext
.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)
, orget(CompletableFuture)
) is called from within aCompletableFuture
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
All Methods Instance Methods Concrete Methods Deprecated Methods 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.useopenContext()
insteadDatabase
database()
Get the underlying FDB database.<T> T
get(CompletableFuture<T> future)
Get a future, following the same logic thatasyncToSync()
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.useFDBRecordContext.getReadVersionAsync()
insteadlong
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 thatasyncToSync()
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 anFDBDatabaseRunner
for use against this database.FDBDatabaseRunner
newRunner(FDBRecordContextConfig.Builder contextConfigBuilder)
Create anFDBDatabaseRunner
for use against this database.FDBDatabaseRunner
newRunner(FDBStoreTimer timer, Map<String,String> mdcContext)
Create anFDBDatabaseRunner
for use against this database.FDBDatabaseRunner
newRunner(FDBStoreTimer timer, Map<String,String> mdcContext, FDBDatabase.WeakReadSemantics weakReadSemantics)
Create anFDBDatabaseRunner
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 thisFDBDatabase
with retry logic.<T> T
run(FDBStoreTimer timer, Map<String,String> mdcContext, Function<? super FDBRecordContext,? extends T> retriable)
Runs a transactional function against thisFDBDatabase
with retry logic.<T> T
run(Function<? super FDBRecordContext,? extends T> retriable)
Runs a transactional function against thisFDBDatabase
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 thisFDBDatabase
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 thisFDBDatabase
with retry logic.<T> CompletableFuture<T>
runAsync(Function<? super FDBRecordContext,CompletableFuture<? extends T>> retriable)
Runs a transactional function asynchronously against thisFDBDatabase
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.
-
-
-
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)
, orget(CompletableFuture)
) is called from within aCompletableFuture
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 returnnull
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.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 threadstimer
- 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 threadstimer
- the timer to use for instrumentationweakReadSemantics
- 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 threadstimer
- the timer to use for instrumentationweakReadSemantics
- allowable staleness information if caching read versionspriority
- 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
isnull
, 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. SeeFDBRecordContext.getTransactionId()
for more details.- Parameters:
mdcContext
- logger context to set in running threadstimer
- the timer to use for instrumentationweakReadSemantics
- allowable staleness information if caching read versionspriority
- the priority of the transaction being createdtransactionId
- 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. SeeperformNoOp(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. SeeperformNoOp(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 notnull
, then this will update theFDBStoreTimer.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 threadstimer
- 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 ofperformNoOpAsync()
. 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 ofperformNoOpAsync(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 ofperformNoOpAsync(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 threadstimer
- 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.useFDBRecordContext.getReadVersionAsync()
insteadGet 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()
-
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()
-
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
-
close
public void close()
-
createTransaction
@Deprecated @API(DEPRECATED) public Transaction createTransaction(Executor executor, @Nullable Map<String,String> mdcContext, boolean transactionIsTraced)
Deprecated.useopenContext()
insteadCreates a new transaction against the database.- Parameters:
executor
- the executor to be used for asynchronous operationsmdcContext
- if not [@code null} and tracing is enabled, information in the context will be included in tracing log messagestransactionIsTraced
- unused- Returns:
- newly created transaction
-
newRunner
@Nonnull public FDBDatabaseRunner newRunner(@Nonnull FDBRecordContextConfig.Builder contextConfigBuilder)
Create anFDBDatabaseRunner
for use against this database. Changes made tocontextConfigBuilder
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 anFDBDatabaseRunner
for use against this database.- Returns:
- a new runner
-
newRunner
@Nonnull public FDBDatabaseRunner newRunner(@Nullable FDBStoreTimer timer, @Nullable Map<String,String> mdcContext)
Create anFDBDatabaseRunner
for use against this database.- Parameters:
timer
- the timer to use for instrumentationmdcContext
- 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 anFDBDatabaseRunner
for use against this database.- Parameters:
timer
- the timer to use for instrumentationmdcContext
- logger context to set in running threadsweakReadSemantics
- 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 thisFDBDatabase
with retry logic. This creates a newrunner
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 thisFDBDatabase
with retry logic. This creates a newrunner
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 instrumentationmdcContext
- logger context to set in running threadsretriable
- 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 thisFDBDatabase
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 aRecordCoreRetriableTransactionException
, a retriableFDBException
, or is an exception caused by a retriable error. The function will not be run more than the number of times specified byFDBDatabaseFactory.getMaxAttempts()
. It also important that the function provided is idempotent as the function may be applied multiple times successfully if the transaction commit returns acommit_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 theweakReadSemantics
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
This creates a newrunAsync()
.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 instrumentationmdcContext
- logger context to set in running threadsweakReadSemantics
- allowable staleness parameters if caching read versionsretriable
- 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 thisFDBDatabase
with retry logic. This creates a newrunner
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 thisFDBDatabase
with retry logic. This creates a newrunner
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 instrumentationmdcContext
- logger context to set in running threadsretriable
- 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 thisFDBDatabase
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 aRecordCoreRetriableTransactionException
, a retriableFDBException
, or is an exception caused by a retriable error. The function will not be run more than the number of times specified byFDBDatabaseFactory.getMaxAttempts()
. It also important that the function provided is idempotent as the function may be applied multiple times successfully if the transaction commit returns acommit_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 theweakReadSemantics
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
This creates a newrun()
.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 instrumentationmdcContext
- logger context to set in running threadsweakReadSemantics
- allowable staleness information if caching read versionsretriable
- 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 thatasyncToSync()
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 theBlockingInAsyncDetection
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 thatasyncToSync()
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 cancelledExecutionException
- if the future completed exceptionallyInterruptedException
- 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 viaFDBDatabaseFactory.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)
-
-