Options provide a way to configure Store when opening it. Options functions can be chained, e.g. options.directory("mypath/objectbox").maxDbSizeInKb(2048); Note: Options objects can be used only once to create a store as they are "consumed" during Store creation. Thus, you need to create a new Option object for each Store that is created. More...

#include <objectbox.hpp>

Public Member Functions
	Options ()

	Options (OBX_model *model)

	~Options ()

Options &	model (OBX_model *model)
	Set the model on the options. The default is no model. NOTE: the model is always freed by this function, including when an error occurs. More...

Options &	directory (const char *dir)
	Set the store directory on the options. The default is "objectbox". Use the prefix "memory:" to open an in-memory database, e.g. "memory:myApp" (see docs for details). More...

Options &	directory (const std::string &dir)
	Set the store directory on the options. The default is "objectbox". Use the prefix "memory:" to open an in-memory database, e.g. "memory:myApp" (see docs for details). More...

std::string	getDirectory () const
	Gets the option for "directory"; this is either the default, or, the value set by directory(). More...

Options &	maxDbSizeInKb (uint64_t sizeInKb)
	Set the maximum db size on the options. The default is 1Gb. More...

uint64_t	getMaxDbSizeInKb () const
	Gets the option for "max DB size"; this is either the default, or, the value set by maxDbSizeInKb(). More...

Options &	maxDataSizeInKb (uint64_t sizeInKb)
	Data size tracking is more involved than DB size tracking, e.g. it stores an internal counter. Thus only use it if a stricter, more accurate limit is required (it's off by default). It tracks the size of actual data bytes of objects (system and metadata is not considered). On the upside, reaching the data limit still allows data to be removed (assuming DB limit is not reached). Max data and DB sizes can be combined; data size must be below the DB size. More...

uint64_t	getMaxDataSizeInKb () const
	Gets the option for "max DB size"; this is either the default, or, the value set by maxDataSizeInKb(). More...

Options &	fileMode (unsigned int fileMode)
	Set the file mode on the options. The default is 0644 (unix-style) More...

Options &	maxReaders (unsigned int maxReaders)
	Set the maximum number of readers (related to read transactions. "Readers" are an finite resource for which we need to define a maximum number upfront. The default value is enough for most apps and usually you can ignore it completely. However, if you get the OBX_ERROR_MAX_READERS_EXCEEDED error, you should verify your threading. For each thread, ObjectBox uses multiple readers. Their number (per thread) depends on number of types, relations, and usage patterns. Thus, if you are working with many threads (e.g. in a server-like scenario), it can make sense to increase the maximum number of readers. More...

Options &	noReaderThreadLocals (bool flag)
	Disables the usage of thread locals for "readers" related to read transactions. This can make sense if you are using a lot of threads that are kept alive. More...

Options &	modelBytes (const void *bytes, size_t size)
	Set the model on the options copying the given bytes. The default is no model. More...

Options &	modelBytesDirect (const void *bytes, size_t size)
	Like modelBytes() BUT WITHOUT copying the given bytes. Thus, you must keep the bytes available until after the store is created. More...

Options &	validateOnOpenPages (size_t pageLimit, uint32_t flags=OBXValidateOnOpenPagesFlags_None)
	When the DB is opened initially, ObjectBox can do a consistency check on the given amount of pages. Reliable file systems already guarantee consistency, so this is primarily meant to deal with unreliable OSes, file systems, or hardware. Thus, usually a low number (e.g. 1-20) is sufficient and does not impact startup performance significantly. To completely disable this you can pass 0, but we recommend a setting of at least 1. Note: ObjectBox builds upon ACID storage, which guarantees consistency given that the file system is working correctly (in particular fsync). More...

Options &	validateOnOpenKv (uint32_t flags=OBXValidateOnOpenKvFlags_None)
	When the DB is opened initially, ObjectBox can do a validation over the key/value pairs to check, for example, whether they're consistent towards our internal specification. More...

Options &	putPaddingMode (OBXPutPaddingMode mode)
	Don't touch unless you know exactly what you are doing: Advanced setting typically meant for language bindings (not end users). See OBXPutPaddingMode description. More...

Options &	readSchema (bool value)
	Advanced setting meant only for special scenarios: setting to false causes opening the database in a limited, schema-less mode. If you don't know what this means exactly: ignore this flag. Defaults to true. More...

Options &	usePreviousCommit (bool value)
	Advanced setting recommended to be used together with read-only mode to ensure no data is lost. Ignores the latest data snapshot (committed transaction state) and uses the previous snapshot instead. When used with care (e.g. backup the DB files first), this option may also recover data removed by the latest transaction. Defaults to false. More...

Options &	readOnly (bool value)
	Open store in read-only mode: no schema update, no write transactions. Defaults to false. More...

Options &	debugFlags (uint32_t flags)
	Configure debug flags; e.g. to influence logging. Defaults to NONE. More...

Options &	addDebugFlags (uint32_t flags)
	Adds debug flags to potentially existing ones (that were previously set). More...

uint32_t	getDebugFlags () const
	Gets the option for "debug flags"; this is either the default, or, the value set by debugFlags(). More...

Options &	asyncMaxQueueLength (size_t value)
	Maximum of async elements in the queue before new elements will be rejected. Hitting this limit usually hints that async processing cannot keep up; data is produced at a faster rate than it can be persisted in the background. In that case, increasing this value is not the only alternative; other values might also optimize throughput. For example, increasing maxInTxDurationMicros may help too. More...

Options &	asyncThrottleAtQueueLength (size_t value)
	Producers (AsyncTx submitter) is throttled when the queue size hits this. More...

Options &	asyncThrottleMicros (uint32_t value)
	Sleeping time for throttled producers on each submission. More...

Options &	asyncMaxInTxDuration (uint32_t micros)
	Maximum duration spent in a transaction before AsyncQ enforces a commit. This becomes relevant if the queue is constantly populated at a high rate. More...

Options &	asyncMaxInTxOperations (uint32_t value)
	Maximum operations performed in a transaction before AsyncQ enforces a commit. This becomes relevant if the queue is constantly populated at a high rate. More...

Options &	asyncPreTxnDelay (uint32_t delayMicros)
	Before the AsyncQ is triggered by a new element in queue to starts a new run, it delays actually starting the transaction by this value. This gives a newly starting producer some time to produce more than one a single operation before AsyncQ starts. Note: this value should typically be low to keep latency low and prevent accumulating too much operations. More...

Options &	asyncPreTxnDelay (uint32_t delayMicros, uint32_t delay2Micros, size_t minQueueLengthForDelay2)
	Before the AsyncQ is triggered by a new element in queue to starts a new run, it delays actually starting the transaction by this value. This gives a newly starting producer some time to produce more than one a single operation before AsyncQ starts. Note: this value should typically be low to keep latency low and prevent accumulating too much operations. More...

Options &	asyncPostTxnDelay (uint32_t delayMicros)
	Similar to preTxDelay but after a transaction was committed. One of the purposes is to give other transactions some time to execute. In combination with preTxDelay this can prolong non-TX batching time if only a few operations are around. More...

Options &	asyncPostTxnDelay (uint32_t delayMicros, uint32_t delay2Micros, size_t minQueueLengthForDelay2, bool subtractProcessingTime=false)
	Similar to preTxDelay but after a transaction was committed. One of the purposes is to give other transactions some time to execute. In combination with preTxDelay this can prolong non-TX batching time if only a few operations are around. More...

Options &	asyncMinorRefillThreshold (size_t queueLength)
	Numbers of operations below this value are considered "minor refills". More...

Options &	asyncMinorRefillMaxCount (uint32_t value)
	If non-zero, this allows "minor refills" with small batches that came in (off by default). More...

Options &	asyncMaxTxPoolSize (size_t value)
	Default value: 10000, set to 0 to deactivate pooling. More...

Options &	asyncObjectBytesMaxCacheSize (uint64_t value)
	Total cache size; default: ~ 0.5 MB. More...

Options &	asyncObjectBytesMaxSizeToCache (uint64_t value)
	Maximal size for an object to be cached (only cache smaller ones) More...

Options &	logCallback (obx_log_callback callback, void userData)
	Registers a log callback, which is called for a selection of log events. Note: this does not replace the default logging, which is much more extensive (at least at this point). More...

Options &	backupRestore (const char *backupFile, uint32_t flags=0)
	Before opening the database, this options instructs to restore the database content from the given backup file. Note: backup is a server-only feature. By default, actually restoring the backup is only performed if no database already exists (database does not contain data). More...

Options &	wal (uint32_t flags=OBXWalFlags_EnableWal)
	Enables Write-ahead logging (WAL); for now this is only supported for in-memory DBs. More...

Options &	walMaxFileSizeOnOpenInKb (uint64_t size_in_kb)
	The WAL file gets consolidated when it reached this size limit when opening the database. This setting is meant for applications that prefer to consolidate on startup, which may avoid consolidations on commits while the application is running. The default is 4096 (4 MB). More...

Options &	walMaxFileSizeInKb (uint64_t size_in_kb)
	The WAL file gets consolidated when it reaches this size limit after a commit. As consolidation takes some time, it is a trade-off between accumulating enough data and the time the consolidation takes (longer with more data). The default is 16384 (16 MB). More...

Detailed Description

Options provide a way to configure Store when opening it. Options functions can be chained, e.g. options.directory("mypath/objectbox").maxDbSizeInKb(2048); Note: Options objects can be used only once to create a store as they are "consumed" during Store creation. Thus, you need to create a new Option object for each Store that is created.

Constructor & Destructor Documentation

◆ Options() [1/2]

obx::Options::Options ( )

inline

◆ Options() [2/2]

obx::Options::Options ( OBX_model * model )

inlineexplicit

Deprecated:: is this used by generator?

◆ ~Options()

obx::Options::~Options ( )

inline

Member Function Documentation

◆ addDebugFlags()

Options& obx::Options::addDebugFlags ( uint32_t flags )

inline

Adds debug flags to potentially existing ones (that were previously set).

◆ asyncMaxInTxDuration()

Options& obx::Options::asyncMaxInTxDuration ( uint32_t micros )

inline

Maximum duration spent in a transaction before AsyncQ enforces a commit. This becomes relevant if the queue is constantly populated at a high rate.

◆ asyncMaxInTxOperations()

Options& obx::Options::asyncMaxInTxOperations ( uint32_t value )

inline

Maximum operations performed in a transaction before AsyncQ enforces a commit. This becomes relevant if the queue is constantly populated at a high rate.

◆ asyncMaxQueueLength()

Options& obx::Options::asyncMaxQueueLength ( size_t value )

inline

Maximum of async elements in the queue before new elements will be rejected. Hitting this limit usually hints that async processing cannot keep up; data is produced at a faster rate than it can be persisted in the background. In that case, increasing this value is not the only alternative; other values might also optimize throughput. For example, increasing maxInTxDurationMicros may help too.

◆ asyncMaxTxPoolSize()

Options& obx::Options::asyncMaxTxPoolSize ( size_t value )

inline

Default value: 10000, set to 0 to deactivate pooling.

◆ asyncMinorRefillMaxCount()

Options& obx::Options::asyncMinorRefillMaxCount ( uint32_t value )

inline

If non-zero, this allows "minor refills" with small batches that came in (off by default).

◆ asyncMinorRefillThreshold()

Options& obx::Options::asyncMinorRefillThreshold ( size_t queueLength )

inline

Numbers of operations below this value are considered "minor refills".

◆ asyncObjectBytesMaxCacheSize()

Options& obx::Options::asyncObjectBytesMaxCacheSize ( uint64_t value )

inline

Total cache size; default: ~ 0.5 MB.

◆ asyncObjectBytesMaxSizeToCache()

Options& obx::Options::asyncObjectBytesMaxSizeToCache ( uint64_t value )

inline

Maximal size for an object to be cached (only cache smaller ones)

◆ asyncPostTxnDelay() [1/2]

Options& obx::Options::asyncPostTxnDelay ( uint32_t delayMicros )

inline

Similar to preTxDelay but after a transaction was committed. One of the purposes is to give other transactions some time to execute. In combination with preTxDelay this can prolong non-TX batching time if only a few operations are around.

◆ asyncPostTxnDelay() [2/2]

Options& obx::Options::asyncPostTxnDelay	(	uint32_t	delayMicros,
		uint32_t	delay2Micros,
		size_t	minQueueLengthForDelay2,
		bool	subtractProcessingTime = `false`
	)

inline

Similar to preTxDelay but after a transaction was committed. One of the purposes is to give other transactions some time to execute. In combination with preTxDelay this can prolong non-TX batching time if only a few operations are around.

Parameters

subtractProcessingTime If set, the delayMicros is interpreted from the start of TX processing. In other words, the actual delay is delayMicros minus the TX processing time including the commit. This can make timings more accurate (e.g. when fixed batching interval are given).

◆ asyncPreTxnDelay() [1/2]

Options& obx::Options::asyncPreTxnDelay ( uint32_t delayMicros )

inline

Before the AsyncQ is triggered by a new element in queue to starts a new run, it delays actually starting the transaction by this value. This gives a newly starting producer some time to produce more than one a single operation before AsyncQ starts. Note: this value should typically be low to keep latency low and prevent accumulating too much operations.

◆ asyncPreTxnDelay() [2/2]

Options& obx::Options::asyncPreTxnDelay	(	uint32_t	delayMicros,
		uint32_t	delay2Micros,
		size_t	minQueueLengthForDelay2
	)

inline

Before the AsyncQ is triggered by a new element in queue to starts a new run, it delays actually starting the transaction by this value. This gives a newly starting producer some time to produce more than one a single operation before AsyncQ starts. Note: this value should typically be low to keep latency low and prevent accumulating too much operations.

◆ asyncThrottleAtQueueLength()

Options& obx::Options::asyncThrottleAtQueueLength ( size_t value )

inline

Producers (AsyncTx submitter) is throttled when the queue size hits this.

◆ asyncThrottleMicros()

Options& obx::Options::asyncThrottleMicros ( uint32_t value )

inline

Sleeping time for throttled producers on each submission.

◆ backupRestore()

Options& obx::Options::backupRestore	(	const char *	backupFile,
		uint32_t	flags = `0`
	)

inline

Before opening the database, this options instructs to restore the database content from the given backup file. Note: backup is a server-only feature. By default, actually restoring the backup is only performed if no database already exists (database does not contain data).

Parameters

flags For default behavior pass 0, or adjust defaults using OBXBackupRestoreFlags bit flags, e.g., to overwrite all existing data in the database.

◆ debugFlags()

Options& obx::Options::debugFlags ( uint32_t flags )

inline

Configure debug flags; e.g. to influence logging. Defaults to NONE.

◆ directory() [1/2]

Options& obx::Options::directory ( const char * dir )

inline

Set the store directory on the options. The default is "objectbox". Use the prefix "memory:" to open an in-memory database, e.g. "memory:myApp" (see docs for details).

◆ directory() [2/2]

Options& obx::Options::directory ( const std::string & dir )

inline

Set the store directory on the options. The default is "objectbox". Use the prefix "memory:" to open an in-memory database, e.g. "memory:myApp" (see docs for details).

◆ fileMode()

Options& obx::Options::fileMode ( unsigned int fileMode )

inline

Set the file mode on the options. The default is 0644 (unix-style)

◆ getDebugFlags()

uint32_t obx::Options::getDebugFlags ( ) const

inline

Gets the option for "debug flags"; this is either the default, or, the value set by debugFlags().

◆ getDirectory()

std::string obx::Options::getDirectory ( ) const

inline

Gets the option for "directory"; this is either the default, or, the value set by directory().

◆ getMaxDataSizeInKb()

uint64_t obx::Options::getMaxDataSizeInKb ( ) const

inline

Gets the option for "max DB size"; this is either the default, or, the value set by maxDataSizeInKb().

◆ getMaxDbSizeInKb()

uint64_t obx::Options::getMaxDbSizeInKb ( ) const

inline

Gets the option for "max DB size"; this is either the default, or, the value set by maxDbSizeInKb().

◆ logCallback()

Options& obx::Options::logCallback	(	obx_log_callback *	callback,
		void *	userData
	)

inline

Registers a log callback, which is called for a selection of log events. Note: this does not replace the default logging, which is much more extensive (at least at this point).

◆ maxDataSizeInKb()

Options& obx::Options::maxDataSizeInKb ( uint64_t sizeInKb )

inline

Data size tracking is more involved than DB size tracking, e.g. it stores an internal counter. Thus only use it if a stricter, more accurate limit is required (it's off by default). It tracks the size of actual data bytes of objects (system and metadata is not considered). On the upside, reaching the data limit still allows data to be removed (assuming DB limit is not reached). Max data and DB sizes can be combined; data size must be below the DB size.

◆ maxDbSizeInKb()

Options& obx::Options::maxDbSizeInKb ( uint64_t sizeInKb )

inline

Set the maximum db size on the options. The default is 1Gb.

◆ maxReaders()

Options& obx::Options::maxReaders ( unsigned int maxReaders )

inline

Set the maximum number of readers (related to read transactions. "Readers" are an finite resource for which we need to define a maximum number upfront. The default value is enough for most apps and usually you can ignore it completely. However, if you get the OBX_ERROR_MAX_READERS_EXCEEDED error, you should verify your threading. For each thread, ObjectBox uses multiple readers. Their number (per thread) depends on number of types, relations, and usage patterns. Thus, if you are working with many threads (e.g. in a server-like scenario), it can make sense to increase the maximum number of readers.

Note: The internal default is currently 126. So when hitting this limit, try values around 200-500.

Attention: Each thread that performed a read transaction and is still alive holds on to a reader slot. These slots only get vacated when the thread ends. Thus be mindful with the number of active threads. Alternatively, you can opt to try the experimental noReaderThreadLocals option flag.

◆ model()

Options& obx::Options::model ( OBX_model * model )

inline

Set the model on the options. The default is no model. NOTE: the model is always freed by this function, including when an error occurs.

◆ modelBytes()

Options& obx::Options::modelBytes	(	const void *	bytes,
		size_t	size
	)

inline

Set the model on the options copying the given bytes. The default is no model.

◆ modelBytesDirect()

Options& obx::Options::modelBytesDirect	(	const void *	bytes,
		size_t	size
	)

inline

Like modelBytes() BUT WITHOUT copying the given bytes. Thus, you must keep the bytes available until after the store is created.

◆ noReaderThreadLocals()

Options& obx::Options::noReaderThreadLocals ( bool flag )

inline

Disables the usage of thread locals for "readers" related to read transactions. This can make sense if you are using a lot of threads that are kept alive.

Note: This is still experimental, as it comes with subtle behavior changes at a low level and may affect corner cases with e.g. transactions, which may not be fully tested at the moment.

◆ putPaddingMode()

Options& obx::Options::putPaddingMode ( OBXPutPaddingMode mode )

inline

Don't touch unless you know exactly what you are doing: Advanced setting typically meant for language bindings (not end users). See OBXPutPaddingMode description.

◆ readOnly()

Options& obx::Options::readOnly ( bool value )

inline

Open store in read-only mode: no schema update, no write transactions. Defaults to false.

◆ readSchema()

Options& obx::Options::readSchema ( bool value )

inline

Advanced setting meant only for special scenarios: setting to false causes opening the database in a limited, schema-less mode. If you don't know what this means exactly: ignore this flag. Defaults to true.

◆ usePreviousCommit()

Options& obx::Options::usePreviousCommit ( bool value )

inline

Advanced setting recommended to be used together with read-only mode to ensure no data is lost. Ignores the latest data snapshot (committed transaction state) and uses the previous snapshot instead. When used with care (e.g. backup the DB files first), this option may also recover data removed by the latest transaction. Defaults to false.

◆ validateOnOpenKv()

Options& obx::Options::validateOnOpenKv ( uint32_t flags = OBXValidateOnOpenKvFlags_None )

inline

When the DB is opened initially, ObjectBox can do a validation over the key/value pairs to check, for example, whether they're consistent towards our internal specification.

Parameters

flags flags used to influence how the validation checks are performed; only OBXValidateOnOpenKvFlags_None is supported for now.

◆ validateOnOpenPages()

Options& obx::Options::validateOnOpenPages	(	size_t	pageLimit,
		uint32_t	flags = `OBXValidateOnOpenPagesFlags_None`
	)

inline

When the DB is opened initially, ObjectBox can do a consistency check on the given amount of pages. Reliable file systems already guarantee consistency, so this is primarily meant to deal with unreliable OSes, file systems, or hardware. Thus, usually a low number (e.g. 1-20) is sufficient and does not impact startup performance significantly. To completely disable this you can pass 0, but we recommend a setting of at least 1. Note: ObjectBox builds upon ACID storage, which guarantees consistency given that the file system is working correctly (in particular fsync).

Parameters

pageLimit	limits the number of checked pages (currently defaults to 0, but will be increased in the future)
flags	flags used to influence how the validation checks are performed

◆ wal()

Options& obx::Options::wal ( uint32_t flags = OBXWalFlags_EnableWal )

inline

Enables Write-ahead logging (WAL); for now this is only supported for in-memory DBs.

Parameters

flags WAL itself is enabled by setting flag OBXWalFlags_EnableWal (also the default parameter value). Combine with other flags using bitwise OR or switch off WAL by passing 0.

◆ walMaxFileSizeInKb()

Options& obx::Options::walMaxFileSizeInKb ( uint64_t size_in_kb )

inline

The WAL file gets consolidated when it reaches this size limit after a commit. As consolidation takes some time, it is a trade-off between accumulating enough data and the time the consolidation takes (longer with more data). The default is 16384 (16 MB).

◆ walMaxFileSizeOnOpenInKb()

Options& obx::Options::walMaxFileSizeOnOpenInKb ( uint64_t size_in_kb )

inline

The WAL file gets consolidated when it reached this size limit when opening the database. This setting is meant for applications that prefer to consolidate on startup, which may avoid consolidations on commits while the application is running. The default is 4096 (4 MB).

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Options() [1/2]

◆ Options() [2/2]

◆ ~Options()

Member Function Documentation

◆ addDebugFlags()

◆ asyncMaxInTxDuration()

◆ asyncMaxInTxOperations()

◆ asyncMaxQueueLength()

◆ asyncMaxTxPoolSize()

◆ asyncMinorRefillMaxCount()

◆ asyncMinorRefillThreshold()

◆ asyncObjectBytesMaxCacheSize()

◆ asyncObjectBytesMaxSizeToCache()

◆ asyncPostTxnDelay() [1/2]

◆ asyncPostTxnDelay() [2/2]

◆ asyncPreTxnDelay() [1/2]

◆ asyncPreTxnDelay() [2/2]

◆ asyncThrottleAtQueueLength()

◆ asyncThrottleMicros()

◆ backupRestore()

◆ debugFlags()

◆ directory() [1/2]

◆ directory() [2/2]

◆ fileMode()

◆ getDebugFlags()

◆ getDirectory()

◆ getMaxDataSizeInKb()

◆ getMaxDbSizeInKb()

◆ logCallback()

◆ maxDataSizeInKb()

◆ maxDbSizeInKb()

◆ maxReaders()

◆ model()

◆ modelBytes()

◆ modelBytesDirect()

◆ noReaderThreadLocals()

◆ putPaddingMode()

◆ readOnly()

◆ readSchema()

◆ usePreviousCommit()

◆ validateOnOpenKv()

◆ validateOnOpenPages()

◆ wal()

◆ walMaxFileSizeInKb()

◆ walMaxFileSizeOnOpenInKb()