gimbal_module.h File Reference

Go to the source code of this file.

Data Structures
struct	GblModuleClass
struct	GblModule

Macros
#define	GBL_REQUIRE(...)
#define	GBL_RELEASE(selfAddr)
#define	GBL_REQUIRE_SCOPE(...)
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)
Opening and Closing
Routines for acquiring and releasing a module.
GblModule *	GblModule_require (GblModule **ppSelf, const char *pName, const char *pVersion, const char *pFile, const char *pFunc, size_t line)
GblModule *	GblModule_requireQuark (GblModule **ppSelf, GblQuark name, const char *pVersion, const char *pFile, const char *pFunc, size_t line)
GBL_RESULT	GblModule_release (GblModule **ppModule)
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

2025 Agustín Bellagamba

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 33 of file gimbal_module.h.

GBL_MODULE

#define GBL_MODULE

(

self

)

Function-style GblInstance cast.

Definition at line 34 of file gimbal_module.h.

GBL_MODULE_CLASS

#define GBL_MODULE_CLASS

(

klass

)

Function-style GblClass cast.

Definition at line 35 of file gimbal_module.h.

GBL_MODULE_CLASSOF

#define GBL_MODULE_CLASSOF

(

self

)

Gets a GblModuleClass from GblInstance.

Definition at line 36 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.

Note

If the supplied pointer is non-NULL, the module is considered cached and is not going to be reloaded. This allows you to avoid dynamic lookups for subsequent calls when using the same pointer.

static MyModule* pModule = NULL;
if(!GBL_REQUIRE(MyModule, &pModule, "MyModule", "1.1.0"))
    GBL_LOG_ERROR("MyModule", "Failed to import module!");

Parameters

instanceStruct	Struct name for desired GblModule instance structure.
selfAddr	The address of a pointer to the instance to store the reference in.
name	Name of the module to import.
version	[optional] Major.minor.patch string for specific version.

Returns

A pointer to the imported module, or NULL if the import failed.

Definition at line 62 of file gimbal_module.h.

GBL_RELEASE

#define GBL_RELEASE

(

selfAddr

)

Macro directive for releasing a module.

Used to optionally "release" a module which has been previously imported, decrementing is "useCount" property, which causes the module to be dynamically unloaded upon hitting zero uses.

Note

This does not necessarily need to be called if you do not wish for your module to be dynamically unloaded at run-time.

Parameters

selfAddr

The address of a pointer pointing to a module.

Returns

GBL_RESULT status code.

Definition at line 77 of file gimbal_module.h.

GBL_REQUIRE_SCOPE

#define GBL_REQUIRE_SCOPE

(

...

)

Scoped macro directive for using a module.

Used to define a local scope in which a module will be imported upon entry and released upon exit.

TestModule* pModule = NULL;
GBL_REQUIRE_SCOPE(TestModule, &pModule) {
    TestModule_doStuff(pModule);
}

Warning

GBL_SCOPE_EXIT must be used to early-break from the scope without causing unwanted side-effects.

Parameters

instanceStruct	Struct name for desired GblModule instance structure.
selfAddr	Address of a pointer to the GblModule struct, which holds the reference.
name	Name of the module to import.
version	[optional] Major.minor.patch string for specific version.

Definition at line 100 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 110 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	(	GblModule **	ppSelf,
		const char *	pName,
		const char *	pVersion,
		const char *	pFile,
		const char *	pFunc,
		size_t	line )

Underlying method backing GBL_REQUIRE() macro, which should be used instead of calling this directly.

GblModule_requireQuark()

GblModule * GblModule_requireQuark	(	GblModule **	ppSelf,
		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_release()

GBL_RESULT GblModule_release

(

GblModule **

ppModule

)

Manually decrements the given module's usage count, and points the passed.

Parameters

ppModule

to NULL.

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.