BlockStorage

Description

sealed class Tinman.Core.Database.BlockStorage

Derived from: Disposable ^abstract
IBeginEndWrite
IBeginEndSync
IFlushable
ICanReadWrite
IPathInfo

A storage that uses a file and provides a generic allocation mechanism for blocks of persistent memory.

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

Offset     | Type  | Count | Description
-----------+-------+-------+----------------------------------------------------
#0  ..  #7 |  int8 |     8 | Magic value that identifies a file used by a
           |       |       | persistent memory allocator:
           |       |       | 0x89 0x42 0x53 0x54 0x0D 0x0A 0x1A 0x0A
-----------+-------+-------+----------------------------------------------------
#8  ..  #9 | int16 |     1 | Binary format version (currently 1).
-----------+-------+-------+----------------------------------------------------
#10 .. #17 | int64 |     1 | Address of root node of allocations B-Tree, given
           |       |       | as a byte offset relative to file offset #0.
-----------+-------+-------+----------------------------------------------------
#18 .. #25 | int64 |     1 | Address of root node of free-chunks B-Tree, given
           |       |       | as a byte offset relative to file offset #0.
-----------+-------+-------+----------------------------------------------------
#26 .. #31 |  int8 |     6 | Reserved (must be all zero).
-----------+-------+-------+----------------------------------------------------
#32 .. EOF |  int8 |     ? | Data area of block storage.
-----------+-------+-------+----------------------------------------------------

Public / Constructors

Create

[OwnerReturn]
public static method Create → (2)

file ⁱⁿ : IFile ^own: [not-null]
The file to use.
offset ⁱⁿ : int64: [>=0]
File offset of block storage.
returns → BlockStorage: The created BlockStorage object.

Creates a new block storage using the given file.

IOException: If an I/O error has occurred.

New

[OwnerReturn]
public static method New → (3)

create ⁱⁿ : bool: Create a new block storage or open an existing one?
file ⁱⁿ : IFile ^own: [not-null]
The file to use.
offset ⁱⁿ : int64: [>=0]
File offset of block storage.
returns → BlockStorage: The created BlockStorage object.

Creates a new block storage using the given file.

IOException: If an I/O error has occurred.

Open

[OwnerReturn]
public static method Open → (2)

file ⁱⁿ : IFile ^own: [not-null]
The file to use.
offset ⁱⁿ : int64: [>=0]
File offset.
returns → BlockStorage: The created BlockStorage object.

Opens an existing block storage using the given file.

IOException: If an I/O error has occurred.

Public / Methods

Allocate

[BeginWriteEnd]
public method Allocate → (1)

size ⁱⁿ : int64: [>0]
Size of storage memory chunk, in bytes.
returns → int64: The block ID of the allocated chunk.

Allocates a persistent chunk of storage memory.

IOException: If an I/O error has occurred.

AllocateNext

[BeginWriteEnd]
public method AllocateNext → (1)

size ⁱⁿ : int64: [>0]
Size of storage memory chunk, in bytes.
returns → int64: The block ID of the allocated chunk.

Returns the block ID that would be allocated next for the given block size.

This method does not perform any actual allocation. The returned block ID remains valid until IBeginEnd.End resp. IBeginEndWrite.WriteRelinquish is called.

IOException: If an I/O error has occurred.

Blocks

[BeginEnd]
public method Blocks → ()

returns → BlockInfo [ ]: The array of allocation blocks.

Returns a list of all allocation blocks (free + used).

This method is intended for informational and debugging purposes.

IOException: If an I/O error has occurred.

Clear

[BeginWriteEnd]
public method Clear → ()

Clears all data from this block storage, including all block indexes.

IOException: If an I/O error has occurred.

Free

[BeginWriteEnd]
public method Free → (1)

blockId ⁱⁿ : int64: The block ID, as returned by Allocate.

Frees a persistent chunk of storage memory that has been allocated with Allocate

If the given block ID is unknown or invalid, the method returns silently.

IOException: If an I/O error has occurred.

Get

[BeginEnd] [OwnerReturn]
public method Get → (2)

blockId ⁱⁿ : int64: The block ID, as returned by Allocate.
buffer ^opt : ByteBuffer ^own = null: The buffer to use or null to create a new one.
returns → ByteBuffer: The block data or null if blockId ⁱⁿ is DatabaseUtil.InvalidId.

Get all data of the given block.

IOException: If an I/O error has occurred.

Read

[BeginEnd]
public method Read → (5)

blockId ⁱⁿ : int64: The block ID, as returned by Allocate.
offset ⁱⁿ : int64: [>=0]
Offset of first byte to read from block.
buffer ⁱⁿ : ByteBuffer: [not-null]
The output buffer. The ByteBuffer object will not be modified by this method.
bufferOffset ^opt : int32 = -1: [>=-1]
Offset into output buffer ⁱⁿ. If set to -1, the current buffer position (see ByteBuffer.Position) will be used.
count ^opt : int32 = -1: [>=-1]
Total number of bytes to read. If set to -1, the remaining buffer bytes (see ByteBuffer.Remaining) will be used.

Reads a chunk of bytes from the given block.

The maximum number of bytes that can be read with a single call is 2^31-1.

IOException: If an I/O error has occurred.

Set

[BeginWriteEnd]
public method Set → (2)

data ⁱⁿ : ByteBuffer ^own: [not-null]
The new block data.
blockId ^opt : int64 = DatabaseUtil.InvalidId: The block ID, as returned by Allocate, or DatabaseUtil.InvalidId.
returns → int64: The resulting block ID (may be different than blockId ^opt).

Sets all data of the given block.

IOException: If an I/O error has occurred.

Size

[BeginEnd]
public method Size → (1)

blockId ⁱⁿ : int64: The block ID, as returned by Allocate.
returns → int64: The storage block size, in bytes. Will be 0 iff blockId ⁱⁿ does not point to a valid storage block.

Returns the size of the given storage block.

IOException: If an I/O error has occurred.

Write

[BeginEnd]
public method Write → (5)

blockId ⁱⁿ : int64: The block ID, as returned by Allocate.
offset ⁱⁿ : int64: [>=0]
Offset of first byte to read from block.
buffer ⁱⁿ : ByteBuffer: [not-null]
The input buffer. The ByteBuffer object will not be modified by this method.
bufferOffset ^opt : int32 = -1: [>=-1]
Offset into output buffer ⁱⁿ. If set to -1, the current buffer position (see ByteBuffer.Position) will be used.
count ^opt : int32 = -1: [>=-1]
Total number of bytes to read. If set to -1, the remaining buffer bytes (see ByteBuffer.Remaining) will be used.

Writes a chunk of bytes to the given block.

The maximum number of bytes that can be written with a single call is 2^31-1. Writing past the end of the block is not allowed.

IOException: If an I/O error has occurred.