Class FDBDatabaseFactory
- java.lang.Object
-
- com.apple.foundationdb.record.provider.foundationdb.FDBDatabaseFactory
-
@API(STABLE) public class FDBDatabaseFactory extends Object
A singleton maintaining a list ofFDBDatabase
instances, indexed by their cluster file location.
-
-
Field Summary
Fields Modifier and Type Field Description static int
DEFAULT_DIRECTORY_CACHE_SIZE
The default number of entries that is to be cached, per database, fromLocatableResolver
retrieval requests.protected static Function<FDBLatencySource,Long>
DEFAULT_LATENCY_INJECTOR
static long
DEFAULT_TR_TIMEOUT_MILLIS
Special value to set the transaction timeout to to indicate that transactions should use the system default.static long
UNLIMITED_TR_TIMEOUT_MILLIS
Special value to set the transaction timeout to to indicate that transactions should not have any timeout set at all.
-
Constructor Summary
Constructors Constructor Description FDBDatabaseFactory()
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
clear()
void
clearLatencyInjector()
Removes any previously installed latency injector.protected Supplier<BlockingInAsyncDetection>
getBlockingInAsyncDetectionSupplier()
FDBDatabase
getDatabase()
FDBDatabase
getDatabase(String clusterFile)
String
getDatacenterId()
int
getDirectoryCacheSize()
Executor
getExecutor()
long
getInitialDelayMillis()
Gets the delay ceiling (in milliseconds) that will be applied between attempts to run a transactional database operation.Function<FDBLatencySource,Long>
getLatencyInjector()
Returns the current latency injector.FDBLocalityProvider
getLocalityProvider()
Get the locality provider that is used to discover the server location of the keys.int
getMaxAttempts()
Gets the maximum number of attempts for a database to make when running a retriable transactional operation.long
getMaxDelayMillis()
Gets the maximum delay (in milliseconds) that will be applied between attempts to run a transactional database operation.Executor
getNetworkExecutor()
long
getReverseDirectoryMaxMillisPerTransaction()
int
getReverseDirectoryRowsPerTransaction()
long
getStateRefreshTimeMillis()
FDBRecordStoreStateCacheFactory
getStoreStateCacheFactory()
Get the store state cache factory.boolean
getTrackLastSeenVersion()
Supplier<Boolean>
getTransactionIsTracedSupplier()
long
getTransactionTimeoutMillis()
Get the transaction timeout time in milliseconds.long
getWarnAndCloseOpenContextsAfterSeconds()
Get whether to warn and close record contexts open for too long.protected FDB
initFDB()
static FDBDatabaseFactory
instance()
boolean
isRunLoopProfilingEnabled()
Get whether additional run-loop profiling has been been enabled.boolean
isUnclosedWarning()
protected Executor
newContextExecutor(Map<String,String> mdcContext)
Creates a newExecutor
for use by a specificFDBRecordContext
.void
setBlockingInAsyncDetection(BlockingInAsyncDetection behavior)
Controls if calls toFDBDatabase#asyncToSync(FDBStoreTimer, FDBStoreTimer.Wait, CompletableFuture)
orFDBRecordContext#asyncToSync(FDBStoreTimer.Wait, CompletableFuture)
will attempt to detect when they are being called from within an asynchronous context and how they should react to this fact when they are.void
setBlockingInAsyncDetection(Supplier<BlockingInAsyncDetection> supplier)
Provides a supplier that controls if calls toFDBDatabase#asyncToSync(FDBStoreTimer, FDBStoreTimer.Wait, CompletableFuture)
orFDBRecordContext#asyncToSync(FDBStoreTimer.Wait, CompletableFuture)
will attempt to detect when they are being called from within an asynchronous context and how they should react to this fact when they are.void
setContextExecutor(Function<Executor,Executor> contextExecutor)
Provides a function that will be invoked when aFDBRecordContext
is created, taking as input theExecutor
that is configured for the database, returning theExecutor
that will be used to execute all asynchronous completions produced from theFDBRecordContext
.void
setDatacenterId(String datacenterId)
void
setDirectoryCacheSize(int directoryCacheSize)
Sets the number of directory layer entries that will be cached for each database that is produced by the factory.void
setExecutor(Executor executor)
Sets the executor that will be used for all asynchronous tasks that are produced from operations initiated from databases produced from this factory.void
setInitialDelayMillis(long initialDelayMillis)
Sets the delay ceiling (in milliseconds) that will be applied between attempts to run a transactional database operation.void
setLatencyInjector(Function<FDBLatencySource,Long> latencyInjector)
Provides a function that computes a latency that should be injected into a specific FDB operation.void
setLocalityProvider(FDBLocalityProvider localityProvider)
Set the locality provider that is used to discover the server location of the keys.void
setMaxAttempts(int maxAttempts)
Sets the maximum number of attempts for a database to make when running a retriable transactional operation.void
setMaxDelayMillis(long maxDelayMillis)
Sets the maximum delay (in milliseconds) that will be applied between attempts to run a transactional database operation.void
setNetworkExecutor(Executor networkExecutor)
void
setReverseDirectoryMaxMillisPerTransaction(long millisPerTransaction)
When a reverse directory lookup is performed from aFDBReverseDirectoryCache
and an entry is not found in the cache and, thus, the directory layer must be scanned to find it, this property determines how many milliseconds may be spent scanning the cache within the context of a single transaction, before the transaction is closed and re-opened in order to avoid apast_version
.void
setReverseDirectoryRowsPerTransaction(int rowsPerTransaction)
When a reverse directory lookup is performed from aFDBReverseDirectoryCache
and an entry is not found in the cache and, thus, the directory layer must be scanned to find it, this property determines how many rows will be scanned within the context of a single transaction, before the transaction is closed and re-opened in order to avoid apast_version
.void
setRunLoopProfilingEnabled(boolean runLoopProfilingEnabled)
Set whether additional run-loop profiling of the FDB client is enabled.void
setStateRefreshTimeMillis(long stateRefreshTimeMillis)
Set the refresh time for the cachedLocatableResolver
state.void
setStoreStateCacheFactory(FDBRecordStoreStateCacheFactory storeStateCacheFactory)
Set the store state cache factory.void
setTrace(String traceDirectory, String traceLogGroup)
Configure the client trace directory and log group.void
setTraceFormat(FDBTraceFormat traceFormat)
Set the output format for the client trace logs.void
setTrackLastSeenVersion(boolean trackLastSeenVersion)
void
setTransactionIsTracedSupplier(Supplier<Boolean> transactionIsTracedSupplier)
Use transactionIsTracedSupplier to control whether a newly created transaction should be traced or not.void
setTransactionTimeoutMillis(long transactionTimeoutMillis)
Set the transaction timeout time in milliseconds.void
setUnclosedWarning(boolean unclosedWarning)
void
setWarnAndCloseOpenContextsAfterSeconds(long warnAndCloseOpenContextsAfterSeconds)
Set whether to warn and close record contexts open for too long.void
shutdown()
-
-
-
Field Detail
-
DEFAULT_LATENCY_INJECTOR
protected static final Function<FDBLatencySource,Long> DEFAULT_LATENCY_INJECTOR
-
DEFAULT_DIRECTORY_CACHE_SIZE
public static final int DEFAULT_DIRECTORY_CACHE_SIZE
The default number of entries that is to be cached, per database, fromLocatableResolver
retrieval requests.- See Also:
- Constant Field Values
-
DEFAULT_TR_TIMEOUT_MILLIS
public static final long DEFAULT_TR_TIMEOUT_MILLIS
Special value to set the transaction timeout to to indicate that transactions should use the system default.
-
UNLIMITED_TR_TIMEOUT_MILLIS
public static final long UNLIMITED_TR_TIMEOUT_MILLIS
Special value to set the transaction timeout to to indicate that transactions should not have any timeout set at all.
-
-
Method Detail
-
instance
@Nonnull public static FDBDatabaseFactory instance()
-
initFDB
protected FDB initFDB()
-
setExecutor
public void setExecutor(@Nonnull Executor executor)
Sets the executor that will be used for all asynchronous tasks that are produced from operations initiated from databases produced from this factory.- Parameters:
executor
- the executor to be used for asynchronous task completion
-
setContextExecutor
public void setContextExecutor(@Nonnull Function<Executor,Executor> contextExecutor)
Provides a function that will be invoked when aFDBRecordContext
is created, taking as input theExecutor
that is configured for the database, returning theExecutor
that will be used to execute all asynchronous completions produced from theFDBRecordContext
. An example use case for this function is to ensure thatThreadLocal
variables that are present in the thread that creates theFDBRecordContext
will be made present in the executor threads that are executing tasks.- Parameters:
contextExecutor
- function to produce an executor to be used for all tasks executed on behalf of a specific record context
-
newContextExecutor
@Nonnull protected Executor newContextExecutor(@Nullable Map<String,String> mdcContext)
Creates a newExecutor
for use by a specificFDBRecordContext
. IfmdcContext
is notnull
, the executor will ensure that the provided MDC present within the context of the executor thread.- Parameters:
mdcContext
- if present, the MDC context to be made available within the executors threads- Returns:
- a new executor to be used by a
FDBRecordContext
-
shutdown
public void shutdown()
-
clear
public void clear()
-
isUnclosedWarning
public boolean isUnclosedWarning()
-
setUnclosedWarning
public void setUnclosedWarning(boolean unclosedWarning)
-
setTrace
public void setTrace(@Nullable String traceDirectory, @Nullable String traceLogGroup)
Configure the client trace directory and log group. If set, this will configure the native client to emit trace logs with important metrics and instrumentation. As this information is useful for monitoring FoundationDB client behavior, it is generally recommended that the user set this option in production environments.The logs will be placed in the directory on the local filesystem specified by the
traceDirectory
parameter. If thetraceLogGroup
is set to a non-null value, each log message will have aLogGroup
field associated with it that is set to the parameter's value. This can be used to associate log messages from related processes together.This method should be called prior to the first time this factory is used to produce an
FDBDatabase
. The factory will configure the client in a manner consistent with the passed parameters the first time a database is needed, and subsequent calls to this method will have no effect.- Parameters:
traceDirectory
- the directory in which to write trace log files ornull
to disable writing logstraceLogGroup
- the value to set the log group field to in each message ofnull
to set no group
-
setTraceFormat
public void setTraceFormat(@Nonnull FDBTraceFormat traceFormat)
Set the output format for the client trace logs. This only will have any effect ifsetTrace(String, String)
is also called. If that method is called (i.e., if trace logs are enabled), then this will be used to configure what the output format of trace log files should be. SeeFDBTraceFormat
for more details on what options are available.This method should be called prior to the first time this factory is used to produce an
FDBDatabase
. The factory will configure the client in a manner consistent with the passed parameters the first time a database is needed, and subsequent calls to this method will have no effect.- Parameters:
traceFormat
- the output format for client trace logs- See Also:
setTrace(String, String)
,FDBTraceFormat
-
getDirectoryCacheSize
public int getDirectoryCacheSize()
-
getTrackLastSeenVersion
public boolean getTrackLastSeenVersion()
-
getDatacenterId
public String getDatacenterId()
-
setDirectoryCacheSize
public void setDirectoryCacheSize(int directoryCacheSize)
Sets the number of directory layer entries that will be cached for each database that is produced by the factory. Changing this value after databases have been created will result in each database having its existing entries discarded and the cache size adjusted to the provided value.Each
FDBDatabase
maintains a cache of entries that have been retrieved by any instance of aLocatableResolver
using that database. Thus, this cache is shared across all resolvers (it should be noted entries in this cache are segregated by resolver and treated as distinct, ensuring that the value for a directory entry from one resolver will not be returned to another resolver even if they share the same key).- Parameters:
directoryCacheSize
- the new directory cache size
-
setTrackLastSeenVersion
public void setTrackLastSeenVersion(boolean trackLastSeenVersion)
-
setDatacenterId
public void setDatacenterId(String datacenterId)
-
setRunLoopProfilingEnabled
public void setRunLoopProfilingEnabled(boolean runLoopProfilingEnabled)
Set whether additional run-loop profiling of the FDB client is enabled. This can be useful for debugging certain performance problems, but the profiling is also fairly heavy-weight, and so it is not generally recommended when performance is critical. This method should be set prior to the firstFDBDatabase
is returned by this factory, as otherwise, it will have no effect (i.e., run-loop profiling will not actually be enabled). Enabling run-loop profiling also places its output in the FDB client trace logs, so it only makes sense to call this method if one also callssetTrace(String, String)
.- Parameters:
runLoopProfilingEnabled
- whether run-loop profiling should be enabled- See Also:
NetworkOptions.setEnableSlowTaskProfiling()
-
isRunLoopProfilingEnabled
public boolean isRunLoopProfilingEnabled()
Get whether additional run-loop profiling has been been enabled.- Returns:
- whether additional run-loop profiling has been enabled
- See Also:
setRunLoopProfilingEnabled(boolean)
-
getMaxAttempts
public int getMaxAttempts()
Gets the maximum number of attempts for a database to make when running a retriable transactional operation. This is used byFDBDatabase.run()
andFDBDatabase.runAsync()
to limit the number of attempts that an operation is retried. The default value is 10.- Returns:
- the maximum number of times to run a transactional database operation
-
setMaxAttempts
public void setMaxAttempts(int maxAttempts)
Sets the maximum number of attempts for a database to make when running a retriable transactional operation. This is used byFDBDatabase.run()
andFDBDatabase.runAsync()
to limit the number of attempts that an operation is retried. The default value is 10.- Parameters:
maxAttempts
- the maximum number of times to run a transactional database operation- Throws:
IllegalArgumentException
- if a non-positive number is given
-
getMaxDelayMillis
public long getMaxDelayMillis()
Gets the maximum delay (in milliseconds) that will be applied between attempts to run a transactional database operation. This is used withinFDBDatabase.run()
andFDBDatabase.runAsync()
to limit the time spent between successive attempts at completing a database operation. The default value is 1000 so that there will not be more than 1 second between attempts.- Returns:
- the maximum delay between attempts when retrying operations
-
setMaxDelayMillis
public void setMaxDelayMillis(long maxDelayMillis)
Sets the maximum delay (in milliseconds) that will be applied between attempts to run a transactional database operation. This is used withinFDBDatabase.run()
andFDBDatabase.runAsync()
to limit the time spent between successive attempts at completing a database operation. The default is 1000 so that there will not be more than 1 second between attempts.- Parameters:
maxDelayMillis
- the maximum delay between attempts when retrying operations- Throws:
IllegalArgumentException
- if the value is negative or less than the minimum delay
-
getInitialDelayMillis
public long getInitialDelayMillis()
Gets the delay ceiling (in milliseconds) that will be applied between attempts to run a transactional database operation. This is used withinFDBDatabase.run()
andFDBDatabase.runAsync()
to determine how long to wait between the first and second attempts at running a database operation. The exponential backoff algorithm will choose an amount of time to wait between zero and the initial delay, and will use that value each successive iteration to determine how long that wait should be. The default value is 10 milliseconds.- Returns:
- the delay ceiling between the first and second attempts at running a database operation
-
setInitialDelayMillis
public void setInitialDelayMillis(long initialDelayMillis)
Sets the delay ceiling (in milliseconds) that will be applied between attempts to run a transactional database operation. This is used withinFDBDatabase.run()
andFDBDatabase.runAsync()
to determine how long to wait between the first and second attempts at running a database operation. The exponential backoff algorithm will choose an amount of time to wait between zero and the initial delay, and will use that value each successive iteration to determine how long that wait should be. The default value is 10 milliseconds.- Parameters:
initialDelayMillis
- the delay ceiling between the first and second attempts at running a database operation- Throws:
IllegalArgumentException
- if the value is negative or greater than the maximum delay
-
setReverseDirectoryRowsPerTransaction
public void setReverseDirectoryRowsPerTransaction(int rowsPerTransaction)
When a reverse directory lookup is performed from aFDBReverseDirectoryCache
and an entry is not found in the cache and, thus, the directory layer must be scanned to find it, this property determines how many rows will be scanned within the context of a single transaction, before the transaction is closed and re-opened in order to avoid apast_version
.- Parameters:
rowsPerTransaction
- the number of rows to scan within the context of a single transaction
-
getReverseDirectoryRowsPerTransaction
public int getReverseDirectoryRowsPerTransaction()
-
setReverseDirectoryMaxMillisPerTransaction
public void setReverseDirectoryMaxMillisPerTransaction(long millisPerTransaction)
When a reverse directory lookup is performed from aFDBReverseDirectoryCache
and an entry is not found in the cache and, thus, the directory layer must be scanned to find it, this property determines how many milliseconds may be spent scanning the cache within the context of a single transaction, before the transaction is closed and re-opened in order to avoid apast_version
.- Parameters:
millisPerTransaction
- the number of miliseconds to spend scanning
-
getReverseDirectoryMaxMillisPerTransaction
public long getReverseDirectoryMaxMillisPerTransaction()
-
setTransactionIsTracedSupplier
public void setTransactionIsTracedSupplier(Supplier<Boolean> transactionIsTracedSupplier)
Use transactionIsTracedSupplier to control whether a newly created transaction should be traced or not. Traced transactions are used to identify and profile unclosed transactions. In order to trace the source of a leaked transaction, it is necessary to capture a stack trace at the point the transaction is created which is a rather expensive operation, so this should either be disabled in a production environment or the supplier to return true for only a very small subset of transactions.- Parameters:
transactionIsTracedSupplier
- a supplier which should returntrue
for creating traced transactions
-
getWarnAndCloseOpenContextsAfterSeconds
public long getWarnAndCloseOpenContextsAfterSeconds()
Get whether to warn and close record contexts open for too long.- Returns:
- number of seconds after which a context and be closed and a warning logged
-
setWarnAndCloseOpenContextsAfterSeconds
public void setWarnAndCloseOpenContextsAfterSeconds(long warnAndCloseOpenContextsAfterSeconds)
Set whether to warn and close record contexts open for too long.- Parameters:
warnAndCloseOpenContextsAfterSeconds
- number of seconds after which a context and be closed and a warning logged
-
setBlockingInAsyncDetection
public void setBlockingInAsyncDetection(@Nonnull BlockingInAsyncDetection behavior)
Controls if calls toFDBDatabase#asyncToSync(FDBStoreTimer, FDBStoreTimer.Wait, CompletableFuture)
orFDBRecordContext#asyncToSync(FDBStoreTimer.Wait, CompletableFuture)
will attempt to detect when they are being called from within an asynchronous context and how they should react to this fact when they are. Note that the process of performing this detection is quite expensive, so running with detection enabled in not recommended for environments other than testing.- Parameters:
behavior
- the blocking desired blocking detection behavior (seeBlockingInAsyncDetection
)
-
setBlockingInAsyncDetection
public void setBlockingInAsyncDetection(@Nonnull Supplier<BlockingInAsyncDetection> supplier)
Provides a supplier that controls if calls toFDBDatabase#asyncToSync(FDBStoreTimer, FDBStoreTimer.Wait, CompletableFuture)
orFDBRecordContext#asyncToSync(FDBStoreTimer.Wait, CompletableFuture)
will attempt to detect when they are being called from within an asynchronous context and how they should react to this fact when they are. Because such detection is quite expensive, it is suggested that it is eitherBlockingInAsyncDetection.DISABLED
for anything other than testing environments or that the supplier randomly chooses a small sample rate in which detection should be enabled.- Parameters:
supplier
- a supplier that produces the blocking desired blocking detection behavior (seeBlockingInAsyncDetection
)
-
getBlockingInAsyncDetectionSupplier
@Nonnull protected Supplier<BlockingInAsyncDetection> getBlockingInAsyncDetectionSupplier()
-
setLatencyInjector
public void setLatencyInjector(@Nonnull Function<FDBLatencySource,Long> latencyInjector)
Provides a function that computes a latency that should be injected into a specific FDB operation. The provided function takes aFDBLatencySource
as input and returns the number of milliseconds delay that should be injected before the operation completes. Returning a value of zero or less indicates that no delay should be injected.Latency injection can be useful for simulating environments in which FDB is under stress or in a configuration in which latency is inherent in its operation.
- Parameters:
latencyInjector
- a function computing the latency to be injected into an operation
-
getLatencyInjector
public Function<FDBLatencySource,Long> getLatencyInjector()
Returns the current latency injector.- Returns:
- the current latency injector
-
clearLatencyInjector
public void clearLatencyInjector()
Removes any previously installed latency injector.
-
getStateRefreshTimeMillis
public long getStateRefreshTimeMillis()
-
setStateRefreshTimeMillis
public void setStateRefreshTimeMillis(long stateRefreshTimeMillis)
Set the refresh time for the cachedLocatableResolver
state. Defaults to 30 seconds.- Parameters:
stateRefreshTimeMillis
- time to set, in milliseconds
-
setTransactionTimeoutMillis
public void setTransactionTimeoutMillis(long transactionTimeoutMillis)
Set the transaction timeout time in milliseconds. Databases created by this factory will use this value when they create transactions. If the timeout is reached, the transaction will fail with anFDBExceptions.FDBStoreTransactionTimeoutException
and will not be retried. Any outstanding work from the transaction will be cancelled, though the user should still close theFDBRecordContext
to free any native memory used by the transaction.If set to
DEFAULT_TR_TIMEOUT_MILLIS
, then the transaction's timeout will default to the system default, which is the value set byDatabaseOptions.setTransactionTimeout(long)
. If that option is not set, then no timeout will be imposed on the transaction. Note also that this is the default valueIf set to
UNLIMITED_TR_TIMEOUT_MILLIS
, then the no timeout will be imposed on the transaction. This will override the system default if one is set.- Parameters:
transactionTimeoutMillis
- the amount of time in milliseconds before a transaction should timeout
-
getTransactionTimeoutMillis
public long getTransactionTimeoutMillis()
Get the transaction timeout time in milliseconds. SeesetTransactionTimeoutMillis(long)
for more information, especially for the meaning of the special valuesDEFAULT_TR_TIMEOUT_MILLIS
andUNLIMITED_TR_TIMEOUT_MILLIS
.- Returns:
- the transaction timeout time in milliseconds
- See Also:
setTransactionTimeoutMillis(long)
-
getStoreStateCacheFactory
@API(EXPERIMENTAL) @Nonnull public FDBRecordStoreStateCacheFactory getStoreStateCacheFactory()
Get the store state cache factory. EachFDBDatabase
produced by thisFDBDatabaseFactory
will be initialized with anFDBRecordStoreStateCache
from this cache factory. By default, the factory is aPassThroughRecordStoreStateCacheFactory
which means that the record store state information is never cached.- Returns:
- the factory of
FDBRecordStoreStateCache
s used when initializingFDBDatabase
s
-
setStoreStateCacheFactory
@API(EXPERIMENTAL) public void setStoreStateCacheFactory(@Nonnull FDBRecordStoreStateCacheFactory storeStateCacheFactory)
Set the store state cache factory. EachFDBDatabase
produced by thisFDBDatabaseFactory
will be initialized with anFDBRecordStoreStateCache
from the cache factory provided.- Parameters:
storeStateCacheFactory
- a factory ofFDBRecordStoreStateCache
s to use when initializingFDBDatabase
s- See Also:
FDBRecordStoreStateCache
-
getDatabase
@Nonnull public FDBDatabase getDatabase(@Nullable String clusterFile)
-
getDatabase
@Nonnull public FDBDatabase getDatabase()
-
getLocalityProvider
@Nonnull public FDBLocalityProvider getLocalityProvider()
Get the locality provider that is used to discover the server location of the keys.- Returns:
- the installed locality provider
-
setLocalityProvider
public void setLocalityProvider(@Nonnull FDBLocalityProvider localityProvider)
Set the locality provider that is used to discover the server location of the keys.- Parameters:
localityProvider
- the locality provider- See Also:
FDBLocalityUtil
-
-