gimbal_class.h File Reference

Go to the source code of this file.

Data Structures
struct	GblClass

Functions
Default Class Management
Methods for managing references to internally-managed default class instances
GblClass *	GblClass_refDefault (GblType type)
GblRefCount	GblClass_unrefDefault (GblClass *pSelf)
GblClass *	GblClass_weakRefDefault (GblType type)
Floating Class Mangement
Methods for managing lifetime of dynamic override class instances
GblClass *	GblClass_createFloating (GblType type, size_t size)
GBL_RESULT	GblClass_constructFloating (GblClass *pSelf, GblType type)
GBL_RESULT	GblClass_destroyFloating (GblClass *pSelf)
GBL_RESULT	GblClass_destructFloating (GblClass *pSelf)

Detailed Description

GblClass virtual-table structure and APIE.

This file contains the GblClass structure, which is the inherited base type and first data member of all derievd class structures.

While GblClass itself is empty other than its basic type info, a derived class typically contains data which is shared by all instances of a type, for deduplication and efficiency.

This data is typically in the form of:

• Overridable virtual methods (in the form of function pointers)
• Static class data

See also

gimbal_instance.h, gimbal_type.h

Author

2023 Falco Girgis

Copyright

MIT License

Definition in file gimbal_class.h.

Function Documentation

GblClass_refDefault()

GblClass * GblClass_refDefault

(

GblType

type

)

Returns a reference to the default class for type, instantiating it if necessary.

Returns a new reference to the existing internally managed default class for the given type or lazily allocates a new one with an initial refCount of 1.

Note

When you're done using the reference, it must be released using GblClass_unrefDefault() in order to avoid memory leaks!

Parameters

type	classed type ID

Returns

reference to internally managed class

See also

GblClass_weakRefDefault, GblClass_unrefDefault

GblClass_unrefDefault()

GblRefCount GblClass_unrefDefault

(

GblClass *

pSelf

)

Releases a reference to the default version of the given class, possibly freeing it.

Release a reference to the default class associated with pSelf, destroying the class if it's reference count hits 0.

Note

This should not be called to release a previously floating class, as it is not reference-counted. See GblClass_destructFloating and GblClass_destroyFloating

It is safe to call this function with a NULL class, as libGimbal tries to be consistent with free() semantics.

Types may be flagged as "persisting", despite their reference counts hitting zero. This is used for builtin types. See GBL_TYPE_FLAG_CLASS_PINNED.

Parameters

pSelf

reference to class

Returns

remaining reference count

See also

GblClass_refDefault

GblClass_weakRefDefault()

GblClass * GblClass_weakRefDefault

(

GblType

type

)

Returns a reference to the default class for type or NULL if it hasn't been created.

Returns a pointer to the default class for the given type without incrementing refCount.

Note

If there has not yet been a class created, or one is no longer active, this call will raise an error followed by returning NULL. Since no references are being created, only use this within contexts where you know a class reference already exists.

Parameters

type	type of desired class

Returns

pointer to a GblClss or NULL upon failure

See also

GblClass_refDefault

GblClass_createFloating()

GblClass * GblClass_createFloating	(	GblType	type,
		size_t	size
	)

Creates a standalone, unowned, "floating" class for the given type, which can override defaults.

GblClass_constructFloating()

GBL_RESULT GblClass_constructFloating	(	GblClass *	pSelf,
		GblType	type
	)

Constructs a standalone, unowned, overridable, "floating" class for the given type in-place.

Placement constructs an unowned class for the given type using an existing user-provided allocation.

Parameters

pSelf	pointer to instance allocation
type	type of instance to construct

Returns

result code

See also

GblClass_createFloating, GblClass_destructFloating

GblClass_destroyFloating()

GBL_RESULT GblClass_destroyFloating

(

GblClass *

pSelf

)

Destroys the standalone, "floating" class, releasing its memory allocation.

Destructs then frees the given heap-allocated, floating class.

Note

It is safe to call this function with a NULL class, as libGimbal tries to be consistent with free() semantics.

Attention

Do not call this with a stack-constructed in-place floating class constructed with GblClass_constructFloating() Luckily libGyro will catch it for you and return an error.

Parameters

pSelf

GblClass pointer

Returns

destructor result code or GBL_RESULT_ERROR_INVALID_OPERATION

See also

GblClass_destructFloating, GblClass_createFloating

GblClass_destructFloating()

GBL_RESULT GblClass_destructFloating

(

GblClass *

pSelf

)

Destructs the standalone, "floating" class, without releasing any allocated resources.

Calls placement delete on the given floating class which was constructed in-place, using GblClass_constructFloating.

It is safe to call this function with a NULL class, as libGimbal tries to be consistent with free() semantics.

Attention

Do not call this with a heap-allocated floating class, created with GblClass_createFloating(). Luckily libGyro will catch it for you and return an error.

Parameters

pSelf

class pointer

Returns

destructor result code or GBL_RESULT_ERROR_INVALID_OPERATION

See also

GblClass_destroyFloating, GblClass_constructFloating