Properties

This is the manual for older MicroStream versions (Version < 5.0).

The new documentation (Version >= 5.0) is located at:

https://docs.microstream.one/

These are the available properties of the Configuration type. The names are used accordingly in the external configuration files. They can be found as constants in ConfigurationPropertyNames.

Property	Short Description
baseDirectory	The base directory of the storage in the file system. Default is "storage" in the working directory.
deletionDirectory	If configured, the storage will not delete files. Instead of deleting a file it will be moved to this directory.
truncationDirectory	If configured, files that will get truncated are copied into this directory.
backupDirectory	The backup directory.
channelCount	The number of threads and number of directories used by the storage engine. Every thread has exclusive access to its directory. Default is 1.
channelDirectoryPrefix	Name prefix of the subdirectories used by the channel threads. Default is "channel_".
dataFilePrefix	Name prefix of the storage files. Default is "channel_".
dataFileSuffix	Name suffix of the storage files. Default is ".dat".
transactionFilePrefix	Name prefix of the storage transaction file. Default is "transactions_".
transactionFileSuffix	Name suffix of the storage transaction file. Default is ".sft".
typeDictionaryFilename	The name of the dictionary file. Default is "PersistenceTypeDictionary.ptd".
houseKeepingInterval	Interval in milliseconds for the housekeeping. This is work like garbage collection or cache checking. In combination with houseKeepingNanoTimeBudget the maximum processor time for housekeeping work can be set. Default is 1000 (every second).
houseKeepingNanoTimeBudget	Number of nanoseconds used for each housekeeping cycle. Default is 10000000 (10 million nanoseconds = 10 milliseconds = 0.01 seconds).
entityCacheThreshold	Abstract threshold value for the lifetime of entities in the cache. Default is 1000000000.
entityCacheTimeout	Timeout in milliseconds for the entity cache evaluator. If an entity wasn't accessed in this timespan it will be removed from the cache. Default is 86400000 (1 day).
dataFileMinSize	Minimum file size for a data file to avoid cleaning it up. Default is 1024^2 = 1 MiB.
dataFileMaxSize	Maximum file size for a data file to avoid cleaning it up. Default is 1024^2*8 = 8 MiB.
dataFileDissolveRatio	The degree of the data payload of a storage file to avoid cleaning it up. Default is 0.75 (75%).

Detailed Description

channelCount

Number of threads used by the storage engine. It depicts the numbers of subdirectories as well. Each thread manages one directory in which it writes to and reads from exclusively. The unity of thread, directory and the cached data therefor is called a "Channel".

__________________________________________________
                               [RAM ]{ Code }    |    (      Filesystem      )
               ,- "Channel 0": [Data]{Thread} <-I|O-> (Storage Subdirectory 0)
              /-- "Channel 1": [Data]{Thread} <-I|O-> (Storage Subdirectory 1)
StorageManager                                   |
              \-- "Channel 2": [Data]{Thread} <-I|O-> (Storage Subdirectory 2)
               '- "Channel 3": [Data]{Thread} <-I|O-> (Storage Subdirectory 3)
_________________________________________________|

Using Channels

houseKeepingInterval

Number of milliseconds for the house keeping interval. House keeping tasks are, among others:

• Garbage Collection

• Cache Check

• File Cleanup Check

In combination with houseKeepingNanoTimeBudget, it can be specified how many CPU time should be used for house keeping. E.g. interval=1000ms and budget=10000000ns means every second there's 0.01 seconds time for house keeping, so max 1% CPU time used for house keeping. This CPU time window is only used if house keeping work is pending. If nothing has to be done, no time is wasted.

houseKeepingNanoTimeBudget

Number of nanoseconds used for each housekeeping cycle. However, no matter how low the number is, one item of work will always be completed. But if there is nothing to clean up, no processor time will be wasted. Default is 10000000 (10 million nanoseconds = 10 milliseconds = 0.01 seconds). However, no matter how small the time is, one item is done at least. This is to avoid no-ops, if a too small time window is configured. This time budget is a "best effort" threshold, meaning when at 1ns left, a huge file has to be cleaned or the references of a huge collection have to be marked for GC, then this budget can be exceeded considerably.

Housekeeping

dataFileDissolveRatio

The degree of the data payload of a storage file to avoid cleaning it up. There are logical "gaps" in database files, byte ranges of records which were replaced with newer versions of them in subsequent database files. These gaps can be removed to keep the used disk space at a minimum. A value of 1 means: Even at the smallest gap clean up the file. A value of 0 means: Gaps don't matter, never clean up anything. All live data in a file is copied to a current head file. Then the source file only consists of gaps and can be deleted without loss of data.

dataFileMinSize

Minimum file size in bytes of a storage file to avoid merging with other files during housekeeping. Must be greater than 1, maximum is 2GB.

dataFileMaxSize

Maximum file size in bytes of a storage file to avoid splitting in more files during housekeeping. Must be greater than 1, maximum is 2GB.

Due to internal implementation details files larger than 2GB are not supported!

Involved Types

This list shows which property configures which type, used by the foundation types, to create the storage manager.

Property	Used by
baseDirectory	StorageFileProvider
deletionDirectory	StorageFileProvider
truncationDirectory	StorageFileProvider
backupDirectory	StorageBackupSetup
channelCount	StorageChannelCountProvider
channelDirectoryPrefix	StorageFileProvider
dataFilePrefix	StorageFileProvider
dataFileSuffix	StorageFileProvider
transactionFilePrefix	StorageFileProvider
transactionFileSuffix	StorageFileProvider
typeDictionaryFilename	StorageFileProvider
houseKeepingInterval	StorageHousekeepingController
houseKeepingNanoTimeBudget	StorageHousekeepingController
entityCacheThreshold	StorageEntityCacheEvaluator
entityCacheTimeout	StorageEntityCacheEvaluator
dataFileMinSize	StorageDataFileEvaluator
dataFileMaxSize	StorageDataFileEvaluator
dataFileDissolveRatio	StorageDataFileEvaluator