Table of Contents

Class RocksDbHandle

Namespace
RocksDbNet
Assembly
RocksDb.Net.dll

Abstract base class for all managed wrappers around native RocksDb handles. Provides deterministic disposal via IDisposable and a GC finalizer safety net.

public abstract class RocksDbHandle : IDisposable
Inheritance
RocksDbHandle
Implements
Derived
Inherited Members

Constructors

RocksDbHandle() 

protected RocksDbHandle()

RocksDbHandle(nint)

Takes over an already-created native handle.

protected RocksDbHandle(nint handle)

Parameters

handle nint

The native handle to own.

Properties

Handle

Gets the native handle associated with the underlying resource, for interoperability with unmanaged code.

public nint Handle { get; protected set; }

Property Value

nint

Remarks

Reading this after disposal throws rather than returning Zero. The C API dereferences whatever it is given without a null check, so a zero handle reaching it is an access violation that takes the process down, with a stack that says nothing about the disposed object that caused it. Every use-after-dispose in the library passes through here, so one guard turns all of them into a named exception. Use IsDisposed to ask the question without throwing.

The value is Zero before the native object has been created, which a wrapper constructed but not yet opened will show.

Exceptions

ObjectDisposedException

This instance has been disposed.

IsDisposed

Gets a value indicating whether the object has been disposed.

public bool IsDisposed { get; }

Property Value

bool

Remarks

True from the moment disposal begins, not from when it finishes, so a half-released object never looks usable. Reading Handle on one of these throws.

IsPinned

Whether PinGarbageCollector(string?) has run, and so whether UnpinGarbageCollector() can be called without throwing.

protected bool IsPinned { get; }

Property Value

bool

Remarks

For the finalizer path. A derived constructor that throws while evaluating the arguments it passes to base(...) leaves an allocated, finalizable object on which no constructor ever ran, so nothing pinned it. Unpinning that throws, and an exception from a finalizer is unhandled and takes the process with it.

Owned

Indicating whether this instance is owned or managed by the current object. If true, the object is responsible for releasing the native handle during disposal; if false, the handle is managed externally and should not be released by this instance.

public bool Owned { get; protected init; }

Property Value

bool

Methods

Dispose()

Releases all resources used by the current instance.

public virtual void Dispose()

Remarks

Call this method when the instance is no longer needed to free unmanaged resources promptly. After calling this method, the instance should not be used.

Dispose(bool) 

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

DisposeHandle()

Releases the native handle. Called during disposal.

protected abstract 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 virtual void DisposeUnmanagedResources()

Remarks

Protected for the same reason as DisposeHandle().

~RocksDbHandle() 

protected ~RocksDbHandle()

GetNameFromPinnedIntPtr(nint)

Recovers the unmanaged name pointer for the instance behind a callback state pointer.

protected static nint GetNameFromPinnedIntPtr(nint state)

Parameters

state nint

The state pointer given to the callback.

Returns

nint

A pointer to the null-terminated name.

GetPinnedIntPtr()

The pointer to pass to RocksDb as the callback state, which comes back to GetSelfFromPinnedIntPtr<T>(nint) on every callback.

protected nint GetPinnedIntPtr()

Returns

nint

A pointer to the pinned handle for this instance.

Exceptions

InvalidOperationException

PinGarbageCollector(string?) has not been called.

GetPinnedNameIntPtr()

The unmanaged copy of this instance's name, for a native name callback to return directly.

protected nint GetPinnedNameIntPtr()

Returns

nint

A pointer to a null-terminated copy of the name.

Remarks

The name has to live in unmanaged memory because RocksDb keeps the pointer it is given rather than copying the string.

Exceptions

InvalidOperationException

PinGarbageCollector(string?) has not been called.

GetSelfFromPinnedIntPtr<T>(nint)

Recovers the managed instance from the state pointer RocksDb passes to a callback.

protected static T GetSelfFromPinnedIntPtr<T>(nint state) where T : RocksDbHandle

Parameters

state nint

The state pointer given to the callback.

Returns

T

The instance the pointer refers to.

Type Parameters

T

The expected instance type.

Exceptions

InvalidOperationException

The pointer is null, the handle is no longer allocated, or the target is not a T.

PinGarbageCollector(string?)

Pins this instance so native code can hold a pointer to it across callbacks, optionally alongside a stable copy of its name.

protected GCHandle PinGarbageCollector(string? name = null)

Parameters

name string

A name to keep in unmanaged memory for the native name callback to return, or null if the type has no name callback.

Returns

GCHandle

The allocated handle, already stored on this instance.

Remarks

Call this before handing any function pointer to RocksDb. Without it the garbage collector is free to move or collect the instance while native code still holds its address, and the callback then runs against freed memory. Release it from the native destructor callback with UnpinGarbageCollector().

ThrowIfDisposed()

Throws an exception if the object has been disposed.

public void ThrowIfDisposed()

Remarks

Call this method before performing operations that require the object to be in a valid, non-disposed state. This helps prevent accessing resources that have already been released.

Exceptions

ObjectDisposedException

Thrown if the object has already been disposed.

UnpinGarbageCollector()

Releases the pin taken by PinGarbageCollector(string?) and frees the unmanaged name copy.

protected void UnpinGarbageCollector()

Remarks

Call this from the native destructor callback, which RocksDb invokes when it is finished with the object. Unpinning earlier leaves native code holding a dangling state pointer.

Edit this page