GblClass Struct Reference

#include <gimbal_class.h>

Inheritance diagram for GblClass:

Data Fields
struct {
uintptr_t   metaClassInfo
}	private_

Related Symbols
(Note that these are not member symbols.)
	GBL_CLASS_SUPER (klass)
	GBL_CLASS_DEFAULT (klass)
#define	GBL_CLASS_PRIVATE(cType, klass)
#define	GBL_CLASS_PUBLIC(cType, priv)
#define	GBL_CLASS_TYPECHECK(cType, klass)
	GBL_CLASS_TYPECHECK_PREFIX (klass, typePrefix)
#define	GBL_CLASS_CAST(cType, klass)
	GBL_CLASS_CAST_PREFIX (klass, typePrefix)
	GBL_CLASS_TRY (klass, toType, cType)
	GBL_CLASS_TRY_PREFIX (klass, typePrefix)
GblClass *	GblClass_refDefault (GblType type)
GblRefCount	GblClass_unrefDefault (GblClass *pSelf)
GblClass *	GblClass_weakRefDefault (GblType type)
GblClass *	GblClass_createFloating (GblType type)
GBL_RESULT	GblClass_destroyFloating (GblClass *pSelf)
GBL_RESULT	GblClass_constructFloating (GblClass *pSelf, GblType type)
GBL_RESULT	GblClass_destructFloating (GblClass *pSelf)
Class Operators
Builtin operations for class structures
#define	GBL_CLASS(klass)
#define	GBL_CLASS_TYPEOF(klass)
#define	GBL_CLASS_PRIVATE(cType, klass)
#define	GBL_CLASS_PUBLIC(cType, priv)
#define	GBL_CLASS_TYPECHECK(cType, klass)
#define	GBL_CLASS_CAST(cType, klass)
#define	GBL_CLASS_AS(cType, klass)
Static Class Type UUID and cast operators
UUID and cast operators for builtin static root class type
#define	GBL_STATIC_CLASS_TYPE
#define	GBL_STATIC_CLASS(klass)
Type Conversions
Methods for type casting and checking
GblBool	GblClass_check (const GblClass *pSelf, GblType toType)
GblClass *	GblClass_cast (GblClass *pSelf, GblType toType)
GblClass *	GblClass_as (GblClass *pSelf, GblType toType)
Public and Private Data
Methods for accessing public and private segments
void *	GblClass_private (const GblClass *pSelf, GblType base)
GblClass *	GblClass_public (const void *pPrivate, GblType base)
Static Type Info
Methods for getting static class information
GblType	GblClass_typeOf (const GblClass *pSelf)
size_t	GblClass_size (const GblClass *pSelf)
size_t	GblClass_privateSize (const GblClass *pSelf)
size_t	GblClass_totalSize (const GblClass *pSelf)
Dynamic Flags
Methods for checking dyanmic runtime flags
GblBool	GblClass_isDefault (const GblClass *pSelf)
GblBool	GblClass_isOverridden (const GblClass *pSelf)
GblBool	GblClass_isInterface (const GblClass *pSelf)
GblBool	GblClass_isInterfaceImpl (const GblClass *pSelf)
GblBool	GblClass_isFloating (const GblClass *pSelf)
GblBool	GblClass_isOwned (const GblClass *pSelf)
GblBool	GblClass_isInPlace (const GblClass *pSelf)
Related Classes
Methods for fetching associated classes
GblClass *	GblClass_super (const GblClass *pSelf)
GblClass *	GblClass_default (const GblClass *pSelf)

Detailed Description

Base struct for all type classes.

A class represents a collection of data that is shared among all instances of a given type. This data is typically in the form of function pointers for modeling overridable methods or regular data for modeling static member variables.

GblClass is the base structure which is to be inherited by all class structures within the meta type system. This means placing it or a type "inheriting" from it as the first member of a class struct, when using C.

See also

GblInstance, GblType

Definition at line 76 of file gimbal_class.h.

Friends And Related Symbol Documentation

GBL_CLASS

GBL_CLASS (   klass )

related

Function-style cast to GblClass*: will always pass, here for consistence with other operators.

Parameters

klass

pointer to a GblClass-compatible

Returns

klass C-style casted to GblClass*

Convenience function-style casting macro.

Definition at line 34 of file gimbal_class.h.

GBL_CLASS_TYPEOF

GBL_CLASS_TYPEOF (   klass )

related

Wraps GblClass_typeOf(), returning the type associated with the given class.

Parameters

klass

pointer to a GblClass-compatible

Returns

type associated with the class, or GBL_INVALID_TYPE if NULL

See also

GblClass_typeOf() Convenience wrapper around GblClass_typeOf() which automatically casts.

Definition at line 36 of file gimbal_class.h.

GBL_CLASS_PRIVATE [1/2]

#define GBL_CLASS_PRIVATE (   cType,   klass  )

related

Wraps GblClass_private(), returning the private structure on the class associated with the given type.

Definition at line 38 of file gimbal_class.h.

GBL_CLASS_PUBLIC [1/2]

#define GBL_CLASS_PUBLIC (   cType,   priv  )

related

Wraps GblClass_public(), returning the public class structure from the given type's private structure.

Definition at line 40 of file gimbal_class.h.

GBL_CLASS_TYPECHECK [1/2]

#define GBL_CLASS_TYPECHECK (   cType,   klass  )

related

Returns GBL_TRUE if the given class is type-compatible with and can be safely casted to the given type.

Definition at line 42 of file gimbal_class.h.

GBL_CLASS_CAST [1/2]

#define GBL_CLASS_CAST (   cType,   klass  )

related

Wraps GblClass_cast(), casting the given class to another type, returning NULL and raising an error upon failure.

Definition at line 44 of file gimbal_class.h.

GBL_CLASS_AS

#define GBL_CLASS_AS (   cType,   klass  )

related

Wraps GblClass_as(), returning the given class as another type or gracefully returning NULL upon failure.

Definition at line 46 of file gimbal_class.h.

GBL_STATIC_CLASS_TYPE

#define GBL_STATIC_CLASS_TYPE

related

GblType UUID for builtin static class primitive.

Definition at line 53 of file gimbal_class.h.

GBL_STATIC_CLASS

#define GBL_STATIC_CLASS (   klass )

related

Casts a class to a static class.

Definition at line 54 of file gimbal_class.h.

GblClass_check()

GblBool GblClass_check ( const GblClass *  pSelf, GblType  toType  )

related

Returns GBL_TRUE if the given class can be casted to toType.

Returns true if the given class can be casted to the given class type.

Note

Also returns true if pClass is NULL AND toType is GBL_TYPE_INVALID, since that would semantically be a valid cast to the invalid type.

Parameters

pSelf	class pointer
toType	desired destination type

Returns

true upon success

See also

GblClass_cast, GblClass_as

GblClass_cast()

GblClass * GblClass_cast ( GblClass *  pSelf, GblType  toType  )

related

Casts the given class to a toType class, or returns NULL and emits an error if unsuccessful.

Casts the given class to a class of the given type, raising errors and returning NULL upon failure.

Parameters

pSelf	source class pointer
toType	desired destination type

Returns

pointer to GblClass upon success, NULL upon failure

See also

GBL_CLASS_CAST(), GblClass_check, GblClass_as

GblClass_as()

GblClass * GblClass_as ( GblClass *  pSelf, GblType  toType  )

related

Casts the given class to a toType class, or gracefully returns NULL without erroring.

Equivalent to GblClass_cast(), except gracefully returning NULL with no errors getting raised if the given class could not be casted to toType.

Note

This is equivalent to a C++ dynamic cast.

Parameters

pSelf	source class
toType	desired destination type

Returns

pointer to GblClass or NULL upon failure

See also

GBL_CLASS_TRY(), GblClass_cast(), GblClass_check()

GblClass_private()

void * GblClass_private ( const GblClass *  pSelf, GblType  type  )

related

Returns the private structure associated with the given base type of the class.

Retrieves the private data pointer associated with the given base type or NULL if there isn't one.

Parameters

pSelf	class pointer
type	type owning the private data

Returns

pointer to private data or NULL upon failure

See also

GblClass_public()

GblClass_public()

GblClass * GblClass_public ( const void *  pPrivate, GblType  base  )

related

Casts back to the class structure from a base type's private data segment structure.

Retrieves the public GblClass corresponding to the given private data pointer for the given type or base type or NULL upon failure.

Parameters

pPrivate	pointer to private data
base	type or base type that registered the private data

Returns

pointer to public GblClass* or NULL upon failure

GblClass_typeOf()

GblType GblClass_typeOf ( const GblClass *  pSelf )

related

Returns the GblType UUID associated with the given class.

Returns the type associated with the given GblClass pointer, or GBL_INVALID_TYPE if the pointer is NULL.

Parameters

pSelf

pointer to a GblClass

Returns

type ID of the class or GBL_INVALID_TYPE if NULL

GblClass_size()

size_t GblClass_size ( const GblClass *  pSelf )

related

Returns the size of the given class's public class structrue.

Returns the size of the public class structure for the given GblClass pointer or 0 if NULL.

Parameters

pSelf

pointer to a GblClass

Returns

size or 0 if class is NULL

See also

GblClass_privateSize(), GblClass_totalSize()

GblClass_privateSize()

size_t GblClass_privateSize ( const GblClass *  pSelf )

related

Returns the combined size of the class's private data segments.

Returns the TOTAL size of the private data structure associated with the type of the given class and all of its base types.

Parameters

pSelf

pointer to a GblClass

Returns

size or 0 if class is NULL

See also

GblClass_size(), GblClass_totalSize()

GblClass_totalSize()

size_t GblClass_totalSize ( const GblClass *  pSelf )

related

Returns the class's combined DEFAULT size (not extended allocation size)

Returns the total combined size of the public and private class structures for the class type and all of its inherited bases.

Parameters

pSelf

pointer to a GblClass

Returns

size or 0 if class is NULL

See also

GblClass_size(), GblClass_privateSize()

GblClass_isDefault()

GblBool GblClass_isDefault ( const GblClass *  pSelf )

related

Returns GBL_TRUE if the class is the internally-managed default for its type.

Returns true if the given GblClass pointer points to the internally-managed default class for its type or false if it not the default.

Note

Note: The class will not be the default if it was created as separate floating class, or if it's the implementation of a GblInterface on another GblClass.

Parameters

pSelf

pointer to a GblClass

Returns

true if default, false if not or if pSelf is NULL

See also

GblClass_default()

GblClass_isOverridden()

GblBool GblClass_isOverridden ( const GblClass *  pSelf )

related

Returns GBL_TRUE if the class differs from the default class for its type.

Inspects the internal memory of the given GblClass pointer and compares it to that of the internally managed default class, returning true if they differ or false if they are the same.

Note

Note: Just because a class is a floating class or an interface implementation doesn't necessarily mean it has actually been overridden to have non-default values!

Parameters

pSelf

pointer to a GblClass

Returns

true if overridden, false if not or if pSelf is NULL

GblClass_isInterface()

GblBool GblClass_isInterface ( const GblClass *  pSelf )

related

Returns GBL_TRUE if the class is an interfaced type.

Returns true if the given GblClass is actually of or derived from GBL_INTERFACE_TYPE, false otherwise.

Parameters

pSelf

pointer to a GblClass

Returns

true if pSelf is a GblInterface, false if not or if pSelf is NULL

See also

GblClass_isInterfaceImpl

GblClass_isInterfaceImpl()

GblBool GblClass_isInterfaceImpl ( const GblClass *  pSelf )

related

Returns GBL_TRUE if the class is another class's implementation of an interface.

Returns true if the given GblClass an interface implementation wihch has been mapped onto another GblClass, false otherwise.

Parameters

pSelf

pointer to a GblClass

Returns

true if pSelf is a mapped GblInterface, false if not or if pSelf is NULL

See also

GblClass_isInterface

GblClass_isFloating()

GblBool GblClass_isFloating ( const GblClass *  pSelf )

related

Returns GBL_TRUE if the class is a non-default floating class and is unowned by an instance.

Returns true if the given GblClass is an unowned, floating class which must be manually managed, or false if it is either the default class or has been sunk by a GblInstance.

Parameters

pSelf

pointer to a GblClass

Returns

true if floating, false if not or if pSelf is NULL

See also

GblClass_createFloating(), GblClass_constructFloating(), GblInstance_sinkClass(), GblInstance_floatClass()

GblClass_isOwned()

GblBool GblClass_isOwned ( const GblClass *  pSelf )

related

Returns GBL_TRUE if the class is a non-default floating class is uowned by an instance.

Returns true if the given GblClass is a previously floating, nondefault class which has been sunk and is now owned by a GblInstance.

Note

This means that its lifetime has been bound to that of the instance, and it will be destructed (and deleted if necessary) with the instance.

Parameters

pSelf

pointer to a GblClass

Returns

true if pSelf is a owned by a GblInstance, false if not or if pSelf is NULL

See also

GblInstance_sinkClass(), GblInstance_floatClass()

GblClass_isInPlace()

GblBool GblClass_isInPlace ( const GblClass *  pSelf )

related

Returns GBL_TRUE if the class was constructed in-place with an existing allocation.

Returns true if the given GblClass was constructed from an existing, user-managed allocation, using GblClass_constructFloating().

Note

If a GblClass is both floating and in-place, it means that you are responsible for uninitializing it manually via GblClass_destructFloating()

Parameters

pSelf

pointer to a GblClass

Returns

true if pSelf was constructed in-place, false if not or if pSelf is NULL

See also

GblClass_constructFloating(), GblClass_destructFloating()

GblClass_super()

GblClass * GblClass_super ( const GblClass *  pSelf )

related

Returns the default class of the class's parent type or NULL if it's a root class.

Returns the default class for the parent type of the given class type.

This is typically used in the implementation of overridden methods to allow you to call into the base class's implementations.

Note

The returned class is a weak reference and does not impact the reference count for the parent's default class.

Parameters

pSelf

pointer to a GblClass

Returns

pointer to parent GblClass or NULL if the given class is NULL or has no parent

See also

GblClass_default()

GblClass_default()

GblClass * GblClass_default ( const GblClass *  pSelf )

related

Returns the default implementation of the given class.

Returns a weak reference to the internally-managed default class corresonding to the given class's type.

This will only be different than the given argument if the class has been created either as a floating class, or if it is a pointer to the implementation of an interface. In the case of an interface, this is how you access the interface's default implementation as well.

Note

The returned class is a weak reference and does not impact the reference count for the default class.

Parameters

pSelf

pointer to a GblClass

Returns

pointer to default GblClass or NULL if the given class is NULL

See also

GblClass_isDefault()

GBL_CLASS_SUPER()

GBL_CLASS_SUPER ( klass  )

related

Parameters

klass

pointer to a GblClass-compatible

Returns

parent class of the given class, or GBL_INVALID_TYPE if NULL

See also

GblClass_super() Convenience wrapper around GblClass_super() which automatically casts.

GBL_CLASS_DEFAULT()

GBL_CLASS_DEFAULT ( klass  )

related

Parameters

klass

pointer to a GblClass-compatible

Returns

default class of the given class, or GBL_INVALID_TYPE if NULL

See also

GblClass_default() Convenience wrapper around GblClass_default() which automatically casts.

GBL_CLASS_PRIVATE [2/2]

#define GBL_CLASS_PRIVATE (   klass,   type  )

related

Parameters

klass	pointer to a GblClass-compatible
type	supertype owning the private data

Returns

private data owned by the given superType or NULL if type there is none or type is not a parent, or type is invalid

See also

GblClass_private() Convenience wrapper around GblClass_private() which automatically casts.

GBL_CLASS_PUBLIC [2/2]

#define GBL_CLASS_PUBLIC (   klassPrivate,   type  )

related

Parameters

klassPrivate	void* pointer to private class data
type	supertype owning the private data

Returns

public GblClass* pointer or NULL if none could be found

See also

GblClass_public() Convenience wrapper around GblClass_public().

GBL_CLASS_TYPECHECK [2/2]

#define GBL_CLASS_TYPECHECK (   klass,   toType  )

related

Parameters

klass	pointer to a GblClass-compatible
toType	the desired destination type

Returns

true if the given class can be casted to a calss of toType

See also

GblClass_check(), GBL_CLASS_TYPECHECK_REFIX() Convenience wrapper around GblClass_check() which automatically casts.

GBL_CLASS_TYPECHECK_PREFIX()

GBL_CLASS_TYPECHECK_PREFIX ( klass  , typePrefix    )

related

Parameters

klass	pointer to a GblClass-compatible
typePrefix	prefix of the given type (type name macro identifier minus _TYPE postfix)

Returns

true if the given class can be casted to a calss of toType

See also

GBL_CLASS_TYPECHECK_PREFIX(), GblClass_check()

Convenience wrapper around GBL_CLASS_TYPECHECK() which automatically appends _TYPE suffix.

Note

This macro is typically used for definining convenience function-style casting utilities for derived types.

GBL_CLASS_CAST [2/2]

#define GBL_CLASS_CAST (   klass,   toType,   cType  )

related

Parameters

klass	pointer to a GblClass-compatible
toType	desination type for resulting class
cType	C structure for the given type's class

Returns

klass casted to cType if the cast was successful, otherwise NULL

See also

GBL_CLASS_CAST_PREFIX(), GblClass_cast(

Convenience wrapper around GblClass_cast() which automatically performs casting.

GBL_CLASS_CAST_PREFIX()

GBL_CLASS_CAST_PREFIX ( klass  , typePrefix    )

related

Parameters

klass	pointer to a GblClass-compatible
typePrefix	prefix of destination type (NAME macro minus the _TYPE suffix)

Note

This macro also requires a macro be defined that is the given typePrefix appended with _CLASS_STRUCT, which it uses as the destination class type for casting.

Returns

klass casted to the formed type identifier upon success, NULL otherwise

See also

GBL_CLASS_CAST(), GblClass_cast()

Convenience wrapper around GBL_CLASS_CAST() which automatically deduces class structure and type identifier.

Note

This macro is typically used for definining convenience function-style casting utilities for derived types.

GBL_CLASS_TRY()

GBL_CLASS_TRY ( klass  , toType  , cType    )

related

Parameters

klass	pointer to a GblClass-compatible
toType	desination type for resulting class
cType	C structure for the given type's class

Returns

klass casted to cType if the cast was successful, otherwise NULL

See also

GBL_CLASS_TRY_PREFIX(), GblClass_as(

Convenience wrapper around GblClass_as() which automatically performs casting.

GBL_CLASS_TRY_PREFIX()

GBL_CLASS_TRY_PREFIX ( klass  , typePrefix    )

related

Parameters

klass	pointer to a GblClass-compatible
typePrefix	prefix of destination type (NAME macro minus the _TYPE suffix)

Note

This macro also requires a macro be defined that is the given typePrefix appended with _CLASS_STRUCT, which it uses as the destination class type for casting.

Returns

klass casted to the formed type identifier upon success, NULL otherwise

See also

GBL_CLASS_TRY(), GblClass_as()

Convenience wrapper around GBL_CLASS_TRY() which automatically deduces class structure and type identifier.

Note

This macro is typically used for defining convenience function-style casting utilities for derived types.

GblClass_refDefault()

GblClass * GblClass_refDefault ( GblType  type )

related

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 )

related

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 )

related

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 )

related

Creates a new, unowned class for the given type on the heap.

Parameters

type	classed type ID

Returns

dynamically allocated unowned class

See also

GblClass_constructFloating, GblClass_destroyFloating, floatingClasses

GblClass_destroyFloating()

GBL_RESULT GblClass_destroyFloating ( GblClass *  pSelf )

related

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_constructFloating()

GBL_RESULT GblClass_constructFloating ( GblClass *  pSelf, GblType  type  )

related

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_destructFloating()

GBL_RESULT GblClass_destructFloating ( GblClass *  pSelf )

related

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

Field Documentation

metaClassInfo

uintptr_t GblClass::metaClassInfo

PRIVATE: Pointer-sized opaque member.

Definition at line 78 of file gimbal_class.h.

---

The documentation for this struct was generated from the following file:

• gimbal_class.h