GType

GType — The GLib Runtime type identification and management system

Synopsis


#include <glib-object.h>


typedef     GType;
#define     G_TYPE_FUNDAMENTAL              (type)
#define     G_TYPE_FUNDAMENTAL_MAX
#define     G_TYPE_MAKE_FUNDAMENTAL         (x)
#define     G_TYPE_IS_ABSTRACT              (type)
#define     G_TYPE_IS_DERIVED               (type)
#define     G_TYPE_IS_FUNDAMENTAL           (type)
#define     G_TYPE_IS_VALUE_TYPE            (type)
#define     G_TYPE_HAS_VALUE_TABLE          (type)
#define     G_TYPE_IS_CLASSED               (type)
#define     G_TYPE_IS_INSTANTIATABLE        (type)
#define     G_TYPE_IS_DERIVABLE             (type)
#define     G_TYPE_IS_DEEP_DERIVABLE        (type)
#define     G_TYPE_IS_INTERFACE             (type)
            GTypeInterface;
            GTypeInstance;
            GTypeClass;
            GTypeInfo;
            GTypeFundamentalInfo;
            GInterfaceInfo;
            GTypeValueTable;
#define     G_TYPE_FROM_INSTANCE            (instance)
#define     G_TYPE_FROM_CLASS               (g_class)
#define     G_TYPE_FROM_INTERFACE           (g_iface)
#define     G_TYPE_INSTANCE_GET_CLASS       (instance, g_type, c_type)
#define     G_TYPE_INSTANCE_GET_INTERFACE   (instance, g_type, c_type)
#define     G_TYPE_INSTANCE_GET_PRIVATE     (instance, g_type, c_type)
#define     G_TYPE_CHECK_INSTANCE           (instance)
#define     G_TYPE_CHECK_INSTANCE_CAST      (instance, g_type, c_type)
#define     G_TYPE_CHECK_INSTANCE_TYPE      (instance, g_type)
#define     G_TYPE_CHECK_CLASS_CAST         (g_class, g_type, c_type)
#define     G_TYPE_CHECK_CLASS_TYPE         (g_class, g_type)
#define     G_TYPE_CHECK_VALUE              (value)
#define     G_TYPE_CHECK_VALUE_TYPE         (value, g_type)
#define     G_TYPE_FLAG_RESERVED_ID_BIT
void        g_type_init                     (void);
enum        GTypeDebugFlags;
void        g_type_init_with_debug_flags    (GTypeDebugFlags debug_flags);
const gchar* g_type_name                    (GType type);
GQuark      g_type_qname                    (GType type);
GType       g_type_from_name                (const gchar *name);
GType       g_type_parent                   (GType type);
guint       g_type_depth                    (GType type);
GType       g_type_next_base                (GType leaf_type,
                                             GType root_type);
gboolean    g_type_is_a                     (GType type,
                                             GType is_a_type);
gpointer    g_type_class_ref                (GType type);
gpointer    g_type_class_peek               (GType type);
gpointer    g_type_class_peek_static        (GType type);
void        g_type_class_unref              (gpointer g_class);
gpointer    g_type_class_peek_parent        (gpointer g_class);
void        g_type_class_add_private        (gpointer g_class,
                                             gsize private_size);
gpointer    g_type_interface_peek           (gpointer instance_class,
                                             GType iface_type);
gpointer    g_type_interface_peek_parent    (gpointer g_iface);
gpointer    g_type_default_interface_ref    (GType g_type);
gpointer    g_type_default_interface_peek   (GType g_type);
void        g_type_default_interface_unref  (gpointer g_iface);
GType*      g_type_children                 (GType type,
                                             guint *n_children);
GType*      g_type_interfaces               (GType type,
                                             guint *n_interfaces);
GType*      g_type_interface_prerequisites  (GType interface_type,
                                             guint *n_prerequisites);
void        g_type_set_qdata                (GType type,
                                             GQuark quark,
                                             gpointer data);
gpointer    g_type_get_qdata                (GType type,
                                             GQuark quark);
void        g_type_query                    (GType type,
                                             GTypeQuery *query);
            GTypeQuery;
void        (*GBaseInitFunc)                (gpointer g_class);
void        (*GBaseFinalizeFunc)            (gpointer g_class);
void        (*GClassInitFunc)               (gpointer g_class,
                                             gpointer class_data);
void        (*GClassFinalizeFunc)           (gpointer g_class,
                                             gpointer class_data);
void        (*GInstanceInitFunc)            (GTypeInstance *instance,
                                             gpointer g_class);
void        (*GInterfaceInitFunc)           (gpointer g_iface,
                                             gpointer iface_data);
void        (*GInterfaceFinalizeFunc)       (gpointer g_iface,
                                             gpointer iface_data);
gboolean    (*GTypeClassCacheFunc)          (gpointer cache_data,
                                             GTypeClass *g_class);
enum        GTypeFlags;
enum        GTypeFundamentalFlags;
GType       g_type_register_static          (GType parent_type,
                                             const gchar *type_name,
                                             const GTypeInfo *info,
                                             GTypeFlags flags);
GType       g_type_register_dynamic         (GType parent_type,
                                             const gchar *type_name,
                                             GTypePlugin *plugin,
                                             GTypeFlags flags);
GType       g_type_register_fundamental     (GType type_id,
                                             const gchar *type_name,
                                             const GTypeInfo *info,
                                             const GTypeFundamentalInfo *finfo,
                                             GTypeFlags flags);
void        g_type_add_interface_static     (GType instance_type,
                                             GType interface_type,
                                             const GInterfaceInfo *info);
void        g_type_add_interface_dynamic    (GType instance_type,
                                             GType interface_type,
                                             GTypePlugin *plugin);
void        g_type_interface_add_prerequisite
                                            (GType interface_type,
                                             GType prerequisite_type);
GTypePlugin* g_type_get_plugin              (GType type);
GTypePlugin* g_type_interface_get_plugin    (GType instance_type,
                                             GType interface_type);
GType       g_type_fundamental_next         (void);
GType       g_type_fundamental              (GType type_id);
GTypeInstance* g_type_create_instance       (GType type);
void        g_type_free_instance            (GTypeInstance *instance);
void        g_type_add_class_cache_func     (gpointer cache_data,
                                             GTypeClassCacheFunc cache_func);
void        g_type_remove_class_cache_func  (gpointer cache_data,
                                             GTypeClassCacheFunc cache_func);
void        g_type_class_unref_uncached     (gpointer g_class);
void        g_type_add_interface_check      (gpointer check_data,
                                             GTypeInterfaceCheckFunc check_func);
void        g_type_remove_interface_check   (gpointer check_data,
                                             GTypeInterfaceCheckFunc check_func);
void        (*GTypeInterfaceCheckFunc)      (gpointer check_data,
                                             gpointer g_iface);
GTypeValueTable* g_type_value_table_peek    (GType type);
#define     G_DEFINE_TYPE                   (TN, t_n, T_P)
#define     G_DEFINE_TYPE_WITH_CODE         (TN, t_n, T_P, _C_)
#define     G_DEFINE_ABSTRACT_TYPE          (TN, t_n, T_P)
#define     G_DEFINE_ABSTRACT_TYPE_WITH_CODE(TN, t_n, T_P, _C_)
#define     G_IMPLEMENT_INTERFACE           (TYPE_IFACE, iface_init)
#define     G_DEFINE_TYPE_EXTENDED          (TypeName, type_name, TYPE_PARENT, flags, CODE)


#define     G_TYPE_INVALID
#define     G_TYPE_NONE
#define     G_TYPE_INTERFACE
#define     G_TYPE_CHAR
#define     G_TYPE_UCHAR
#define     G_TYPE_BOOLEAN
#define     G_TYPE_INT
#define     G_TYPE_UINT
#define     G_TYPE_LONG
#define     G_TYPE_ULONG
#define     G_TYPE_INT64
#define     G_TYPE_UINT64
#define     G_TYPE_ENUM
#define     G_TYPE_FLAGS
#define     G_TYPE_FLOAT
#define     G_TYPE_DOUBLE
#define     G_TYPE_STRING
#define     G_TYPE_POINTER
#define     G_TYPE_BOXED
#define     G_TYPE_PARAM
#define     G_TYPE_OBJECT

#define     G_TYPE_RESERVED_GLIB_FIRST
#define     G_TYPE_RESERVED_GLIB_LAST
#define     G_TYPE_RESERVED_BSE_FIRST
#define     G_TYPE_RESERVED_BSE_LAST
#define     G_TYPE_RESERVED_USER_FIRST

Description

The GType API is the foundation of the GObject system. It provides the facilities for registering and managing all fundamental data types, user-defined object and interface types. Before using any GType or GObject functions, g_type_init() must be called to initialize the type system.

For type creation and registration purposes, all types fall into one of two categories: static or dynamic. Static types are never loaded or unloaded at run-time as dynamic types may be. Static types are created with g_type_register_static() that gets type specific information passed in via a GTypeInfo structure. Dynamic types are created with g_type_register_dynamic() which takes a GTypePlugin structure instead. The remaining type information (the GTypeInfo structure) is retrieved during runtime through GTypePlugin and the g_type_plugin_*() API. These registration functions are usually called only once from a function whose only purpose is to return the type identifier for a specific class. Once the type (or class or interface) is registered, it may be instantiated, inherited, or implemented depending on exactly what sort of type it is. There is also a third registration function for registering fundamental types called g_type_register_fundamental() which requires both a GTypeInfo structure and a GTypeFundamentalInfo structure but it is seldom used since most fundamental types are predefined rather than user-defined.

A final word about type names. Such an identifier needs to be at least three characters long. There is no upper length limit. The first character needs to be a letter (a-z or A-Z) or an underscore '_'. Subsequent characters can be letters, numbers or any of '-_+'.

Details

GType

A numerical value which represents the unique identifier of a registered type.

G_TYPE_FUNDAMENTAL()

#define G_TYPE_FUNDAMENTAL(type)	(g_type_fundamental (type))

Returns the fundamental type which is the ancestor of type. Fundamental types are types that serve as fundaments for the derived types, thus they are the roots of distinct inheritance hierarchies.

type : A GType value.

G_TYPE_FUNDAMENTAL_MAX

#define	G_TYPE_FUNDAMENTAL_MAX		(255 << G_TYPE_FUNDAMENTAL_SHIFT)

An integer constant that represents the number of identifiers reserved for types that are assigned at compile-time.

G_TYPE_MAKE_FUNDAMENTAL()

#define	G_TYPE_MAKE_FUNDAMENTAL(x)	((GType) ((x) << G_TYPE_FUNDAMENTAL_SHIFT))

Returns the type ID for the fundamental type number x. Use g_type_fundamental_next() instead of this macro to create new fundamental types.

x : the fundamental type number.

G_TYPE_IS_ABSTRACT()

#define G_TYPE_IS_ABSTRACT(type)                (g_type_test_flags ((type), G_TYPE_FLAG_ABSTRACT))

Returns TRUE if type is an abstract type. An abstract type can not be instantiated and is normally used as an abstract base class for derived classes.

type : A GType value.

G_TYPE_IS_DERIVED()

#define G_TYPE_IS_DERIVED(type)                 ((type) > G_TYPE_FUNDAMENTAL_MAX)

Returns TRUE if type is derived (or in object-oriented terminology: inherited) from another type (this holds true for all non-fundamental types).

type : A GType value.

G_TYPE_IS_FUNDAMENTAL()

#define G_TYPE_IS_FUNDAMENTAL(type)             ((type) <= G_TYPE_FUNDAMENTAL_MAX)

Returns TRUE if type is a fundamental type.

type : A GType value.

G_TYPE_IS_VALUE_TYPE()

#define G_TYPE_IS_VALUE_TYPE(type)              (g_type_check_is_value_type (type))

Returns TRUE if type is a value type which can be used for g_value_init().

type : A GType value.

G_TYPE_HAS_VALUE_TABLE()

#define G_TYPE_HAS_VALUE_TABLE(type)            (g_type_value_table_peek (type) != NULL)

Returns TRUE if type has a GTypeValueTable.

type : A GType value.

G_TYPE_IS_CLASSED()

#define G_TYPE_IS_CLASSED(type)                 (g_type_test_flags ((type), G_TYPE_FLAG_CLASSED))

Returns TRUE if type is a classed type.

type : A GType value.

G_TYPE_IS_INSTANTIATABLE()

#define G_TYPE_IS_INSTANTIATABLE(type)          (g_type_test_flags ((type), G_TYPE_FLAG_INSTANTIATABLE))

Returns TRUE if type can be instantiated. Instantiation is the process of creating an instance (object) of this type.

type : A GType value.

G_TYPE_IS_DERIVABLE()

#define G_TYPE_IS_DERIVABLE(type)               (g_type_test_flags ((type), G_TYPE_FLAG_DERIVABLE))

Returns TRUE if type is a derivable type. A derivable type can be used as the base class of a flat (single-level) class hierarchy.

type : A GType value.

G_TYPE_IS_DEEP_DERIVABLE()

#define G_TYPE_IS_DEEP_DERIVABLE(type)          (g_type_test_flags ((type), G_TYPE_FLAG_DEEP_DERIVABLE))

Returns TRUE if type is a deep derivable type. A deep derivable type can be used as the base class of a deep (multi-level) class hierarchy.

type : A GType value.

G_TYPE_IS_INTERFACE()

#define G_TYPE_IS_INTERFACE(type)               (G_TYPE_FUNDAMENTAL (type) == G_TYPE_INTERFACE)

Returns TRUE if type is an interface type. Interface types are types that provide pure APIs, the implementation of which is provided by another type (which is then said to conform to the interface). GLib interfaces are somewhat analogous to Java interfaces and C++ classes containing only pure virtual functions, with the difference that GType interfaces are not derivable (but see g_type_interface_add_prerequisite() for an alternative).

type : A GType value.

GTypeInterface

typedef struct {
} GTypeInterface;

An opaque structure used as the base of all interface types.

GTypeInstance

typedef struct {
} GTypeInstance;

An opaque structure used as the base of all type instances.

GTypeClass

typedef struct {
} GTypeClass;

An opaque structure used as the base of all classes.

GTypeInfo

typedef struct {
  /* interface types, classed types, instantiated types */
  guint16                class_size;
  
  GBaseInitFunc          base_init;
  GBaseFinalizeFunc      base_finalize;
  
  /* interface types, classed types, instantiated types */
  GClassInitFunc         class_init;
  GClassFinalizeFunc     class_finalize;
  gconstpointer          class_data;
  
  /* instantiated types */
  guint16                instance_size;
  guint16                n_preallocs;
  GInstanceInitFunc      instance_init;
  
  /* value handling */
  const GTypeValueTable	*value_table;
} GTypeInfo;

This structure is used to provide the type system with the information required to initialize and destruct (finalize) a type's class and instances thereof. The initialized structure is passed to the g_type_register_static() function (or is copied into the provided GTypeInfo structure in the g_type_plugin_complete_type_info()). The type system will perform a deep copy of this structure, so it's memory does not need to be persistent across invocation of g_type_register_static().

guint16 `class_size`;	Size of the class structure (required for interface, classed and instantiatable types).
GBaseInitFunc `base_init`;	Location of the base initialization function (optional).
GBaseFinalizeFunc `base_finalize`;	Location of the base finalization function (optional).
GClassInitFunc `class_init`;	Location of the class initialization function for classed and types. Location of the default vtable inititalization function for interface types. (optional) This function is used both to fill in virtual functions in the class or default vtable, and to do type-specific setup such as registering signals and object properties.
GClassFinalizeFunc `class_finalize`;	Location of the class finalization function for classed and types. Location fo the default vtable finalization function for interface types. (optional)
gconstpointer `class_data`;	User-supplied data passed to the class init/finalize functions.
guint16 `instance_size`;	Size of the instance (object) structure (required for instantiatable types only).
guint16 `n_preallocs`;	Number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching).
GInstanceInitFunc `instance_init`;	Location of the instance initialization function (optional, for instantiatable types only).
const GTypeValueTable *`value_table`;	A GTypeValueTable function table for generic handling of GValues of this type (usually only useful for fundamental types).

GTypeFundamentalInfo

typedef struct {
  GTypeFundamentalFlags  type_flags;
} GTypeFundamentalInfo;

A structure that provides information to the type system which is used specifically for managing fundamental types.

GInterfaceInfo

typedef struct {
  GInterfaceInitFunc     interface_init;
  GInterfaceFinalizeFunc interface_finalize;
  gpointer               interface_data;
} GInterfaceInfo;

A structure that provides information to the type system which is used specifically for managing interface types.

GInterfaceInitFunc `interface_init`;	Location of the function that initializes the interface.
GInterfaceFinalizeFunc `interface_finalize`;	Location of the function that finalizes the interface.
gpointer `interface_data`;	Location of user data passed to the `interface_init` and `interface_finalize` functions (optional).

GTypeValueTable

typedef struct {
  void     (*value_init)         (GValue       *value);
  void     (*value_free)         (GValue       *value);
  void     (*value_copy)         (const GValue *src_value,
				  GValue       *dest_value);
  /* varargs functionality (optional) */
  gpointer (*value_peek_pointer) (const GValue *value);
  gchar	    *collect_format;
  gchar*   (*collect_value)      (GValue       *value,
				  guint         n_collect_values,
				  GTypeCValue  *collect_values,
				  guint		collect_flags);
  gchar	    *lcopy_format;
  gchar*   (*lcopy_value)        (const GValue *value,
				  guint         n_collect_values,
				  GTypeCValue  *collect_values,
				  guint		collect_flags);
} GTypeValueTable;

The GTypeValueTable provides the functions required by the GValue implementation, to serve as a container for values of a type.

value_init ()

Default initialize values contents by poking values directly into the value->data array. The data array of the GValue passed into this function was zero-filled with memset(), so no care has to be taken to free any old contents. E.g. for the implementation of a string value that may never be NULL, the implementation might look like:

{
  value->data[0].v_pointer = g_strdup ("");
}

value_free ()

Free any old contents that might be left in the data array of the passed in value. No resources may remain allocated through the GValue contents after this function returns. E.g. for our above string type:

{
  /* only free strings without a specific flag for static storage */
  if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS))
    g_free (value->data[0].v_pointer);
}

value_copy ()

dest_value is a GValue with zero-filled data section and src_value is a properly setup GValue of same or derived type. The purpose of this function is to copy the contents of src_value into dest_value in a way, that even after src_value has been freed, the contents of dest_value remain valid. String type example:

{
  dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer);
}

value_peek_pointer ()

If the value contents fit into a pointer, such as objects or strings, return this pointer, so the caller can peek at the current contents. To extend on our above string example:

{
  return value->data[0].v_pointer;
}

gchar *collect_format;

A string format describing how to collect the contents of this value, bit-by-bit. Each character in the format represents an argument to be collected, the characters themselves indicate the type of the argument. Currently supported arguments are:

	'i' - Integers. passed as collect_values[].v_int.
	'l' - Longs. passed as collect_values[].v_long.
	'd' - Doubles. passed as collect_values[].v_double.
	'p' - Pointers. passed as collect_values[].v_pointer.

It should be noted, that for variable argument list construction, ANSI C promotes every type smaller than an integer to an int, and floats to doubles. So for collection of short int or char, 'i' needs to be used, and for collection of floats 'd'.

collect_value ()

The collect_value() function is responsible for converting the values collected from a variable argument list into contents suitable for storage in a GValue. This function should setup value similar to value_init(), e.g. for a string value that does not allow NULL pointers, it needs to either spew an error, or do an implicit conversion by storing an empty string. The value passed in to this function has a zero-filled data array, so just like for value_init() it is guaranteed to not contain any old contents that might need freeing. n_collect_values is exactly the string length of collect_format, and collect_values is an array of unions GTypeCValue with length n_collect_values, containing the collected values according to collect_format. collect_flags is an argument provided as a hint by the caller, which may contain the flag G_VALUE_NOCOPY_CONTENTS indicating, that the collected value contents may be considered "static" for the duration of the value lifetime. Thus an extra copy of the contents stored in collect_values is not required for assignment to value. For our above string example, we continue with:

{
  if (!collect_values[0].v_pointer)
    value->data[0].v_pointer = g_strdup ("");
  else if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
    {
      value->data[0].v_pointer = collect_values[0].v_pointer;
      /* keep a flag for the value_free() implementation to not free this string */
      value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS;
    }
  else
    value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer);

  return NULL;
}

It should be noted, that it is generally a bad idea to follow the G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to reentrancy requirements and reference count assertions performed by the GSignal code, reference counts should always be incremented for reference counted contents stored in the value->data array. To deviate from our string example for a moment, and taking a look at an exemplary implementation for collect_value() of GObject:

{
  if (collect_values[0].v_pointer)
    {
      GObject *object = G_OBJECT (collect_values[0].v_pointer);

      /* never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types */
      value->data[0].v_pointer = g_object_ref (object);
      return NULL;
    }
  else
    return g_strdup_printf ("Object passed as invalid NULL pointer");
}

The reference count for valid objects is always incremented, regardless of collect_flags. For invalid objects, the example returns a newly allocated string without altering value. Upon success, collect_value() needs to return NULL, if however a malicious condition occurred, collect_value() may spew an error by returning a newly allocated non-NULL string, giving a suitable description of the error condition. The calling code makes no assumptions about the value contents being valid upon error returns, value is simply thrown away without further freeing. As such, it is a good idea to not allocate GValue contents, prior to returning an error, however, collect_values() is not obliged to return a correctly setup value for error returns, simply because any non-NULL return is considered a fatal condition so further program behaviour is undefined.

gchar *lcopy_format; Format description of the arguments to collect for lcopy_value, analogous to collect_format. Usually, lcopy_format string consists only of 'p's to provide lcopy_value() with pointers to storage locations.

lcopy_value ()

This function is responsible for storing the value contents into arguments passed through a variable argument list which got collected into collect_values according to lcopy_format. n_collect_values equals the string length of lcopy_format, and collect_flags may contain G_VALUE_NOCOPY_CONTENTS. In contrast to collect_value(), lcopy_value() is obliged to always properly support G_VALUE_NOCOPY_CONTENTS. Similar to collect_value() the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example:

{
  gchar **string_p = collect_values[0].v_pointer;

  if (!string_p)
    return g_strdup_printf ("string location passed as NULL");

  if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
    *string_p = value->data[0].v_pointer;
  else
    *string_p = g_strdup (value->data[0].v_pointer);

}

And an exemplary version of lcopy_value() for reference-counted types:

{
  GObject **object_p = collect_values[0].v_pointer;

  if (!object_p)
    return g_strdup_printf ("object location passed as NULL");
  if (!value->data[0].v_pointer)
    *object_p = NULL;
  else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) /* always honour */
    *object_p = value->data[0].v_pointer;
  else
    *object_p = g_object_ref (value->data[0].v_pointer);
  return NULL;
}