Class NativeMemoryManagerBase

Namespace

Sdl3Sharp.Utilities

Assembly

Sdl3Sharp.dll

A base class for memory managers that manage and represent allocated native memory

public abstract class NativeMemoryManagerBase : IDisposable

Inheritance

object

NativeMemoryManagerBase

Implements

IDisposable

Derived

NativeMemoryManager

TexturePixelMemoryManager

SurfacePixelMemoryManager

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Note: Always remember to dispose NativeMemoryManagerBase when the memory they're managing is no longer needed.

Properties

IsPinned

Gets a value indicating whether this NativeMemoryManager is pinned

public virtual bool IsPinned { get; }

Property Value

bool

A value indicating whether this NativeMemoryManager is pinned

Remarks

A pinned NativeMemoryManager can't be disposed or be used in operations like TryRealloc(ref NativeMemoryManager?, nuint).

See Also

Pin()

Length

Gets the number of bytes in the allocated memory region this NativeMemoryManagerBase represents

public abstract nuint Length { get; }

Property Value

nuint

The number of bytes in the allocated memory region this NativeMemoryManagerBase represents

Memory

Gets the allocated memory buffer this NativeMemoryManagerBase represents

public virtual NativeMemory Memory { get; }

Property Value

NativeMemory

The allocated memory buffer this NativeMemoryManagerBase represents

PinCounter

Gets the current pin counter

protected ulong PinCounter { get; }

Property Value

ulong

Pointer

Gets a pointer to the start of the allocated memory region this NativeMemoryManagerBase represents

public abstract nint Pointer { get; }

Property Value

nint

A pointer to the start of the allocated memory region this NativeMemoryManagerBase represents

Methods

AddPin(ulong, ulong)

Adds a "pin" to this NativeMemoryManagerBase

protected virtual void AddPin(ulong oldPinCounter, ulong newPinCounter)

Parameters

oldPinCounter ulong

The pin counter before it was increased

newPinCounter ulong

The current pin counter after it was increased

Remarks

This method is called each time the pin counter was successfully increased. You can override this method to implement custom logic that should be executed each time a "pin" is added to this NativeMemoryManagerBase.

If you want a more general pinning logic that only triggers when the first pin is added, you can check whether oldPinCounter is 0 and newPinCounter greater than 0 in your custom implementation.

When implementing this method, remember that it must work in conjunction with RemovePin(ulong, ulong).

There's no guarantee about when this method is called in relation to other threads pinning or unpinning this NativeMemoryManagerBase. Custom implementations must take care of thread-safetiness themselves if needed, especially in regards to the ordering of AddPin(ulong, ulong) and RemovePin(ulong, ulong) operations.

The only guarantee given is that this method is only ever called immediately after the pin counter was successfully increased by a single pinning operation.

DecreasePinCounter(ulong)

Decreases the pin counter

protected virtual ulong DecreasePinCounter(ulong pinCounter)

Parameters

pinCounter ulong

The current pin counter

Returns

ulong

The new pin counter

Remarks

Override this method to implement custom pin counter decreasing step logic. You can even just ignore pinning altogether and always return the given pinCounter.

Notice that custom implementations of this method should ensure that the returned value is less than or equal to the given pinCounter. Also, when implementing this method, remember that the pin counter stepping must work in conjunction with IncreasePinCounter(ulong). Furthermore, there's no underflow preventing logic in the consumers of this method, so custom implementations should ensure that underflow doesn't happen.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Remarks

All of the NativeMemory and NativeMemory<T> instances, that are subsequently depending on this NativeMemoryManagerBase, will become invalid of this operation.

Note: Trying to dipose a pinned NativeMemoryManager will throw! Make sure that the NativeMemoryManager is not pinned anymore before trying to dispose it.

Dispose(bool)

Disposes this NativeMemoryManagerBase

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

A value indicating whether this method is called from Dispose() (true) or from the finalizer (false)

See Also

Dispose()

~NativeMemoryManagerBase()

protected ~NativeMemoryManagerBase()

IncreasePinCounter(ulong)

Increases the pin counter

protected virtual ulong IncreasePinCounter(ulong pinCounter)

Parameters

pinCounter ulong

The current pin counter

Returns

ulong

The new pin counter

Remarks

Override this method to implement custom pin counter increasing step logic. You can even just ignore pinning altogether and always return the given pinCounter.

Notice that custom implementations of this method should ensure that the returned value is greater than or equal to the given pinCounter. Also, when implementing this method, remember that the pin counter stepping must work in conjunction with DecreasePinCounter(ulong). Furthermore, there's no overflow preventing logic in the consumers of this method, so custom implementations should ensure that overflow doesn't happen.

Pin()

Pins this NativeMemoryManagerBase

public NativeMemoryPin Pin()

Returns

NativeMemoryPin

A pin pinning this NativeMemoryManagerBase

Remarks

A pinned NativeMemoryManager can't be disposed or be used in operations like TryRealloc(ref NativeMemoryManager?, nuint).

PinOnce()

Pins this NativeMemoryManagerBase once

protected ulong PinOnce()

Returns

ulong

The new pin counter

RemovePin(ulong, ulong)

Removes a "pin" to this NativeMemoryManagerBase

protected virtual void RemovePin(ulong oldPinCounter, ulong newPinCounter)

Parameters

oldPinCounter ulong

The pin counter before it was decreased

newPinCounter ulong

The current pin counter after it was decreased

Remarks

This method is called each time the pin counter was successfully decreased. You can override this method to implement custom logic that should be executed each time a "pin" is removed from this NativeMemoryManagerBase.

If you want a more general pinning logic that only triggers when the last pin is removed, you can check whether oldPinCounter is greater than 0 and newPinCounter is 0 in your custom implementation.

When implementing this method, remember that it must work in conjunction with AddPin(ulong, ulong).

There's no guarantee about when this method is called in relation to other threads pinning or unpinning this NativeMemoryManagerBase. Custom implementations must take care of thread-safetiness themselves if needed, especially in regards to the ordering of AddPin(ulong, ulong) and RemovePin(ulong, ulong) operations.

The only guarantee given is that this method is only ever called immediately after the pin counter was successfully decreased by a single unpinning operation.

UnpinOnce()

Unpins this NativeMemoryManagerBase once

protected ulong UnpinOnce()

Returns

ulong

The new pin counter

See Also

NativeMemory