handle.h

#include <modkit/handle.h>6 functions · 3 structs · 3 typedefs · 10 macros

Generational handle system for safe resource management.

Handles are type-safe identifiers for resources (meshes, materials, etc.) Each handle contains an index and generation to detect stale references. Handle format: [generation:8][index:24] = 32 bitsIndex: slot in pool (up to 16M objects per type)Generation: incremented on reuse, detects use-after-free

Functions

mk_handle_pool_allocfunction

uint32_t mk_handle_pool_alloc(mk_handle_pool_t *pool)

Allocate a new handle from the pool.

Parameter	Type	Description
pool	mk_handle_pool_t *	Pool to allocate from

Returns New handle ID, or 0 if pool is exhausted

mk_handle_pool_countfunction

uint32_t mk_handle_pool_count(mk_handle_pool_t *pool)

Get the number of active handles in the pool.

Parameter	Type	Description
pool	mk_handle_pool_t *	Pool to query

Returns Number of allocated handles

mk_handle_pool_createfunction

mk_handle_pool_t mk_handle_pool_create(uint32_t capacity)

Create a handle pool with initial capacity.

Parameter	Type	Description
capacity	uint32_t	Initial number of slots

Returns Initialized pool, or empty pool on failure

mk_handle_pool_destroyfunction

void mk_handle_pool_destroy(mk_handle_pool_t *pool)

Destroy a handle pool and free memory.

Parameter	Type	Description
pool	mk_handle_pool_t *	Pool to destroy

mk_handle_pool_freefunction

bool mk_handle_pool_free(mk_handle_pool_t *pool, uint32_t handle)

Free a handle back to the pool.

Parameter	Type	Description
pool	mk_handle_pool_t *	Pool to return handle to
handle	uint32_t	Handle ID to free

Returns true if freed successfully, false if invalid/already freed

mk_handle_pool_validfunction

bool mk_handle_pool_valid(mk_handle_pool_t *pool, uint32_t handle)

Check if a handle is currently valid.

Parameter	Type	Description
pool	mk_handle_pool_t *	Pool to check against
handle	uint32_t	Handle ID to validate

Returns true if handle is valid and not freed

Structs

mk_atlas_handlestruct

Atlas handle (sprite system).

Field	Type	Description
id	uint32_t	The ID.

mk_handle_poolstruct

Handle pool for managing a type of resource.

Each resource type has its own pool.

Field	Type	Description
generations	uint32_t *	Generation counter per slot.
free_list	uint32_t *	Stack of free indices.
free_count	uint32_t	Number of free slots.
capacity	uint32_t	Total slots allocated.
count	uint32_t	Currently active handles.

mk_tilemap_handlestruct

Tilemap handle (tilemap package).

Field	Type	Description
id	uint32_t	The ID.

Typedefs

mk_atlas_handle_ttypedef

typedef struct mk_atlas_handle mk_atlas_handle_t

Atlas handle (sprite system).

mk_handle_pool_ttypedef

typedef struct mk_handle_pool mk_handle_pool_t

Handle pool for managing a type of resource.

Each resource type has its own pool.

mk_tilemap_handle_ttypedef

typedef struct mk_tilemap_handle mk_tilemap_handle_t

Tilemap handle (tilemap package).

Macros

MK_ATLAS_H_INVALIDdefine

MK_ATLAS_H_INVALID

Invalid sentinel for atlas h.

mk_atlas_h_validdefine

mk_atlas_h_valid(h)

Constant for atlas h valid.

MK_HANDLE_GENdefine

MK_HANDLE_GEN(h)

Extract generation from handle.

MK_HANDLE_INDEXdefine

MK_HANDLE_INDEX(h)

Extract index from handle.

MK_HANDLE_MAKEdefine

MK_HANDLE_MAKE(idx, gen)

Create handle from index and generation.

MK_HANDLE_MAX_GENdefine

MK_HANDLE_MAX_GEN

Maximum supported handle gen.

MK_HANDLE_MAX_INDEXdefine

MK_HANDLE_MAX_INDEX

Maximum objects per pool type.

MK_INVALID_HANDLE_IDdefine

MK_INVALID_HANDLE_ID

Invalid sentinel for invalid handle ID.

MK_TILEMAP_H_INVALIDdefine

MK_TILEMAP_H_INVALID

Invalid sentinel for tilemap h.

mk_tilemap_h_validdefine

mk_tilemap_h_valid(h)

Constant for tilemap h valid.