Reference-counted wrapper for C structures using std::shared_ptr. More...

#include <SharedPtrWrapper.hpp>

Public Types
using	SharedPtr = std::shared_ptr<StructType>
	Type alias for std::shared_ptr<StructType>.
using	WeakPtr = std::weak_ptr<StructType>
	Type alias for std::weak_ptr<StructType>.
using	SharedCacheMap = std::unordered_map<StructType*, WeakPtr>
	Type alias for the cache map (std::unordered_map<StructType*, WeakPtr>).
using	DeleteFunc = std::function<void(StructType*)>
	Type alias for deletion function (std::function<void(StructType*)>).

Public Member Functions
	SharedPtrWrapper ()=delete
	SharedPtrWrapper (std::nullptr_t)
	Construct a null wrapper (explicit nullptr initialization).
	SharedPtrWrapper (StructType *struct_ptr, DeleteFunc deleteFunc)
	Construct from a raw pointer and deletion function.
	SharedPtrWrapper (SharedPtrWrapper &&other) noexcept
	Move constructor.
	SharedPtrWrapper (SharedPtr shared_ptr)
	Existing Shared Pointer.
SharedPtrWrapper &	operator= (SharedPtrWrapper &&other) noexcept
	Move assignment operator.
	SharedPtrWrapper (const SharedPtrWrapper &other)
	Copy constructor.
SharedPtrWrapper &	operator= (const SharedPtrWrapper &other)
	Copy assignment operator.
	operator StructType * () const
	Implicit conversion to raw C pointer.
SharedPtrWrapper &	operator= (std::nullptr_t)
	Assign nullptr to release ownership.
	operator bool () const
	Check if the wrapper holds a valid pointer.
StructType *	operator-> () const
	Arrow operator for member access.

Static Public Member Functions
static void	null_deleter (StructType *)

Static Protected Member Functions
static SharedCacheMap &	get_shared_weak_ptr_cache ()
static bool	is_cached (StructType *ptr)
static SharedPtr	get_or_view (StructType *ptr)
	Get or create a non-owning reference to a C pointer.
static SharedPtr	get_or_cache (StructType *ptr, DeleteFunc deleteFunc)
	Get or create an owning reference to a C pointer.

Detailed Description

template<typename StructType>
class hdk::grid::SharedPtrWrapper< StructType >

Reference-counted wrapper for C structures using std::shared_ptr.

Template Parameters

StructType The C structure type being wrapped

SharedPtrWrapper provides automatic lifetime management for C-style structures through reference counting. This template is the foundation for building C++-style wrappers around C APIs while maintaining compatibility with the underlying C code through implicit pointer conversion.

Key features:

Reference counting: Multiple copies of a wrapper share ownership of one C structure
Implicit casting: Automatically converts to StructType* for C API compatibility
Smart pointer semantics: Automatic cleanup when last reference is released
Caching: Prevents reference counting issues when the same C pointer is wrapped multiple times

The template maintains an internal cache of weak pointers to ensure that the same C structure pointer always maps to the same shared_ptr instance, preventing double-deletion and ensuring consistent reference counting.

Note: No default constructor. Must be constructed with a value or explicitly set to nullptr.; Evaluates to false (via operator bool) if the shared pointer is null, true otherwise.

See also: https://en.cppreference.com/w/cpp/memory/shared_ptr

Definition at line 8 of file SharedPtrWrapper.hpp.

Member Typedef Documentation

◆ DeleteFunc

template<typename StructType>

using hdk::grid::SharedPtrWrapper< StructType >::DeleteFunc = std::function<void(StructType*)>

Type alias for deletion function (std::function<void(StructType*)>).

The deletion function is called when the reference count reaches zero. Typically this is a C API cleanup function like SDL_DestroyWindow.

Definition at line 13 of file SharedPtrWrapper.hpp.

◆ SharedCacheMap

template<typename StructType>

using hdk::grid::SharedPtrWrapper< StructType >::SharedCacheMap = std::unordered_map<StructType*, WeakPtr>

Type alias for the cache map (std::unordered_map<StructType*, WeakPtr>).

The cache ensures that multiple wrappers of the same raw pointer share the same shared_ptr instance, preventing reference counting errors.

Definition at line 12 of file SharedPtrWrapper.hpp.

◆ SharedPtr

template<typename StructType>

using hdk::grid::SharedPtrWrapper< StructType >::SharedPtr = std::shared_ptr<StructType>

Type alias for std::shared_ptr<StructType>.

Definition at line 10 of file SharedPtrWrapper.hpp.

◆ WeakPtr

template<typename StructType>

using hdk::grid::SharedPtrWrapper< StructType >::WeakPtr = std::weak_ptr<StructType>

Type alias for std::weak_ptr<StructType>.

Definition at line 11 of file SharedPtrWrapper.hpp.

Constructor & Destructor Documentation

◆ SharedPtrWrapper() [1/6]

template<typename StructType>

hdk::grid::SharedPtrWrapper< StructType >::SharedPtrWrapper ( )

delete

Referenced by operator=(), operator=(), operator=(), SharedPtrWrapper(), and SharedPtrWrapper().

◆ SharedPtrWrapper() [2/6]

template<typename StructType>

hdk::grid::SharedPtrWrapper< StructType >::SharedPtrWrapper ( std::nullptr_t )

inline

Construct a null wrapper (explicit nullptr initialization).

Initializes the wrapper to hold a null pointer.

See also: SharedPtrWrapper::operator=(std::nullptr_t)

Definition at line 16 of file SharedPtrWrapper.hpp.

◆ SharedPtrWrapper() [3/6]

template<typename StructType>

hdk::grid::SharedPtrWrapper< StructType >::SharedPtrWrapper	(	StructType *	struct_ptr,
		DeleteFunc	deleteFunc )

inline

Construct from a raw pointer and deletion function.

Creates a wrapper that takes ownership of the provided pointer and uses the specified deletion function for cleanup when the reference count reaches zero.

Template Parameters

StructType The structure type

Parameters

struct_ptr	The raw pointer to wrap
deleteFunc	The function to call for cleanup (e.g., SDL_DestroyWindow, SDL_DestroyRenderer)

Definition at line 18 of file SharedPtrWrapper.hpp.

References get_shared_weak_ptr_cache().

◆ SharedPtrWrapper() [4/6]

template<typename StructType>

hdk::grid::SharedPtrWrapper< StructType >::SharedPtrWrapper ( SharedPtrWrapper< StructType > && other )

inlinenoexcept

Move constructor.

Efficiently transfers ownership from another wrapper instance.

Parameters

other The source wrapper (will be moved from)

Definition at line 23 of file SharedPtrWrapper.hpp.

References SharedPtrWrapper().

◆ SharedPtrWrapper() [5/6]

template<typename StructType>

hdk::grid::SharedPtrWrapper< StructType >::SharedPtrWrapper ( SharedPtr shared_ptr )

inline

Existing Shared Pointer.

Construct from an existing shared_ptr.

Creates a wrapper around an already-created shared_ptr, which is useful when working with already-managed pointers or integrating with other code that uses shared_ptr.

Parameters

shared_ptr An existing std::shared_ptr to wrap

Definition at line 26 of file SharedPtrWrapper.hpp.

References get_shared_weak_ptr_cache(), and is_cached().

◆ SharedPtrWrapper() [6/6]

template<typename StructType>

hdk::grid::SharedPtrWrapper< StructType >::SharedPtrWrapper ( const SharedPtrWrapper< StructType > & other )

inline

Copy constructor.

Creates a new wrapper that shares ownership of the same structure. Both instances will increment the reference count and share the lifetime of the underlying structure.

Parameters

other The source wrapper to copy from

Definition at line 40 of file SharedPtrWrapper.hpp.

References SharedPtrWrapper().

Member Function Documentation

◆ get_or_cache()

template<typename StructType>

SharedPtr hdk::grid::SharedPtrWrapper< StructType >::get_or_cache	(	StructType *	ptr,
		DeleteFunc	deleteFunc )

inlinestaticprotected

Get or create an owning reference to a C pointer.

This protected method is used by derived classes to create owning references to C pointers. If the pointer is already in the cache, returns the cached shared_ptr. Otherwise, creates a new shared_ptr with the provided deletion function and caches it.

This ensures that the same C pointer always maps to the same shared_ptr instance, preventing reference counting errors.

Parameters

ptr	The raw pointer to wrap
deleteFunc	The function to call when the reference count reaches zero

Returns: SharedPtr A shared_ptr to the pointer (cached if newly created)

Example from derived class:

// Creating a new window and taking ownership
static Window Create(const char* title, int w, int h, SDL_WindowFlags flags) {
  return Window(get_or_cache(SDL_CreateWindow(title, w, h, flags), SDL_DestroyWindow));
}

If no ptr, no need to do anything else

Definition at line 82 of file SharedPtrWrapper.hpp.

References get_shared_weak_ptr_cache(), and is_cached().

◆ get_or_view()

template<typename StructType>

SharedPtr hdk::grid::SharedPtrWrapper< StructType >::get_or_view ( StructType * ptr )

inlinestaticprotected

Get or create a non-owning reference to a C pointer.

This protected method is used by derived classes to create references to C pointers without taking ownership. If the pointer is already in the cache, returns the cached shared_ptr. Otherwise, returns a new non-owning shared_ptr (with null_deleter).

This is useful when:

The C object was created outside this wrapper system
You want to reference a C object without managing its lifetime
The C object is owned by SDL or other external code

Parameters

ptr	The raw pointer to wrap

Returns: SharedPtr A shared_ptr to the pointer (owning if cached, non-owning otherwise)

Example from derived class:

// Getting a window created externally, without taking ownership
static Window GetFromID(SDL_WindowID id) {
  return Window(get_or_view(SDL_GetWindowFromID(id)));
}

if no pointer

then return a non-owning null

Definition at line 67 of file SharedPtrWrapper.hpp.

References get_shared_weak_ptr_cache(), is_cached(), and null_deleter().

◆ get_shared_weak_ptr_cache()

template<typename StructType>

SharedCacheMap & hdk::grid::SharedPtrWrapper< StructType >::get_shared_weak_ptr_cache ( )

inlinestaticprotected

Definition at line 59 of file SharedPtrWrapper.hpp.

Referenced by get_or_cache(), get_or_view(), is_cached(), SharedPtrWrapper(), and SharedPtrWrapper().

◆ is_cached()

template<typename StructType>

bool hdk::grid::SharedPtrWrapper< StructType >::is_cached ( StructType * ptr )

inlinestaticprotected

Definition at line 63 of file SharedPtrWrapper.hpp.

References get_shared_weak_ptr_cache().

Referenced by get_or_cache(), get_or_view(), and SharedPtrWrapper().

◆ null_deleter()

template<typename StructType>

void hdk::grid::SharedPtrWrapper< StructType >::null_deleter ( StructType * )

inlinestatic

Definition at line 14 of file SharedPtrWrapper.hpp.

Referenced by get_or_view().

◆ operator bool()

template<typename StructType>

hdk::grid::SharedPtrWrapper< StructType >::operator bool ( ) const

inline

Check if the wrapper holds a valid pointer.

Returns: bool True if holding a non-null pointer, false if null

Example:

if (window) {
  // window is valid
}

Definition at line 53 of file SharedPtrWrapper.hpp.

◆ operator StructType *()

template<typename StructType>

hdk::grid::SharedPtrWrapper< StructType >::operator StructType * ( ) const

inline

Implicit conversion to raw C pointer.

Allows the wrapper to be used anywhere a StructType* is expected, enabling seamless compatibility with C APIs.

Returns: StructType* The underlying raw pointer

Example:

hdk::sdl::Window window = ...;

SDL_SetWindowSize(window, 800, 600); // implicit conversion to SDL_Window*

Definition at line 48 of file SharedPtrWrapper.hpp.

◆ operator->()

template<typename StructType>

StructType * hdk::grid::SharedPtrWrapper< StructType >::operator-> ( ) const

inline

Arrow operator for member access.

Allows access to structure members through the -> operator.

Returns: StructType* The underlying pointer for member access

Example:

hdk::grid::SharedPtrWrapper<SDL_Surface> surface = ...;

int width = surface->w; // access surface width

hdk::grid::SharedPtrWrapper

Reference-counted wrapper for C structures using std::shared_ptr.

Definition SharedPtrWrapper.hpp:8

Definition at line 54 of file SharedPtrWrapper.hpp.

◆ operator=() [1/3]

template<typename StructType>

SharedPtrWrapper & hdk::grid::SharedPtrWrapper< StructType >::operator= ( const SharedPtrWrapper< StructType > & other )

inline

Copy assignment operator.

Parameters

other The source wrapper to copy from

Returns: Reference to this wrapper

Definition at line 42 of file SharedPtrWrapper.hpp.

References SharedPtrWrapper().

◆ operator=() [2/3]

template<typename StructType>

SharedPtrWrapper & hdk::grid::SharedPtrWrapper< StructType >::operator= ( SharedPtrWrapper< StructType > && other )

inlinenoexcept

Move assignment operator.

Parameters

other The source wrapper (will be moved from)

Returns: Reference to this wrapper

Definition at line 34 of file SharedPtrWrapper.hpp.

References SharedPtrWrapper().

◆ operator=() [3/3]

template<typename StructType>

SharedPtrWrapper & hdk::grid::SharedPtrWrapper< StructType >::operator= ( std::nullptr_t )

inline

Assign nullptr to release ownership.

Releases ownership of the current structure, decrementing the reference count. If this was the last reference, the structure is destroyed using the registered deletion function.

Returns: Reference to this wrapper

Definition at line 49 of file SharedPtrWrapper.hpp.

References SharedPtrWrapper().

The documentation for this class was generated from the following files:

include/hdk/grid/SharedPtrWrapper.hpp
src/SharedPtrWrapper.cpp

hdk-grid 0.0.1 Header-only foundational library for the Hollow Development Kit.

Public Types

Public Member Functions

Static Public Member Functions

Static Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ DeleteFunc

◆ SharedCacheMap

◆ SharedPtr

◆ WeakPtr

Constructor & Destructor Documentation

◆ SharedPtrWrapper() [1/6]

◆ SharedPtrWrapper() [2/6]

◆ SharedPtrWrapper() [3/6]

◆ SharedPtrWrapper() [4/6]

◆ SharedPtrWrapper() [5/6]

◆ SharedPtrWrapper() [6/6]

Member Function Documentation

◆ get_or_cache()

◆ get_or_view()

◆ get_shared_weak_ptr_cache()

◆ is_cached()

◆ null_deleter()

◆ operator bool()

◆ operator StructType *()

◆ operator->()

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]