Table of Contents

Class Transaction

Namespace
RocksDbNet
Assembly
RocksDb.Net.dll

A transaction on a TransactionDb. Maps to rocksdb_transaction_t.

public sealed class Transaction : RocksDbHandle, IDisposable
Inheritance
Transaction
Implements
Inherited Members

Remarks

Reads see the transaction's own pending writes as well as the committed database. Writes are buffered until Commit(), and discarded by Rollback().

This is not repeatable read. A plain Get(ReadOnlySpan<byte>, ReadOptions?) takes no lock and is not tracked, so a key can change underneath a transaction between reading it and committing, and nothing reports that. Conflict detection happens when a key is locked, by GetForUpdate(ReadOnlySpan<byte>, bool, ReadOptions?) or by a write, and not at Commit(). A transaction whose correctness depends on what it read has to read for update.

Always dispose it. Neither Commit() nor Rollback() releases the transaction; they only decide what happens to its writes. A transaction that is never disposed keeps its locks.

It must be released before the database. That ordering is enforced rather than merely documented: a transaction keeps its database reachable, and skips its native release once the database has closed. RocksDb's own destructor unlocks keys and unregisters the transaction through the database pointer, so releasing after the close would use freed memory.

Properties

Name

The name this transaction is known by, which is what makes it findable again after a crash.

public string Name { get; set; }

Property Value

string

Remarks

Empty until set. A name has to be given before Prepare(), must be unique among live transactions, and cannot be changed once set.

This is the identifier GetPreparedTransactions() hands back, so it wants to mean something to the recovering process — a message id or a coordinator's transaction id, rather than a counter that restarts with the program.

Exceptions

ArgumentException

value is null or empty.

RocksDbException

The name is already taken, or this transaction already has one.

Methods

Commit()

Applies the transaction's writes to the database.

public void Commit()

Remarks

Conflicts are not detected here. A pessimistic transaction, which is what TransactionDb gives you, takes a lock and checks for a conflicting change when the key is written or read for update, so a conflict has already thrown from Put(ReadOnlySpan<byte>, ReadOnlySpan<byte>) or GetForUpdate(ReadOnlySpan<byte>, bool, ReadOptions?) long before this is called. That is the ordinary outcome to retry.

A key read with a plain Get(ReadOnlySpan<byte>, ReadOptions?) is not tracked and never causes a conflict, whether or not SetSnapshot was used. Measured: a transaction that read a key, watched another transaction change and commit it, and then committed its own unrelated write, committed successfully. Use GetForUpdate for reads a decision depends on.

This does not release the transaction. Dispose it as well.

ContainsKey(ReadOnlySpan<byte>, ColumnFamilyHandle, ReadOptions?)

Returns whether key exists, exactly, without copying its value.

public bool ContainsKey(ReadOnlySpan<byte> key, ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>
cf ColumnFamilyHandle
options ReadOptions

Returns

bool

Remarks

Unlike KeyMayExist, which consults only the bloom filters and can answer yes for a key that is absent, this is a real read and is never wrong. It costs the same as reading the value, less the copy: the value is located and pinned, then released unread.

Exceptions

RocksDbException

The read failed, as opposed to finding nothing.

ContainsKey(ReadOnlySpan<byte>, ReadOptions?)

Returns whether key exists, exactly, without copying its value.

public bool ContainsKey(ReadOnlySpan<byte> key, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>
options ReadOptions

Returns

bool

Remarks

Unlike KeyMayExist, which consults only the bloom filters and can answer yes for a key that is absent, this is a real read and is never wrong. It costs the same as reading the value, less the copy: the value is located and pinned, then released unread.

Exceptions

RocksDbException

The read failed, as opposed to finding nothing.

ContainsKey(string, ColumnFamilyHandle, ReadOptions?)

Returns whether the UTF-8 encoded key exists in cf, exactly.

public bool ContainsKey(string key, ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

key string
cf ColumnFamilyHandle
options ReadOptions

Returns

bool

Remarks

Unlike KeyMayExist, which consults only the bloom filters and can answer yes for a key that is absent, this is a real read and is never wrong. It costs the same as reading the value, less the copy: the value is located and pinned, then released unread.

ContainsKey(string, ReadOptions?)

Returns whether the UTF-8 encoded key exists, exactly.

public bool ContainsKey(string key, ReadOptions? options = null)

Parameters

key string
options ReadOptions

Returns

bool

Remarks

Unlike KeyMayExist, which consults only the bloom filters and can answer yes for a key that is absent, this is a real read and is never wrong. It costs the same as reading the value, less the copy: the value is located and pinned, then released unread.

Delete(ReadOnlySpan<byte>)

Queues a delete of key, taking a lock on it.

public void Delete(ReadOnlySpan<byte> key)

Parameters

key ReadOnlySpan<byte>

Delete(ReadOnlySpan<byte>, ColumnFamilyHandle)

Queues a delete of key, taking a lock on it.

public void Delete(ReadOnlySpan<byte> key, ColumnFamilyHandle cf)

Parameters

key ReadOnlySpan<byte>
cf ColumnFamilyHandle

Delete(string)

Queues a delete of key, taking a lock on it.

public void Delete(string key)

Parameters

key string

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().

DisposeUnmanagedResources()

Releases unmanaged resources used by the current instance.

protected override void DisposeUnmanagedResources()

Remarks

Protected for the same reason as DisposeHandle().

Get(ReadOnlySpan<byte>, ColumnFamilyHandle, ReadOptions?)

Reads a key, seeing this transaction's pending writes, or returns null if it is absent.

public byte[]? Get(ReadOnlySpan<byte> key, ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>
cf ColumnFamilyHandle
options ReadOptions

Returns

byte[]

Remarks

This takes no lock. Use GetForUpdate(ReadOnlySpan<byte>, bool, ReadOptions?) for a read that a later write in the same transaction depends on.

Get(ReadOnlySpan<byte>, ReadOptions?)

Reads a key, seeing this transaction's pending writes, or returns null if it is absent.

public byte[]? Get(ReadOnlySpan<byte> key, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>
options ReadOptions

Returns

byte[]

Remarks

This takes no lock. Use GetForUpdate(ReadOnlySpan<byte>, bool, ReadOptions?) for a read that a later write in the same transaction depends on.

GetForUpdate(ReadOnlySpan<byte>, ColumnFamilyHandle, bool, ReadOptions?)

Reads a key and locks it, so that no other transaction can change it before this one finishes.

public byte[]? GetForUpdate(ReadOnlySpan<byte> key, ColumnFamilyHandle cf, bool exclusive = true, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>

The key to read and lock.

cf ColumnFamilyHandle
exclusive bool

true, the default, takes a write lock. Passing false takes a shared lock, which several transactions may hold at once, so it guards against writers but not against another reader also intending to write.

options ReadOptions

Read options, or null for the defaults.

Returns

byte[]

Remarks

This is the read half of a read-modify-write, and the reason to use a transaction at all. Reading with Get(ReadOnlySpan<byte>, ReadOptions?) and then writing leaves a window in which another transaction can change the value.

Throws if the lock cannot be taken within the timeout, or if SetSnapshot was set and the key has changed since the transaction began. Both are ordinary outcomes to retry, not bugs.

GetForUpdate(ReadOnlySpan<byte>, bool, ReadOptions?)

Reads a key and locks it, so that no other transaction can change it before this one finishes.

public byte[]? GetForUpdate(ReadOnlySpan<byte> key, bool exclusive = true, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>

The key to read and lock.

exclusive bool

true, the default, takes a write lock. Passing false takes a shared lock, which several transactions may hold at once, so it guards against writers but not against another reader also intending to write.

options ReadOptions

Read options, or null for the defaults.

Returns

byte[]

Remarks

This is the read half of a read-modify-write, and the reason to use a transaction at all. Reading with Get(ReadOnlySpan<byte>, ReadOptions?) and then writing leaves a window in which another transaction can change the value.

Throws if the lock cannot be taken within the timeout, or if SetSnapshot was set and the key has changed since the transaction began. Both are ordinary outcomes to retry, not bugs.

GetPinned(ReadOnlySpan<byte>, ColumnFamilyHandle, ReadOptions?)

Reads a key without copying the value into managed memory, or returns null if it is absent.

public PinnableSlice? GetPinned(ReadOnlySpan<byte> key, ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>
cf ColumnFamilyHandle
options ReadOptions

Returns

PinnableSlice

Remarks

Dispose the result promptly: it pins the block the value came from, which cannot be evicted from the block cache while it lives. See PinnableSlice.

GetPinned(ReadOnlySpan<byte>, ReadOptions?)

Reads a key without copying the value into managed memory, or returns null if it is absent.

public PinnableSlice? GetPinned(ReadOnlySpan<byte> key, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>
options ReadOptions

Returns

PinnableSlice

Remarks

Dispose the result promptly: it pins the block the value came from, which cannot be evicted from the block cache while it lives. See PinnableSlice.

GetPinnedForUpdate(ReadOnlySpan<byte>, ColumnFamilyHandle, bool, ReadOptions?)

Reads a key without copying the value, and locks it.

public PinnableSlice? GetPinnedForUpdate(ReadOnlySpan<byte> key, ColumnFamilyHandle cf, bool exclusive = true, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>
cf ColumnFamilyHandle
exclusive bool
options ReadOptions

Returns

PinnableSlice

Remarks

Dispose the result promptly: it pins the block the value came from, which cannot be evicted from the block cache while it lives. See PinnableSlice.

GetPinnedForUpdate(ReadOnlySpan<byte>, bool, ReadOptions?)

Reads a key without copying the value, and locks it.

public PinnableSlice? GetPinnedForUpdate(ReadOnlySpan<byte> key, bool exclusive = true, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>
exclusive bool
options ReadOptions

Returns

PinnableSlice

Remarks

Dispose the result promptly: it pins the block the value came from, which cannot be evicted from the block cache while it lives. See PinnableSlice.

GetString(string, ColumnFamilyHandle, ReadOptions?)

Reads a UTF-8 key as a string, or null if absent.

public string? GetString(string key, ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

key string
cf ColumnFamilyHandle
options ReadOptions

Returns

string

GetString(string, ReadOptions?)

Reads a UTF-8 key as a string, or null if absent.

public string? GetString(string key, ReadOptions? options = null)

Parameters

key string
options ReadOptions

Returns

string

GetStringForUpdate(string, bool, ReadOptions?)

Reads and locks a UTF-8 key.

public string? GetStringForUpdate(string key, bool exclusive = true, ReadOptions? options = null)

Parameters

key string
exclusive bool
options ReadOptions

Returns

string

Merge(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Queues a merge operation on key.

public void Merge(ReadOnlySpan<byte> key, ReadOnlySpan<byte> value)

Parameters

key ReadOnlySpan<byte>
value ReadOnlySpan<byte>

Merge(ReadOnlySpan<byte>, ReadOnlySpan<byte>, ColumnFamilyHandle)

Queues a merge operation on key.

public void Merge(ReadOnlySpan<byte> key, ReadOnlySpan<byte> value, ColumnFamilyHandle cf)

Parameters

key ReadOnlySpan<byte>
value ReadOnlySpan<byte>
cf ColumnFamilyHandle

MultiGet(IReadOnlyList<byte[]>, ColumnFamilyHandle, ReadOptions?)

Reads several keys in one call, seeing this transaction's pending writes.

public byte[]?[] MultiGet(IReadOnlyList<byte[]> keys, ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

keys IReadOnlyList<byte[]>
cf ColumnFamilyHandle
options ReadOptions

Returns

byte[][]

Remarks

One native call instead of one per key. A missing key yields null in the corresponding position.

This takes no locks, exactly like Get(ReadOnlySpan<byte>, ReadOptions?). Use MultiGetForUpdate(IReadOnlyList<byte[]>, ReadOptions?) for reads a later write depends on.

MultiGet(IReadOnlyList<byte[]>, ReadOptions?)

Reads several keys in one call, seeing this transaction's pending writes.

public byte[]?[] MultiGet(IReadOnlyList<byte[]> keys, ReadOptions? options = null)

Parameters

keys IReadOnlyList<byte[]>
options ReadOptions

Returns

byte[][]

Remarks

One native call instead of one per key. A missing key yields null in the corresponding position.

This takes no locks, exactly like Get(ReadOnlySpan<byte>, ReadOptions?). Use MultiGetForUpdate(IReadOnlyList<byte[]>, ReadOptions?) for reads a later write depends on.

MultiGet(IReadOnlyList<byte[]>, IReadOnlyList<ColumnFamilyHandle>, ReadOptions?)

Reads several keys in one call, each from the column family at the same position in columnFamilies.

public byte[]?[] MultiGet(IReadOnlyList<byte[]> keys, IReadOnlyList<ColumnFamilyHandle> columnFamilies, ReadOptions? options = null)

Parameters

keys IReadOnlyList<byte[]>
columnFamilies IReadOnlyList<ColumnFamilyHandle>
options ReadOptions

Returns

byte[][]

Remarks

One native call instead of one per key. A missing key yields null in the corresponding position.

This takes no locks, exactly like Get(ReadOnlySpan<byte>, ReadOptions?). Use MultiGetForUpdate(IReadOnlyList<byte[]>, ReadOptions?) for reads a later write depends on.

Exceptions

ArgumentException

The two lists are of different lengths.

MultiGetForUpdate(IReadOnlyList<byte[]>, ColumnFamilyHandle, ReadOptions?)

Reads several keys in one call and locks every one of them.

public byte[]?[] MultiGetForUpdate(IReadOnlyList<byte[]> keys, ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

keys IReadOnlyList<byte[]>

Keys to read and lock.

cf ColumnFamilyHandle
options ReadOptions

Read options, or null for the defaults.

Returns

byte[][]

Remarks

The batched form of GetForUpdate(ReadOnlySpan<byte>, bool, ReadOptions?), and the more useful half of this pair: a transaction that reads a set of keys it intends to write is exactly the case conflict detection is for, and locking them one at a time is the slowest way to do it.

Every key is locked, including ones that turn out to be absent. If any key cannot be locked the call throws, and the locks it did take stay held until the transaction ends — locking is not rolled back.

The locks are always exclusive. Unlike GetForUpdate(ReadOnlySpan<byte>, bool, ReadOptions?) there is no shared-lock form, because the C API's batched variant takes no such flag; a shared lock on a set of keys means reading them one at a time.

MultiGetForUpdate(IReadOnlyList<byte[]>, ReadOptions?)

Reads several keys in one call and locks every one of them.

public byte[]?[] MultiGetForUpdate(IReadOnlyList<byte[]> keys, ReadOptions? options = null)

Parameters

keys IReadOnlyList<byte[]>

Keys to read and lock.

options ReadOptions

Read options, or null for the defaults.

Returns

byte[][]

Remarks

The batched form of GetForUpdate(ReadOnlySpan<byte>, bool, ReadOptions?), and the more useful half of this pair: a transaction that reads a set of keys it intends to write is exactly the case conflict detection is for, and locking them one at a time is the slowest way to do it.

Every key is locked, including ones that turn out to be absent. If any key cannot be locked the call throws, and the locks it did take stay held until the transaction ends — locking is not rolled back.

The locks are always exclusive. Unlike GetForUpdate(ReadOnlySpan<byte>, bool, ReadOptions?) there is no shared-lock form, because the C API's batched variant takes no such flag; a shared lock on a set of keys means reading them one at a time.

MultiGetForUpdate(IReadOnlyList<byte[]>, IReadOnlyList<ColumnFamilyHandle>, ReadOptions?)

Reads several keys in one call and locks every one of them.

public byte[]?[] MultiGetForUpdate(IReadOnlyList<byte[]> keys, IReadOnlyList<ColumnFamilyHandle> columnFamilies, ReadOptions? options = null)

Parameters

keys IReadOnlyList<byte[]>

Keys to read and lock.

columnFamilies IReadOnlyList<ColumnFamilyHandle>
options ReadOptions

Read options, or null for the defaults.

Returns

byte[][]

Remarks

The batched form of GetForUpdate(ReadOnlySpan<byte>, bool, ReadOptions?), and the more useful half of this pair: a transaction that reads a set of keys it intends to write is exactly the case conflict detection is for, and locking them one at a time is the slowest way to do it.

Every key is locked, including ones that turn out to be absent. If any key cannot be locked the call throws, and the locks it did take stay held until the transaction ends — locking is not rolled back.

The locks are always exclusive. Unlike GetForUpdate(ReadOnlySpan<byte>, bool, ReadOptions?) there is no shared-lock form, because the C API's batched variant takes no such flag; a shared lock on a set of keys means reading them one at a time.

Exceptions

ArgumentException

The two lists are of different lengths.

NewIterator(ColumnFamilyHandle, ReadOptions?)

Creates an iterator over the database plus this transaction's pending writes.

public Iterator NewIterator(ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

cf ColumnFamilyHandle
options ReadOptions

Returns

Iterator

Remarks

The iterator is invalidated by Commit(), Rollback() and RollbackToSavePoint(). Those dispose any iterator still open, so using one afterwards throws ObjectDisposedException rather than reading freed memory.

NewIterator(ReadOptions?)

Creates an iterator over the database plus this transaction's pending writes.

public Iterator NewIterator(ReadOptions? options = null)

Parameters

options ReadOptions

Returns

Iterator

Remarks

The iterator is invalidated by Commit(), Rollback() and RollbackToSavePoint(). Those dispose any iterator still open, so using one afterwards throws ObjectDisposedException rather than reading freed memory.

Prepare()

Makes this transaction's writes durable without committing them, so that it survives a crash and can be resolved afterwards.

public void Prepare()

Remarks

The first half of two-phase commit. After this returns, the transaction is on disk in a prepared state: a later Commit() applies it and Rollback() discards it, and if the process dies in between, GetPreparedTransactions() finds it again in the reopened database. Without preparing, an interrupted transaction is simply gone.

A prepared transaction holds its locks until it is resolved, including across the restart. Recovery that never commits or rolls one back leaves those keys locked against every other writer.

Exceptions

RocksDbException

The transaction has no Name, or is not in a state that can be prepared.

Put(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Queues a write of key, taking a lock on it.

public void Put(ReadOnlySpan<byte> key, ReadOnlySpan<byte> value)

Parameters

key ReadOnlySpan<byte>
value ReadOnlySpan<byte>

Put(ReadOnlySpan<byte>, ReadOnlySpan<byte>, ColumnFamilyHandle)

Queues a write of key, taking a lock on it.

public void Put(ReadOnlySpan<byte> key, ReadOnlySpan<byte> value, ColumnFamilyHandle cf)

Parameters

key ReadOnlySpan<byte>
value ReadOnlySpan<byte>
cf ColumnFamilyHandle

Put(string, string)

Queues a write of a UTF-8 key and value.

public void Put(string key, string value)

Parameters

key string
value string

Put(string, string, ColumnFamilyHandle)

Queues a write of a UTF-8 key and value.

public void Put(string key, string value, ColumnFamilyHandle cf)

Parameters

key string
value string
cf ColumnFamilyHandle

PutLogData(ReadOnlySpan<byte>)

Writes a blob to the write-ahead log alongside this transaction's writes, without storing it in the database.

public void PutLogData(ReadOnlySpan<byte> blob)

Parameters

blob ReadOnlySpan<byte>

The data to log. Copied.

Remarks

For marking a transaction in the log for a change-data-capture reader, which sees it through Entries() on the batches GetUpdatesSince(ulong, WalReadOptions?) returns, as PutLogData(ReadOnlySpan<byte>) does for an ordinary batch. The blob is logged when the transaction commits, and not at all if it rolls back.

RebuildFromWriteBatch(WriteBatch)

Applies every operation in batch to this transaction, as if each had been made on it directly.

public void RebuildFromWriteBatch(WriteBatch batch)

Parameters

batch WriteBatch

Remarks

Each write takes its lock as it would through Put(ReadOnlySpan<byte>, ReadOnlySpan<byte>), so this can fail part-way on a lock timeout or conflict, leaving the operations before it applied. The batch is copied from, not consumed.

RebuildFromWriteBatch(WriteBatchWithIndex)

Applies every operation in batch to this transaction, as if each had been made on it directly.

public void RebuildFromWriteBatch(WriteBatchWithIndex batch)

Parameters

batch WriteBatchWithIndex

Remarks

Each write takes its lock as it would through Put(ReadOnlySpan<byte>, ReadOnlySpan<byte>), so this can fail part-way on a lock timeout or conflict, leaving the operations before it applied. The batch is copied from, not consumed.

Rollback()

Discards the transaction's writes and releases its locks.

public void Rollback()

Remarks

This does not release the transaction. Dispose it as well.

RollbackToSavePoint()

Discards everything queued since the last SetSavePoint().

public void RollbackToSavePoint()

Remarks

Invalidates any open iterator, so those are disposed first.

SetSavePoint()

Marks a point that RollbackToSavePoint() can return to.

public void SetSavePoint()

TryGet<T>(ReadOnlySpan<byte>, ColumnFamilyHandle, ValueDecoder<T>, out T, ReadOptions?)

Reads key and decodes its value in place, without copying it into a managed array.

public bool TryGet<T>(ReadOnlySpan<byte> key, ColumnFamilyHandle cf, ValueDecoder<T> decode, out T value, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>

The key to read.

cf ColumnFamilyHandle
decode ValueDecoder<T>

Turns the value into a T. The span it is given is valid only until it returns. Not called when the key is absent.

value T

The decoded value, when the key was found.

options ReadOptions

Read options, or null for the defaults.

Returns

bool

true if the key was found.

Type Parameters

T

What the value decodes to.

Remarks

The value is read through a pinned slice and released once decode returns, or throws; an exception from the decoder reaches the caller unchanged. Compared with decoding the array Get returns, this saves allocating and copying the value.

A static lambda allocates nothing. A decoder that needs state, such as serializer options, can take it through the overload with a state argument instead of capturing it.

Exceptions

RocksDbException

The read failed, as opposed to finding nothing.

TryGet<T>(ReadOnlySpan<byte>, ValueDecoder<T>, out T, ReadOptions?)

Reads key and decodes its value in place, without copying it into a managed array.

public bool TryGet<T>(ReadOnlySpan<byte> key, ValueDecoder<T> decode, out T value, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>

The key to read.

decode ValueDecoder<T>

Turns the value into a T. The span it is given is valid only until it returns. Not called when the key is absent.

value T

The decoded value, when the key was found.

options ReadOptions

Read options, or null for the defaults.

Returns

bool

true if the key was found.

Type Parameters

T

What the value decodes to.

Remarks

The value is read through a pinned slice and released once decode returns, or throws; an exception from the decoder reaches the caller unchanged. Compared with decoding the array Get returns, this saves allocating and copying the value.

A static lambda allocates nothing. A decoder that needs state, such as serializer options, can take it through the overload with a state argument instead of capturing it.

Exceptions

RocksDbException

The read failed, as opposed to finding nothing.

TryGet<TState, T>(ReadOnlySpan<byte>, ColumnFamilyHandle, TState, ValueDecoder<TState, T>, out T, ReadOptions?)

Reads key and decodes its value in place, passing state to the decoder rather than having it captured.

public bool TryGet<TState, T>(ReadOnlySpan<byte> key, ColumnFamilyHandle cf, TState state, ValueDecoder<TState, T> decode, out T value, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>

The key to read.

cf ColumnFamilyHandle
state TState

Passed to decode unchanged.

decode ValueDecoder<TState, T>

Turns the value into a T. The span it is given is valid only until it returns. Not called when the key is absent.

value T

The decoded value, when the key was found.

options ReadOptions

Read options, or null for the defaults.

Returns

bool

true if the key was found.

Type Parameters

TState

The state the decoder needs.

T

What the value decodes to.

Remarks

The value is read through a pinned slice and released once decode returns, or throws; an exception from the decoder reaches the caller unchanged. Compared with decoding the array Get returns, this saves allocating and copying the value.

A static lambda allocates nothing. A decoder that needs state, such as serializer options, can take it through the overload with a state argument instead of capturing it.

Exceptions

RocksDbException

The read failed, as opposed to finding nothing.

TryGet<TState, T>(ReadOnlySpan<byte>, TState, ValueDecoder<TState, T>, out T, ReadOptions?)

Reads key and decodes its value in place, passing state to the decoder rather than having it captured.

public bool TryGet<TState, T>(ReadOnlySpan<byte> key, TState state, ValueDecoder<TState, T> decode, out T value, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>

The key to read.

state TState

Passed to decode unchanged.

decode ValueDecoder<TState, T>

Turns the value into a T. The span it is given is valid only until it returns. Not called when the key is absent.

value T

The decoded value, when the key was found.

options ReadOptions

Read options, or null for the defaults.

Returns

bool

true if the key was found.

Type Parameters

TState

The state the decoder needs.

T

What the value decodes to.

Remarks

The value is read through a pinned slice and released once decode returns, or throws; an exception from the decoder reaches the caller unchanged. Compared with decoding the array Get returns, this saves allocating and copying the value.

A static lambda allocates nothing. A decoder that needs state, such as serializer options, can take it through the overload with a state argument instead of capturing it.

Exceptions

RocksDbException

The read failed, as opposed to finding nothing.

Edit this page