BlockStorage

Description

sealed class Tinman.Core.Database.BlockStorage

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 in : IFile own

[not-null]
The file to use.

offset in : 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 in : bool

Create a new block storage or open an existing one?

file in : IFile own

[not-null]
The file to use.

offset in : 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 in : IFile own

[not-null]
The file to use.

offset in : 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 in : 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.

Allocate​Next


[BeginWriteEnd]
public method AllocateNext → (1)

size in : 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 in : 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 in : 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 in 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 in : int64

The block ID, as returned by Allocate.

offset in : int64

[>=0]
Offset of first byte to read from block.

buffer in : 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 in. 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 in : 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 in : int64

The block ID, as returned by Allocate.

returns → int64

The storage block size, in bytes. Will be 0 iff blockId in 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 in : int64

The block ID, as returned by Allocate.

offset in : int64

[>=0]
Offset of first byte to read from block.

buffer in : 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 in. 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.