Class NativeHandle

Namespace

Pamoja.Native.Interop

Assembly

Pamoja.Native.dll

A SafeHandle over a native pointer whose release function is supplied at construction, so the handle is always released exactly once even across finalization races.

public sealed class NativeHandle : SafeHandle, IDisposable

Inheritance

object

CriticalFinalizerObject

SafeHandle

NativeHandle

Implements

IDisposable

Inherited Members

SafeHandle.Close()

SafeHandle.DangerousAddRef(ref bool)

SafeHandle.DangerousGetHandle()

SafeHandle.DangerousRelease()

SafeHandle.Dispose()

SafeHandle.SetHandleAsInvalid()

SafeHandle.IsClosed

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

The helper-math capabilities expose a family of handles that differ only in which *_free function releases them, so one handle type carrying that function serves them all.

Constructors

NativeHandle(nint, Action<nint>)

Wraps a non-null native pointer with the function that frees it.

public NativeHandle(nint handle, Action<nint> release)

Parameters

handle nint

The pointer returned by a native constructor.

release Action<nint>

The matching native release function.

Properties

IsInvalid

When overridden in a derived class, gets a value indicating whether the handle value is invalid.

public override bool IsInvalid { get; }

Property Value

bool

true if the handle value is invalid; otherwise, false.

Methods

Create(nint, Action<nint>, string)

Creates a wrapper, throwing when the native constructor returned null.

public static NativeHandle Create(nint handle, Action<nint> release, string what)

Parameters

handle nint

The pointer returned by a native constructor.

release Action<nint>

The matching native release function.

what string

What was being created, for the exception message.

Returns

NativeHandle

The wrapped handle.

Exceptions

PamojaException

The native constructor returned null.

ReleaseHandle()

When overridden in a derived class, executes the code required to free the handle.

protected override bool ReleaseHandle()

Returns

bool

true if the handle is released successfully; otherwise, in the event of a catastrophic failure, false. In this case, it generates a releaseHandleFailed Managed Debugging Assistant.

Use(Action<nint>)

Runs a native call that returns nothing, holding the handle open.

public void Use(Action<nint> call)

Parameters

call Action<nint>

The native call to make.

UseTry<TValue>(NativeTry<TValue>)

Runs a native call that answers "maybe", holding the handle open, and maps its bool-plus-out-parameter shape onto a nullable value.

public TValue? UseTry<TValue>(NativeTry<TValue> call) where TValue : struct

Parameters

call NativeTry<TValue>

The native call to make.

Returns

TValue?

The value the call produced, or null when it produced none.

Type Parameters

TValue

The value the native call may produce.

Use<TResult>(Func<nint, TResult>)

Runs a native call that returns a value, holding the handle open.

public TResult Use<TResult>(Func<nint, TResult> call)

Parameters

call Func<nint, TResult>

The native call to make.

Returns

TResult

Whatever the native call returned.

Type Parameters

TResult

The value the native call returns.