Interface IZoneTree<TKey, TValue>

The interface for the core functionality of a ZoneTree.

Inherited Members

IDisposable.Dispose()

Namespace: Tenray.ZoneTree

Assembly: ZoneTree.dll

Syntax

public interface IZoneTree<TKey, TValue> : IDisposable

Type Parameters

Name	Description
TKey	The key type
TValue	The value type

Properties

Comparer

The key comparer.

Declaration

IRefComparer<TKey> Comparer { get; }

Property Value

Type	Description
IRefComparer<TKey>

IsReadOnly

Enables read-only mode.

Declaration

bool IsReadOnly { get; set; }

Property Value

Type	Description
bool

KeySerializer

The key serializer.

Declaration

ISerializer<TKey> KeySerializer { get; }

Property Value

Type	Description
ISerializer<TKey>

Logger

ZoneTree Logger.

Declaration

ILogger Logger { get; }

Property Value

Type	Description
ILogger

Maintenance

Returns maintenance object belongs to this ZoneTree.

Declaration

IZoneTreeMaintenance<TKey, TValue> Maintenance { get; }

Property Value

Type	Description
IZoneTreeMaintenance<TKey, TValue>

ValueSerializer

The value serializer.

Declaration

ISerializer<TValue> ValueSerializer { get; }

Property Value

Type	Description
ISerializer<TValue>

Methods

AtomicUpsert(in TKey, in TValue)

Adds or updates the specified key/value pair atomically across LSM-Tree segments.

Declaration

void AtomicUpsert(in TKey key, in TValue value)

Parameters

Type	Name	Description
TKey	key	The key of the element to upsert.
TValue	value	The value of the element to upsert.

ContainsKey(in TKey)

Checks the existence of the key in the tree.

Declaration

bool ContainsKey(in TKey key)

Parameters

Type	Name	Description
TKey	key	The key of the element.

Returns

Type	Description
bool	true if key is found in tree; otherwise, false

Count()

Counts Keys in the entire database. This operation scans the in-memory segments and queries the disk segment.

Declaration

long Count()

Returns

Type	Description
long	Number of the valid records in the tree.

CountFullScan()

Counts Keys in the entire database with a full scan.

Declaration

long CountFullScan()

Returns

Type	Description
long	Number of the valid records in the tree.

Remarks

In regular cases, the disk segment does not contain deleted records. However, TTL or custom deletion logic would let the disk segment contains deleted records. In that case, a full scan is required for the count.

CreateIterator(IteratorType, bool)

Creates an iterator that enables scanning of the entire database.

Declaration

IZoneTreeIterator<TKey, TValue> CreateIterator(IteratorType iteratorType = IteratorType.AutoRefresh, bool includeDeletedRecords = false)

Parameters

Type	Name	Description
IteratorType	iteratorType	Defines iterator type.
bool	includeDeletedRecords	if true the iterator retrieves the deleted and normal records

Returns

Type	Description
IZoneTreeIterator<TKey, TValue>	ZoneTree Iterator

Remarks

The iterator might or might not retrieve newly inserted elements. This depends on the iterator's internal segment iterator positions.

If the newly inserted or deleted key is after the internal segment iterator position, the new data is included in the iteration.

Iterators are lightweight. Create them when you need and dispose them when you dont need. Iterators acquire locks on the disk segment and prevents its disposal.

Use snapshot iterators for consistent view by ignoring new writes.

CreateMaintainer()

Creates the default ZoneTree Maintainer.

Declaration

IMaintainer CreateMaintainer()

Returns

Type	Description
IMaintainer

CreateReverseIterator(IteratorType, bool)

Creates a reverse iterator that enables scanning of the entire database.

Declaration

IZoneTreeIterator<TKey, TValue> CreateReverseIterator(IteratorType iteratorType = IteratorType.AutoRefresh, bool includeDeletedRecords = false)

Parameters

Type	Name	Description
IteratorType	iteratorType	Defines iterator type.
bool	includeDeletedRecords	if true the iterator retrieves the deleted and normal records

Returns

Type	Description
IZoneTreeIterator<TKey, TValue>	ZoneTree Iterator

Remarks

ZoneTree iterator direction does not hurt performance. Forward and backward iterator's performances are equal.

ForceDelete(in TKey)

Deletes the specified key regardless of existence. (hint: LSM Tree delete is an insert) This is faster than TryDelete because it does not check existence in all layers. It increases the data lake size.

Declaration

void ForceDelete(in TKey key)

Parameters

Type	Name	Description
TKey	key	The key of the element to delete.

TryAtomicAdd(in TKey, in TValue)

Attempts to add the specified key and value atomically across LSM-Tree segments.

Declaration

bool TryAtomicAdd(in TKey key, in TValue value)

Parameters

Type	Name	Description
TKey	key	The key of the element to add.
TValue	value	The value of the element to add. It can be null.

Returns

Type	Description
bool	true if the key/value pair was added successfully; otherwise, false.

TryAtomicAddOrUpdate(in TKey, in TValue, ValueUpdaterDelegate<TValue>)

Attempts to add or update the specified key and value atomically across LSM-Tree segments.

Declaration

bool TryAtomicAddOrUpdate(in TKey key, in TValue valueToAdd, ValueUpdaterDelegate<TValue> valueUpdater)

Parameters

Type	Name	Description
TKey	key	The key of the element to add.
TValue	valueToAdd	The value of the element to add. It can be null.
ValueUpdaterDelegate<TValue>	valueUpdater	The delegate function that updates the value.

Returns

Type	Description
bool	true if the key/value pair was added; false, if the key/value pair was updated.

TryAtomicGetAndUpdate(in TKey, out TValue, ValueUpdaterDelegate<TValue>)

Tries to get the value of the given key and updates the value atomically using value updater if found any.

Declaration

bool TryAtomicGetAndUpdate(in TKey key, out TValue value, ValueUpdaterDelegate<TValue> valueUpdater)

Parameters

Type	Name	Description
TKey	key	The key of the element.
TValue	value	The value of the element associated with the key.
ValueUpdaterDelegate<TValue>	valueUpdater	The delegate function that updates the value.

Returns

Type	Description
bool	true if the key is found; otherwise, false

TryAtomicUpdate(in TKey, in TValue)

Attempts to update the specified key's value atomically across LSM-Tree segments.

Declaration

bool TryAtomicUpdate(in TKey key, in TValue value)

Parameters

Type	Name	Description
TKey	key	The key of the element to update.
TValue	value	The value of the element to update. It can be null.

Returns

Type	Description
bool	true if the key/value pair was updated successfully; otherwise, false.

TryDelete(in TKey)

Attempts to delete the specified key.

Declaration

bool TryDelete(in TKey key)

Parameters

Type	Name	Description
TKey	key	The key of the element to delete.

Returns

Type	Description
bool	true if the key was found and deleted; false if the key was not found.

TryGet(in TKey, out TValue)

Tries to get the value of the given key.

Declaration

bool TryGet(in TKey key, out TValue value)

Parameters

Type	Name	Description
TKey	key	The key of the element.
TValue	value	The value of the element associated with the key.

Returns

Type	Description
bool	true if the key is found; otherwise, false

TryGetAndUpdate(in TKey, out TValue, ValueUpdaterDelegate<TValue>)

Tries to get the value of the given key and updates the value using value updater if found any.

Declaration

bool TryGetAndUpdate(in TKey key, out TValue value, ValueUpdaterDelegate<TValue> valueUpdater)

Parameters

Type	Name	Description
TKey	key	The key of the element.
TValue	value	The value of the element associated with the key.
ValueUpdaterDelegate<TValue>	valueUpdater	The delegate function that updates the value.

Returns

Type	Description
bool	true if the key is found; otherwise, false

Upsert(in TKey, in TValue)

Adds or updates the specified key/value pair.

Declaration

void Upsert(in TKey key, in TValue value)

Parameters

Type	Name	Description
TKey	key	The key of the element to upsert.
TValue	value	The value of the element to upsert.

Remarks

This is a thread-safe method, but it is not sycnhronized with other atomic add/update/upsert methods. Using the Upsert method in parallel to atomic methods breaks the atomicity of the atomic methods.

For example: TryAtomicAddOrUpdate(key) does the following 3 things within lock to preserve atomicity across segments of LSM-Tree.

1. tries to get the value of the key
2. if it can find the key, it updates the value
3. if it cannot find the key, inserts the new key/value

All atomic methods respect this order using the same lock.

The Upsert method does not respect to the atomicity of atomic methods, because it does upsert without lock.

On the other hand, the Upsert method is atomic in the mutable segment scope but not across all segments. This makes Upsert method thread-safe.

This is the fastest add or update function.