GblInstance Struct Reference

#include <gimbal_instance.h>

Inheritance diagram for GblInstance:

Data Fields
GblClass *	pClass

Related Symbols
(Note that these are not member symbols.)
GblRefCount	GblInstance_destroy (GblInstance *pSelf)
Instance Operators
Builtin operations for Instance-derived types
#define	GBL_TYPEOF(self)
#define	GBL_PRIVATE(cType, self)
#define	GBL_PUBLIC(cType, selfPriv)
#define	GBL_TYPECHECK(cType, self)
#define	GBL_CAST(cType, self)
#define	GBL_AS(cType, self)
#define	GBL_CLASSOF(cType, self)
#define	GBL_CLASSOF_AS(cType, self)
#define	GBL_VCALL(cType, method, ...)
#define	GBL_VCALL_DEFAULT(cType, method, ...)
Type Conversions
Methods for type casting and checking
GblBool	GblInstance_check (const GblInstance *pSelf, GblType toType)
GblInstance *	GblInstance_cast (GblInstance *pSelf, GblType toType)
GblInstance *	GblInstance_as (GblInstance *pSelf, GblType toType)
Public and Private Data
Methods for accessing public and private segments
void *	GblInstance_private (const GblInstance *pSelf, GblType base)
GblInstance *	GblInstance_public (const void *pPriv, GblType base)
Type Info
Methods for getting instance information
GblType	GblInstance_typeOf (const GblInstance *pSelf)
size_t	GblInstance_size (const GblInstance *pSelf)
size_t	GblInstance_privateSize (const GblInstance *pSelf)
size_t	GblInstance_totalSize (const GblInstance *pSelf)
Classes
Methods for managing classes
GblClass *	GblInstance_class (const GblInstance *pSelf)
GBL_RESULT	GblInstance_swizzleClass (GblInstance *pSelf, GblClass *pClass)
GBL_RESULT	GblInstance_sinkClass (GblInstance *pSelf)
GBL_RESULT	GblInstance_floatClass (GblInstance *pSelf)

Detailed Description

Base struct for all instantiable meta types.

An Instance simply represents an object that can be created from a given GblType which shares some data with other instances of the same type, located within their class.

GblInstance is the base structure which is to be inherited by instances of all instantiable types. This means placing it or a type inheriting from it as the first member of an instance struct.

Note

As the root instantiable type, an instance contains nothing but a pointer to its corresponding class. Its as lightweight as possible.

See also

GblClass, GblType, GblBox, GblObject

Definition at line 79 of file gimbal_instance.h.

Friends And Related Symbol Documentation

GBL_TYPEOF

#define GBL_TYPEOF (   self )

related

Returns the type UUID for a GblInstance.

Definition at line 37 of file gimbal_instance.h.

GBL_PRIVATE

#define GBL_PRIVATE (   cType,   self  )

related

Wraps GblInstance_private(), passing the given type and returning its private structure.

Definition at line 39 of file gimbal_instance.h.

GBL_PUBLIC

#define GBL_PUBLIC (   cType,   selfPriv  )

related

Wraps GblInstance_public(), passing the given type, and returning its public struct.

Definition at line 41 of file gimbal_instance.h.

GBL_TYPECHECK

#define GBL_TYPECHECK (   cType,   self  )

related

Returns GBL_TRUE if the instance can be casted to the given type safely.

Definition at line 43 of file gimbal_instance.h.

GBL_CAST

#define GBL_CAST (   cType,   self  )

related

Wraps GblInstance_cast() for the given type, implementing a convenient cast operator.

Definition at line 45 of file gimbal_instance.h.

GBL_AS

#define GBL_AS (   cType,   self  )

related

Wraps GblInstance_as() for the given type, providing a gracefully-failing case.

Definition at line 47 of file gimbal_instance.h.

GBL_CLASSOF

#define GBL_CLASSOF (   cType,   self  )

related

Casts to the given instance type, then returns its class, returning NULL and raising an error upon failure.

Definition at line 49 of file gimbal_instance.h.

GBL_CLASSOF_AS

#define GBL_CLASSOF_AS (   cType,   self  )

related

Uses GblInstance_as(), then gets its class (if successful) or returns NULL without raising an error.

Definition at line 51 of file gimbal_instance.h.

GBL_VCALL

#define GBL_VCALL (   cType,   method,   ...  )

related

Invokes a virtual method on the given type's class, passing the variadic arguments directly through to it as method arguments.

Definition at line 53 of file gimbal_instance.h.

GBL_VCALL_DEFAULT

#define GBL_VCALL_DEFAULT (   cType,   method,   ...  )

related

Invokes a virtual method on the default class for a given type, used for calling into parent or default methods.

Definition at line 55 of file gimbal_instance.h.

GblInstance_check()

GblBool GblInstance_check ( const GblInstance *  pSelf, GblType  toType  )

related

Returns GBL_TRUE if the given instance's type is compatible with toType.

Returns true if the given instance can be casted to an instance of the given type.

Parameters

pSelf	source instance
toType	casted result type

Returns

true if cast is valid

See also

GblInstance_as

GblInstance_cast()

GblInstance * GblInstance_cast ( GblInstance *  pSelf, GblType  toType  )

related

Attempts to cast the given instance to toType, raising an error and returning NULL upon failure.

Casts the given instance to the given type, erroring-out upon failure.

Parameters

pSelf	source instance
toType	casted result type

Returns

pointer to casted instance or NULL upon failure

See also

GblInstance_check, GblInstance_as

GblInstance_as()

GblInstance * GblInstance_as ( GblInstance *  pSelf, GblType  toType  )

related

Attempts to cast the given instance to toType, gracefully returning NULL upon failure.

Equivalent to GblInstance_cast(), except gracefully returning NULL with no errors upon failure.

This is analogous to a dynamic_cast<> operation in C++.

Parameters

pSelf	source instance
toType	casted result type

Returns

pointer to casted instance or NULL upon failure

See also

GblInstance_cast

GblInstance_private()

void * GblInstance_private ( const GblInstance *  pSelf, GblType  base  )

related

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

Returns the private instance data associated with the base or actual type of the given public instance structure.

Parameters

pSelf	source instance
base	type ID to fetch private data for

Returns

pointer to private data upon success, NULL upon failure

GblInstance_public()

GblInstance * GblInstance_public ( const void *  pPrivate, GblType  base  )

related

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

Returns the public GblInstance structure for the given private data and its associated base or actual type.

Parameters

pPrivate	private data pointer
base	type corresponding to the private data

Returns

pointer to instance upon success, NULL upon failure

GblInstance_typeOf()

GblType GblInstance_typeOf ( const GblInstance *  pSelf )

related

Returns the GblType associated with the given GblInstance.

Returns the type ID associated with the given instance.

Parameters

pSelf

instance pointer

Returns

type ID or NULL if the instance is NULL

GblInstance_size()

size_t GblInstance_size ( const GblInstance *  pSelf )

related

Returns the size of the given GblInstance's public data segment.

Returns the size of the public instance struct for the given instance.

Parameters

pSelf

instance pointer

Returns

size or 0 if instance is NULL

See also

GblInstance_privateSize, GblInstance_totalSize

GblInstance_privateSize()

size_t GblInstance_privateSize ( const GblInstance *  pSelf )

related

Returns the size of the given GblInstance's private data segment.

Returns the size of the private instance struct for the given instance.

Parameters

pSelf

instance pointer

Returns

size or 0 if instance is NULL

GblInstance_totalSize()

size_t GblInstance_totalSize ( const GblInstance *  pSelf )

related

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

Returns the total size for both public and private instance data for the given instance.

Parameters

pSelf

instance pointer

Returns

size or 0 if instance is NULL

GblInstance_class()

GblClcass * GblInstance_class ( const GblInstance *  pSelf )

related

Returns the GblClass associated with the given GblInstance.

Returns the public class structure associated with the given instance.

Parameters

pSelf

instance pointer

Returns

class pointer or NULL if instance is NULL

GblInstance_swizzleClass()

GBL_RESULT GblInstance_swizzleClass ( GblInstance *  pSelf, GblClass *  pClass  )

related

Swaps out the class associated with the instance, without taking ownership of it.

Releases ownership of the instance's current class, replacing it with a type-compatible class.

This is analogous to Objective-C's "is-a swizzling."

Note

The instance does not automatically assume ownersip of the new class.

Parameters

pSelf	instance
pClass	replacement GblClass of compatible type

Returns

result code

See also

GblInstance_sinkClass

GblInstance_sinkClass()

GBL_RESULT GblInstance_sinkClass ( GblInstance *  pSelf )

related

Takes ownership of the class associated with the instance, deallocating it with the instance.

Claims ownership of the previously floating class contained by the instance, binding the lifetime of the two, so that the class will be finalized when the instance is finalized.

Attention

ONLY a GblClass that has been created or constructed as a floating class can be sunk. Attempting to sink the default class for a given type will result in an erro!

Parameters

pSelf

instance

Returns

result code

See also

GblInstance_floatClass, GblClass_isFloating(), GblClass_createFloating(), GblClass_constructFloating()

GblInstance_floatClass()

GBL_RESULT GblInstance_floatClass ( GblInstance *  pSelf )

related

Relinquishes ownership of the class assosciated with the instance, but maintaining their association.

Releases ownership of the owned class contained by the instance.

The class will no longer be finalized along with the given instance.

Parameters

pSelf

instance

Returns

result code

See also

GblInstance_sinkClass

GblInstance_destroy()

GblRefCount GblInstance_destroy ( GblInstance *  pSelf )

related

Finalizes then deletes an instance that was created on the heap, either unreferencing.

its class if using the default or destroying it if using a sunk floating class.

Parameters

pSelf

heap-callocated instance

Returns

remaining number of active instances of the associated type

See also

GblInstance_destruct

Field Documentation

pClass

GblClass* GblInstance::pClass

READ-ONLY Pointer to Instance's Class, do not modify directly.

Definition at line 80 of file gimbal_instance.h.

---

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

• gimbal_instance.h