registry.h File Reference

A registry holds arbitrarily-sized blocks of memory that are referenced by handle. These blocks are stored along with their size in the registry, and the registry owns its own copy of the data (if a block is probided, it takes a copy in the add and set functions). Entries can opt-in to being auto-released when thier internal reference counter reaches 0. Callers can also register callbacks when acquiring references to registry blocks to be informed of any updates to said block when it occurs (via the block_set function) by passing a callback during acquisition. More...

#include "defines.h"
#include "identifiers/khandle.h"

Go to the source code of this file.

Data Structures
struct	kregistry_entry_listener_callback
struct	kregistry_entry
struct	k_registry

Typedefs
typedef enum kregistry_entry_change_type	kregistry_entry_change_type
typedef void(*	PFN_on_registry_entry_updated) (void *sender, void *block, u64 size, kregistry_entry_change_type change_type)
	Callback to be made when a registry block is updated via registry_entry_block_set(). More...
typedef struct kregistry_entry_listener_callback	kregistry_entry_listener_callback
typedef struct kregistry_entry	kregistry_entry
typedef struct k_registry	kregistry

Enumerations
enum	kregistry_entry_change_type { K_REGISTRY_CHANGE_TYPE_BLOCK_CHANGED , K_REGISTRY_CHANGE_TYPE_DESTROYED }

Functions
KAPI void	kregistry_create (kregistry *out_registry)
KAPI void	kregistry_destroy (kregistry *registry)
KAPI khandle	kregistry_add_entry (kregistry *registry, const void *block, u64 size, b8 auto_release)
	Adds a new entry to the registry and returns a handle to it. More...
KAPI b8	kregistry_entry_set (kregistry *registry, khandle entry_handle, const void *block, u64 size, void *sender)
	Attempts to set an existing registry block's data. When this occurs, the old data block will be released and replaced by the new one. If any callbacks are registered for this block, they will be informed of the update so thier pointer to the block may be updated. NOTE: This may only be done against existing entries. Non-existing will fail. More...
KAPI b8	kregistry_entry_update_callback_for_listener (kregistry *registry, khandle entry_handle, void *listener, PFN_on_registry_entry_updated updated_callback)
	Attempts to update the callback for the given entry for the provided listener. More...
KAPI void *	kregistry_entry_acquire (kregistry *registry, khandle entry_handle, void *listener, PFN_on_registry_entry_updated updated_callback)
	Attempts to acquire a reference for the given entry for the provided listener. This increments the internal reference counter. More...
KAPI void	kregistry_entry_release (kregistry *registry, khandle entry_handle, void *listener)
	Attempts to release a reference for the given entry for the provided listener. This decrements the internal reference counter. If set to auto-release, the entry's internal block of memory will be released when its internal reference counter reaches 0. More...

Detailed Description

A registry holds arbitrarily-sized blocks of memory that are referenced by handle. These blocks are stored along with their size in the registry, and the registry owns its own copy of the data (if a block is probided, it takes a copy in the add and set functions). Entries can opt-in to being auto-released when thier internal reference counter reaches 0. Callers can also register callbacks when acquiring references to registry blocks to be informed of any updates to said block when it occurs (via the block_set function) by passing a callback during acquisition.

Author

Travis Vroman (travi.nosp@m.s@ko.nosp@m.hieng.nosp@m.ine..nosp@m.com)

Version

1.0

Date

2024-03-04

Copyright

Kohi Game Engine is Copyright (c) Travis Vroman 2021-2024

Typedef Documentation

kregistry

typedef struct k_registry kregistry

kregistry_entry

typedef struct kregistry_entry kregistry_entry

kregistry_entry_change_type

typedef enum kregistry_entry_change_type kregistry_entry_change_type

kregistry_entry_listener_callback

typedef struct kregistry_entry_listener_callback kregistry_entry_listener_callback

PFN_on_registry_entry_updated

typedef void(* PFN_on_registry_entry_updated) (void *sender, void *block, u64 size, kregistry_entry_change_type change_type)

Callback to be made when a registry block is updated via registry_entry_block_set().

Enumeration Type Documentation

kregistry_entry_change_type

enum kregistry_entry_change_type

Enumerator
K_REGISTRY_CHANGE_TYPE_BLOCK_CHANGED
K_REGISTRY_CHANGE_TYPE_DESTROYED

Function Documentation

kregistry_add_entry()

KAPI khandle kregistry_add_entry	(	kregistry *	registry,
		const void *	block,
		u64	size,
		b8	auto_release
	)

Adds a new entry to the registry and returns a handle to it.

Parameters

registry	A pointer to the registry.
block	A block of memory to be tracked. Optional. If provided, a copy of this is taken and owned by the registry.
size	The size of the block of memory.
auto_release	Indicates if this entry should automatically release memory when its internal reference counter reaches 0.

Returns

A handle to the newly-created registry entry.

kregistry_create()

KAPI void kregistry_create

(

kregistry *

out_registry

)

Creates a new registry.

Parameters

out_registry

A pointer to hold the newly-created registry.

kregistry_destroy()

KAPI void kregistry_destroy

(

kregistry *

registry

)

Destroys the provided registry.

Parameters

registry

A pointer to the registry to be destroyed.

kregistry_entry_acquire()

KAPI void* kregistry_entry_acquire	(	kregistry *	registry,
		khandle	entry_handle,
		void *	listener,
		PFN_on_registry_entry_updated	updated_callback
	)

Attempts to acquire a reference for the given entry for the provided listener. This increments the internal reference counter.

Parameters

registry	A pointer to the registry.
entry_handle	The handle to the entry to acquire.
listener	The listener to update the callback for. Optional, but required if updated_callback is set.
updated_callback	The callback to be set. Optional.

Returns

A pointer to the entry's memory block on success; otherwise 0/null.

kregistry_entry_release()

KAPI void kregistry_entry_release	(	kregistry *	registry,
		khandle	entry_handle,
		void *	listener
	)

Attempts to release a reference for the given entry for the provided listener. This decrements the internal reference counter. If set to auto-release, the entry's internal block of memory will be released when its internal reference counter reaches 0.

Parameters

registry	A pointer to the registry.
entry_handle	The handle to the entry to release.
listener	A pointer to the listener. Optional.

kregistry_entry_set()

KAPI b8 kregistry_entry_set	(	kregistry *	registry,
		khandle	entry_handle,
		const void *	block,
		u64	size,
		void *	sender
	)

Attempts to set an existing registry block's data. When this occurs, the old data block will be released and replaced by the new one. If any callbacks are registered for this block, they will be informed of the update so thier pointer to the block may be updated. NOTE: This may only be done against existing entries. Non-existing will fail.

Parameters

registry	A pointer to the registry.
entry_handle	The handle to the entry.
block	The new block of memory.
size	The new size of the block of memory.
sender	An optional pointer to the initiator of this operation.

Returns

True if successfully set; otherwise false.

kregistry_entry_update_callback_for_listener()

KAPI b8 kregistry_entry_update_callback_for_listener	(	kregistry *	registry,
		khandle	entry_handle,
		void *	listener,
		PFN_on_registry_entry_updated	updated_callback
	)

Attempts to update the callback for the given entry for the provided listener.

Parameters

registry	A pointer to the registry.
entry_handle	The handle to the entry.
listener	The listener to update the callback for. Optional. If 0/null is passed, it's assumed that the block itself will be the listener.
updated_callback	The callback to be set. Required.

Returns

True on success; otherwise false.