Data Structures
struct	GblModuleClass

struct	GblModule

Macros
#define	GBL_REQUIRE(...)

Type System
Type UUID and cast operators.
#define	GBL_MODULE_TYPE

#define	GBL_MODULE(self)

#define	GBL_MODULE_CLASS(klass)

#define	GBL_MODULE_CLASSOF(self)

Typedefs
typedef GblBool(*	GblModuleIterFn) (GblModule pIt, void pClosure)

Functions
GblType	GblModule_type (void)

Registry
Static routines for querying the module registry.
GblModule *	GblModule_find (const char *pName)

GblModule *	GblModule_findQuark (GblQuark name)

GblModule *	GblModule_at (size_t index)

size_t	GblModule_count (void)

GblBool	GblModule_iterate (GblModuleIterFn pFnIter, void *pCl)

Importing
Routines for returning a module
GblModule *	GblModule_require (const char pName, const char pVersion, const char pFile, const char pFunc, size_t line)

GblModule *	GblModule_requireQuark (GblQuark name, const char pVersion, const char pFile, const char *pFunc, size_t line)

Lifetime
Methods for creating and destroying modules.
GblModule *	GblModule_create (GblType derivedType, const char pName, GblVersion version, const char pAuthor, const char pDescription, const char pPrefix)

GblRefCount	GblModule_unref (GblModule *pSelf)

Registration
Methods for adding and removing from the registry.
GBL_RESULT	GblModule_register (GblModule *pSelf)

GBL_RESULT	GblModule_unregister (GblModule *pSelf)

Loading/Unloading
Routines for controlling when a module is loaded and unloaded.
GBL_RESULT	GblModule_use (GblModule *pSelf)

GBL_RESULT	GblModule_unuse (GblModule *pSelf)

GblRefCount	GblModule_useCount (const GblModule *pSelf)

GblBool	GblModule_isLoaded (const GblModule *pSelf)

Detailed Description

Dynamic module and plugin system.

This file contains the type declarations of GblModule and its associated API, providing the functionality of a static registry of lazily loaded "services" or C++ singleton types and their associated type registry.

Todo

advanced unit testing
plan out type registration/management
rig up option group parsery
stop inheriting GblContext

Author: 2023, 2025 Falco Girgis

Copyright: MIT License

Definition in file gimbal_module.h.

Macro Definition Documentation

◆ GBL_MODULE_TYPE

#define GBL_MODULE_TYPE

Type UUID for GblModule.

Definition at line 32 of file gimbal_module.h.

◆ GBL_MODULE

#define GBL_MODULE ( self )

Function-style GblInstance cast.

Definition at line 33 of file gimbal_module.h.

◆ GBL_MODULE_CLASS

#define GBL_MODULE_CLASS ( klass )

Function-style GblClass cast.

Definition at line 34 of file gimbal_module.h.

◆ GBL_MODULE_CLASSOF

#define GBL_MODULE_CLASSOF ( self )

Gets a GblModuleClass from GblInstance.

Definition at line 35 of file gimbal_module.h.

◆ GBL_REQUIRE

#define GBL_REQUIRE ( ... )

Macro directive for importing a module.

Used to "import" a GblModule whose type has been registered with the type system, lazily loading it the fist time and returning references to it subsequently.

MyModule* module = GBL_REQUIRE(MyModule, "1.0.1");

GBL_ASSERT(module, "Failed to load MyModule!");

GBL_REQUIRE

#define GBL_REQUIRE(...)

Macro directive for importing a module.

Definition gimbal_module.h:54

Parameters

typename	Struct name for desired GblModule instance structure.
version	[optional] Major.minor.patch string for specific version.

Return values

GblModule*	An auto-casted pointer to the instance of the desire module.
NULL	The module wasn't present or the version was too low.

Definition at line 54 of file gimbal_module.h.

Typedef Documentation

◆ GblModuleIterFn

typedef GblBool(* GblModuleIterFn) (GblModule *pIt, void *pClosure)

Function callback used with GblModule_foreach() for iterating over active modules, returning GBL_TRUE to end iteration early.

Definition at line 64 of file gimbal_module.h.

Function Documentation

◆ GblModule_type()

GblType GblModule_type ( void )

Returns the GblType UUID associated with GblModule.

◆ GblModule_find()

GblModule * GblModule_find ( const char * pName )

Returns a pointer to the module with the gibven name, if present, gracefully returning NULL otherwise.

◆ GblModule_findQuark()

GblModule * GblModule_findQuark ( GblQuark name )

Equivalent to GblModule_find(), except doing a faster search using a GblQuark for the name.

◆ GblModule_at()

GblModule * GblModule_at ( size_t index )

Returns a pointer to the GblModule which has been loaded at the given index, or NULL if there isn't one.

◆ GblModule_count()

size_t GblModule_count ( void )

Returns the total number of modules which have been registered.

◆ GblModule_iterate()

GblBool GblModule_iterate	(	GblModuleIterFn	pFnIter,
		void *	pCl )

Iterates over every registered module, invoking the provided iterator callback, optionally passing back an arbitrary userdata closure pointer.

◆ GblModule_require()

GblModule * GblModule_require	(	const char *	pName,
		const char *	pVersion,
		const char *	pFile,
		const char *	pFunc,
		size_t	line )

Loads or returns a module matching the given name and optional version identifier, raising an error and returning NULL if there was no match.

◆ GblModule_requireQuark()

GblModule * GblModule_requireQuark	(	GblQuark	name,
		const char *	pVersion,
		const char *	pFile,
		const char *	pFunc,
		size_t	line )

Equivalent to GblModule_require(), except using a faster quark for the name identifier.

◆ GblModule_create()

GblModule * GblModule_create	(	GblType	derivedType,
		const char *	pName,
		GblVersion	version,
		const char *	pAuthor,
		const char *	pDescription,
		const char *	pPrefix )

Creates and returns a reference to a new GblModule-compatible instance type, but does not add it to the registry.

◆ GblModule_unref()

GblRefCount GblModule_unref ( GblModule * pSelf )

Releases a reference to a previously created GblModule instance, destructing and freeing it if there are no references left.

◆ GblModule_register()

GBL_RESULT GblModule_register ( GblModule * pSelf )

Attempts to register a previously instantiated GblModule instance as a globally importable module within the internal registry.

◆ GblModule_unregister()

GBL_RESULT GblModule_unregister ( GblModule * pSelf )

Attempts to unregister a previously registered GblModule instance, removing it from the internal registry.

◆ GblModule_use()

GBL_RESULT GblModule_use ( GblModule * pSelf )

Manually increments the given module's usage count, loading it on first usage. You can manually control its lifetimeto prevent being dynamically unloaded like this.

◆ GblModule_unuse()

GBL_RESULT GblModule_unuse ( GblModule * pSelf )

Manually decrements the given module's usage count, unloading it when the last user is done. You can manually control unloading it like this.

◆ GblModule_useCount()

GblRefCount GblModule_useCount ( const GblModule * pSelf )

Retrieves the current usage counter for the given module.

◆ GblModule_isLoaded()

GblBool GblModule_isLoaded ( const GblModule * pSelf )

Returns true if the given module is currently loaded and has active uses, return false otherwise.

Data Structures

Macros

Typedefs

Functions