Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

Prime Cache at Server Startup

This feature is new with V13.

FairCom Server technology supports configuration options that are used to prime the server's data and index caches when the server starts up. The functionality is similar to cache priming configuration options PRIME_CACHE, PRIME_CACHE_BY_KEY, and PRIME_INDEX, except that those options take effect only when an application opens the files.

This feature relies on atomic operations. If atomic operation support is off at compile time, the feature will be disabled.

The new configuration options are specified in JSON format, such as in the following example:

subsystem cache prime_cache_at_startup {

"allow_connections": true,

"thread_count": 8,

"prime_cache": [

{"file": "filename1.dat", "size": "1 gb"},

{"file": "filename2.dat"}

],

"prime_cache_by_key": [

{"file": "filename1.dat", "size" : "1 gb", "index": 1, "reverse": false},

{"file": "filename2.dat", "size" : "1 gb", "index": 1}

],

"prime_index": [

{"file": "filename1.dat", "size": "1 gb", "index": 1},

{"file": "filename2.dat", "size": "1 gb", "index": 1}

]

}

Supported attributes:

  • allow_connections is a boolean value that indicates if connections to the server are allowed while the cache priming is performed at server startup. Defaults to false.
  • thread_count is an integer value that sets the number of threads to use to prime the cache. It defaults to 4. Maximum is 255.
  • prime_cache is an array of names of data files that are to be read into the cache in physical order, and an optional size indicating the maximum number of bytes to read into data cache for the file. The file name is a string. The file name can include wildcard characters (for example, *.dat). The wildcard characterdoes not recurse into subdirectories. The size can include a suffix, such as kb, mb, gb, tb (for example, "1 gb"). If size is not specified, the entire file is read into the data cache.
  • prime_cache_by_key is an array of names of data files that are to be read into the cache in the order of the specified index. The index number is a positive value, where 1 means the first index. If the index number is omitted, the first index is used. Size has the same definition as for prime_cache. Reverse is a boolean indicating whether the key traversal is in ascending or descending key order.
  • prime_index is an array of names of index files that are to be read into the index cache. Size and index have the same meaning as for prime_cache_by_key.

In addition to the specified size limits, the data and index cache sizes limit the cache priming as follows:

prime_cache and prime_cache_by_key stop if the data cache becomes full.

prime_index stops if the index cache becomes full.

The SUBSYSTEM CACHE PRIME_CACHE_AT_STARTUP configuration option can be specified in a server settings file. If it is used in a settings file, the option cannot also be used in the configuration file. In that case, the subsystem is considered blocked and the configuration file options are ignored. Likewise, if this subsystem is specified more than once in the configuration file, only the first occurrence of the subsystem block takes effect. The other occurrences are ignored.

The subsystem can be commented out by placing a semicolon at the start of the SUBSYSTEM line. However, individual lines within the subsystem block cannot be commented out. Attempting to do so will cause a syntax error.

By default, the server logs information about the files that it loads into cache to CTSTATUS.FCS. The configuration option CTSTATUS_MASK PRIME_CACHE_AT_STARTUP can be used to disable this logging.

TOCIndex