DatasetFileCache

Description

sealed class Tinman.Terrain.Datasets.DatasetFileCache

Derived from: Disposable ^abstract
IDisposableGeneric<DatasetFileCache>
IFlushable

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 ⁱⁿ : 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.

CreateOrOpen

[OwnerReturn]
public static method CreateOrOpen → (2)

filePath ⁱⁿ : 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 ⁱⁿ : 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

IsReadOnly

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.