Class PinnableSlice

Namespace

RocksDbNet

Assembly

RocksDb.Net.dll

A value read from the database without copying it into managed memory. Maps to rocksdb_pinnableslice_t.

public sealed class PinnableSlice : RocksDbHandle, IDisposable

Inheritance

object

RocksDbHandle

PinnableSlice

Implements

IDisposable

Inherited Members

RocksDbHandle.Handle

RocksDbHandle.Owned

RocksDbHandle.IsDisposed

RocksDbHandle.ThrowIfDisposed()

RocksDbHandle.Dispose()

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

An ordinary Get(ReadOnlySpan<byte>, ReadOptions?) copies twice: RocksDb allocates a copy of the value, and the wrapper copies that into a managed array. This copies neither. When the value is served from the block cache, Value points straight at the cached block.

The trade is that the value stays pinned until this object is disposed, so dispose it promptly. While it lives it holds a reference to the block it came from, which cannot be evicted and still counts against the cache's capacity. Holding many of these, or holding one for a long time, degrades the cache.

Value is only valid until disposal. Copy it with ToArray() if it needs to outlive this object. The instance keeps the database alive, so it cannot be invalidated by the database being collected, but it does not survive the database being disposed explicitly: see the remarks on Value.

Properties

Length

Length of the value in bytes.

public int Length { get; }

Property Value

int

Exceptions

ObjectDisposedException

This instance has been disposed.

Value

The value, without a copy.

public ReadOnlySpan<byte> Value { get; }

Property Value

ReadOnlySpan<byte>

Remarks

Valid until this instance is disposed, and no longer. It also does not survive the database being disposed first: the memory may belong to a block cache that the database owns, so reading it afterwards reads freed memory. Dispose this before the database, which the using pattern gives you for free when both are locals.

Exceptions

ObjectDisposedException

This instance has been disposed.

Methods

DisposeHandle()

Releases the native handle. Called during disposal.

protected override void DisposeHandle()

Remarks

Protected rather than public: it destroys the native object without marking this instance disposed or clearing the handle, so calling it from outside and then disposing normally would free the same pointer twice. It was the most Dispose-looking member on the type. Callers want Dispose().

ToArray()

Copies the value into a new managed array.

public byte[] ToArray()

Returns

byte[]

Remarks

Use this when the value has to outlive the slice. It costs the copy that the pinned read exists to avoid, so prefer reading Value directly where the lifetime allows.

ToUtf8String()

Decodes the value as UTF-8.

public string ToUtf8String()

Returns

string