DatasetFileCache

Description

sealed class Tinman.Terrain.Datasets.DatasetFileCache

An file-based cache for IDatasets.

Dataset file caches can be shared between multiple processes resp. machines, with the restriction that all shared dataset file caches must be opened read-only mode (see Open), which implies that the shared dataset file cache must have been warmed up in a pre-processing step.

The following table shows the binary layout of a dataset cache (multibyte values are encoded as ByteOrder.LittleEndian).

Offset     | Type  | Count | Description
-----------+-------+-------+----------------------------------------------------
#0  ..  #7 |  int8 |     8 | Magic value that identifies a file used by a
           |       |       | dataset cache:
           |       |       | 0x89 0x48 0x47 0x43 0x0D 0x0A 0x1A 0x0A
-----------+-------+-------+----------------------------------------------------
#8  ..  #9 | int16 |     1 | Binary format version (currently 1).
-----------+-------+-------+----------------------------------------------------
#10 .. #17 | int64 |     1 | Maximum file size, in bytes.
-----------+-------+-------+----------------------------------------------------
#18 .. #39 |  int8 |    22 | Reserved (must be all zero).
-----------+-------+-------+----------------------------------------------------
#40 .. #47 | int64 |     1 | Block ID of root of primary block index.
-----------+-------+-------+----------------------------------------------------
#48 .. #55 |  int8 |     8 | Reserved, must be zero.
-----------+-------+-------+----------------------------------------------------
#56 .. #63 | int64 |     1 | Block ID of root of timestamp index "LastUsed".
-----------+-------+-------+----------------------------------------------------
#64 .. EOF |  int8 |     ? | Data area of dataset cache.
-----------+-------+-------+----------------------------------------------------

The data area of a dataset cache is managed by an embedded BlockStorage.

Public / Constructors

Create


[OwnerReturn]
public static method Create → (2)

filePath in : Path

[not-null]
Path to the cache file.

maximumFileSize opt : int64 = 0

[>=0]
The maximum file size, in bytes. If zero, the file size will be unlimited. Defaults to 0.

returns → DatasetFileCache

The dataset file cache.

Creates a new dataset file cache.

IOException

If an I/O error has occurred.

Create​Or​Open


[OwnerReturn]
public static method CreateOrOpen → (2)

filePath in : Path

[not-null]
Path to the cache file.

maximumFileSize opt : int64 = 0

[>=0]
The maximum file size, in bytes. If zero, the file size will be unlimited. Defaults to 0.

returns → DatasetFileCache

The dataset file cache.

Opens an existing dataset file cache or creates a new one if necessary.

If the given file path points to a non-existent file, a new dataset file cache with the given properties will be created. If the file path refers to an existing dataset file cache, it will be opened iff its properties match maximumFileSize opt- otherwise a new dataset file cache is created and the existing one is overwritten.

IOException

If an I/O error has occurred.

Open


[OwnerReturn]
public static method Open → (2)

filePath in : Path

[not-null]
Path to the cache file.

readOnly opt : bool = false

Open pyramid file cache in read-only mode? Use this for sharing warmed-up file caches between multiple processes or machines.

returns → DatasetFileCache

The dataset file cache.

Opens an existing dataset file cache.

IOException

If an I/O error has occurred.

Public / Methods

Clear


[ThreadSafe]
public method Clear → ()

Clears all cached dataset content from the cache.

IOException

If an I/O error has occurred.

Public / Attributes

Is​Read​Only


public attribute IsReadOnly → (get)

value : bool

true if the dataset file cache is in read-only mode,
false if the dataset file cache is in read-write mode.

Is the dataset file cache in read-only mode?

In read-only mode, the cache file will not be updated. In effect, sample blocks that are not present in the cache will be loaded from the underlying dataset, and the resulting sample block will not be stored in the cache file.