VersionedFileSystem

Description

sealed class Tinman.Core.IO.Files.VersionedFileSystem

Derived from

FileSystem abstract

A versioned file system.

The VersionedFileSystem is an implementation of the IFileSystem interface that provides a read-only view into a virtual filesystem, which based on a versioned content repository, see Repository). Please be aware that this class does not implement a version control system (like Git or SVN). Instead, it provides a simple mechanism for building a versioned filesystem and accessing files for individual versions.

Public / Constructors

Versioned​File​System

public constructor VersionedFileSystem → (3)

root in : string

[not-empty]
The root selector of the versioned filesystem.

repository in : Path

[not-null]
The content repository of the versioned filesystem. Write access to the content repository is only performed during calls to Commit. All other accesses are read-only.

version opt : int32 = 0

[>=0]
The requested filesystem version, see Version. If 0, the most recent version in the content repository is used and Commit is enabled. Otherwise, trying to commit a new version will always fail with a IOException, even if the most recent version has been passed to this parameter. The given version is clamped, so passing Maths.MaxInt will use the most recent version while disabling Commit.

Creates a new instance of VersionedFileSystem.

The Refresh method will be called lazily upon the first filesystem access. To catch potential filesystem errors early, it may also be called right after creating a VersionedFileSystem object.

Public / Methods

Commit

public method Commit → (1)

content in : Path

[not-null]
The content directory to use for creating a new filesystem version.

returns → int32

[Version..Version+1] The resulting filesystem version.

Updates the metadata of the versioned filesystem and optionally creates a new version based on the given content.

Calling this method may cause write accesses into Repository. In all other cases, the VersionedFileSystem class performs read-only accesses. If CanCommit returns false, this method will always throw.

IOException

If an I/O error has occurred.

See also

VersionedFileSystem.CanCommit

Refresh

public method Refresh → ()

Refreshes the metadata of this versioned filesystem.

The refreshed metadata is kept in memory. To write the metadata files, call Commit, passing null.

IOException

If an I/O error has occurred.

See also

VersionedFileSystem.Repository

Public / Attributes

Can​Commit

[Constant]
public attribute CanCommit → (get)

value : bool

true if Commit may be used,
false if it cannot be used and will always throw.

Can Commit be used to create new filesystem versions?

Repository

[Constant]
public attribute Repository → (get)

value : Path

[not-null]
The canonical path to the storage repository.

Returns the storage repository of this versioned file system.

The storage repository is populated with content using the following directory structure:

  • 0/
    The special version 0 holds the temporary version that has not yet been assigned a version number because it is still being processed by Commit.

  • N/
    For each version N (always greater than or equal to 1), a corresponding directory in the repository holds only the content that is different from the previous version.

A version N stores only the differences to its previous version N-1. When a file is requested for version N, the following logic is used to find the content file in the repository:

  1. If a content file exists in the version directory, use that file. Otherwise, continue with 2.

  2. If a deletion placeholder for the content file exists in the version directory, fail with a IOError.NotFound error. Otherwise, continue with 3.

  3. If N = 1, fail with a IOError.NotFound error. Otherwise, continue with 4.

  4. Set N to N - 1 and continue with 1.

A deletion placeholder is a file with the same name but prefixed with '!'. This implies that regular content files with such a name cannot be used. The presence of a directory for version N is determined by whether it contains at least one file of the same version, which means that empty directories cannot be used.

Version

public attribute Version → (get)

value : int32

[>=0]
The current filesystem version. Will be 0 iff there are no versions yet.

Returns the current version of the filesystem.

The version increases when Commit is called and one or more file changes have occurred.

IOException

If an I/O error has occurred.

See also

VersionedFileSystem.Repository