class BlockStorage in Tinman.Core.Database

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

sealed class	BlockStorage	extends	Disposable
		implements	IBeginEndSync
			IBeginEndWrite
			ICanReadWrite
			IFlushable
			IPathInfo

Remarks

The following table shows the binary layout of a block storage (multibyte values are encoded as 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 / Attributes

CanRead

Does this object support read access?

public property	CanRead { get }
type	bool
value		true if this object supports reading, false if not.
implements	ICanReadWrite.CanRead

CanWrite

Does this binary object support write access?

public property	CanWrite { get }
type	bool
value		true if this object supports writing, false if not.
implements	ICanReadWrite.CanWrite

LifecycleState

Returns the lifecycle state of this object.

public virtual property	LifecycleState { get }
type	LifecycleState
value		The lifecycle state.
inherited	Disposable.LifecycleState

PathInfo

Returns a Path object that represents the file path this object is associated with.

public property	PathInfo { get }
type	Path
value	[not-null]	The path info.
implements	IPathInfo.PathInfo

Remarks:

Objects that do not have a meaningful file path association simply return Unknown.

Public / Constructors

Create

Creates a new block storage using the given file.

[OwnerReturn]
public static method	Create ([Owner] IFile file, int64 offset)
type	BlockStorage
params	file	[not-null]	The file to use.
	offset	[>=0]	File offset of block storage.
returns		[not-null]	The created BlockStorage object.

New

Creates a new block storage using the given file.

[OwnerReturn]
public static method	New (bool create, [Owner] IFile file, int64 offset)
type	BlockStorage
params	create		Create a new block storage or open an existing one?
	file	[not-null]	The file to use.
	offset	[>=0]	File offset of block storage.
returns		[not-null]	The created BlockStorage object.

Open

Opens an existing block storage using the given file.

[OwnerReturn]
public static method	Open ([Owner] IFile file, int64 offset)
type	BlockStorage
params	file	[not-null]	The file to use.
	offset	[>=0]	File offset.
returns		[not-null]	The created BlockStorage object.

Public / Methods

AcquireTry

Acquires a strong reference to this disposable object.

[OwnerReturn, ThreadSafe]
public method	AcquireTry ()
type	IDisposable
returns			this if a new strong reference has been acquired, null if this object is already being disposed.
inherited	Disposable.AcquireTry

Remarks:

The object will not be actually disposed by calls to Dispose when there is at least one strong reference left. Code that calls the AcquireTry method is responsible for calling the Dispose method accordingly.

This method is not intended to be used in performance-critical code. It should only be used to high-level resource management.

Allocate

Allocates a persistent chunk of storage memory.

[BeginWriteEnd]
public method	Allocate (int64 size)
type	int64
params	size	[>0]	Size of storage memory chunk, in bytes.
returns		[>=0]	The block ID of the allocated chunk.

AllocateNext

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

[BeginWriteEnd]
public method	AllocateNext (int64 size)
type	int64
params	size	[>0]	Size of storage memory chunk, in bytes.
returns		[>=0]	The block ID of the allocated chunk.

Remarks:

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

AssertReading

Asserts that there is a pending read-only / read-write access to the block storage.

[BeginEnd]
public method	AssertReading (string source)
params	source		Error source tag.

AssertWriting

Asserts that there is a pending read-write access to the block storage.

[BeginEnd]
public method	AssertWriting (string source)
params	source		Error source tag.

Begin

Begins an access to this object.

public method	Begin ()
implements	IBeginEnd.Begin

Remarks:

See the documentation of the class which implements this interface for details on the operations that must be wrapped in Begin and End calls.

See also:

BeginEnd

BeginWrite

Begins an exclusive read-write access.

public method	BeginWrite ()
implements	IBeginEndWrite.BeginWrite

Remarks:

Read-write access is acquired by calling BeginWrite or by calling Begin, followed by a later call to WriteAcquire.

Blocks

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

[BeginEnd]
public method	Blocks ()
type	BlockInfo[]
returns		[not-null]	The array of allocation blocks.

Remarks:

This method is intended for informational and debugging purposes.

Clear

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

[BeginWriteEnd]
public method	Clear ()

Dispose

Releases all resources held by this object if there are no more strong references to it, decrements the reference counter by one otherwise.

[Dispose, OwnerThis, ThreadSafe]
public method	Dispose ()
inherited	Disposable.Dispose

Remarks:

The Dispose method silently returns if the object has already been disposed.

End

Ends the current access to this object.

public method	End ()
implements	IBeginEnd.End

Remarks:

See the documentation of the class which implements this interface for details on the operations that must be wrapped in Begin and End calls.

See also:

BeginEnd

Flush

Flushes all cached data.

public method	Flush ()
implements	IFlushable.Flush

Remarks:

Performing a flush may result in I/O work. Depending on the semantics of the implementing class, this work may need to be wrapped in special Begin / End method calls. See the documentation of the implementing classes for details.

In case this object represents a read-only resource, calling the Flush method has no effect.

Free

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

[BeginWriteEnd]
public method	Free (int64 blockId)
params	blockId		The block ID, as returned by Allocate.

Remarks:

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

Get

Get all data of the given block.

[BeginEnd, OwnerReturn]
public method	Get (int64 blockId)
type	ByteBuffer
params	blockId		The block ID, as returned by Allocate.
returns			The block data or null if blockId is InvalidId.

NotifyWaiting

Notifies all threads currently blocked in a call to WaitForNotify.

public method	NotifyWaiting ()
implements	IBeginEndSync.NotifyWaiting

Read

Reads a chunk of bytes from the given block.

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

Remarks:

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

Set

Sets all data of the given block.

[BeginWriteEnd, OwnerReturn]
public method	Set ([Owner] ByteBuffer data, int64 blockId = DatabaseUtil.InvalidId)
type	int64
params	data	[not-null]	The new block data.
	blockId		The block ID, as returned by Allocate, or InvalidId. Defaults to InvalidId.
returns			The resulting block ID (may be different than blockId).

Size

Returns the size of the given storage block.

[BeginEnd]
public method	Size (int64 blockId)
type	int64
params	blockId		The block ID, as returned by Allocate.
returns		[>=0]	The storage block size, in bytes. Will be 0 iff blockId does not point to a valid storage block.

WaitForNotify

Waits until one of the events described below takes place and reacquires the lock on this monitor.

public method	WaitForNotify (int32 timeout = 50)
params	timeout	[>0]	The timeout value, in milliseconds. Defaults to 50.
implements	IBeginEndSync.WaitForNotify

Remarks:

The calling thread will be blocked until one of the following events takes place:

• Another thread calls the NotifyWaiting method on this monitor.
• The timeout has elapsed.

Exceptions:

• InvalidArgumentException:
  If one of the parameters is invalid.

Write

Writes a chunk of bytes to the given block.

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

Remarks:

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.

WriteAcquire

Acquires read-write access for the current read-only access.

[BeginEnd]
public method	WriteAcquire ()
implements	IBeginEndWrite.WriteAcquire

Remarks:

After calling Begin, read-only access is allowed on the block storage. By calling the WriteAcquire method, the access is turned into read-write access (blocking may be necessary for this).

See also:

IBeginEndWrite.WriteRelinquish

WriteRelinquish

Returns to read-only access from the current read-write access.

[BeginEnd]
public method	WriteRelinquish ()
implements	IBeginEndWrite.WriteRelinquish

See also:

IBeginEndWrite.WriteAcquire