Package gobject

Type Information
GObject
Enumeration and Flag Types
Boxed Types
Generic Values
Parameters and Values
GParamSpec
Signals
Closures
GBinding

Type Information

The GLib Runtime type identification and management system.

The GType API is the foundation of the GObject system. It provides the facilities for registering and managing all fundamental data types, user-defined objects and interface types.

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 the function g_type_register_static() that gets type specific information passed in via a GTypeInfo structure. Dynamic types are created with the function g_type_register_dynamic() which takes a GTypePlugin structure instead. The remaining type information (the GTypeInfo structure) is retrieved during runtime through the GTypePlugin structure 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.

Type instance and class structures are limited to a total of 64 KiB, including all parent types. Similarly, type instances' private data (as created by the function g_type_class_add_private()) are limited to a total of 64 KiB. If a type instance needs a large static buffer, allocate it separately (typically by using a GArray or GPtrArray structure) and put a pointer to the buffer in the structure.

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 '-_+'.

GObject

The base object type.

Enumeration and Flag Types

The GLib type system provides fundamental types for enumeration and flags types. Flags types are like enumerations, but allow their values to be combined by bitwise OR. A registered enumeration or flags type associates a name and a nickname with each allowed value. When an enumeration or flags type is registered with the GLib type system, it can be used as value type for object properties, using the functions g-param-spec-enum or g-param-spec-flags.

Boxed Types

A mechanism to wrap opaque C structures registered by the type system

GBoxed is a generic wrapper mechanism for arbitrary C structures. The only thing the type system needs to know about the structures is how to copy and free them, beyond that they are treated as opaque chunks of memory.

Boxed types are useful for simple value-holder structures like rectangles or points. They can also be used for wrapping structures defined in non-GObject based libraries. They allow arbitrary structures to be handled in a uniform way, allowing uniform copying (or referencing) and freeing (or unreferencing) of them, and uniform representation of the type of the contained structure. In turn, this allows any type which can be boxed to be set as the data in a GValue, which allows for polymorphic handling of a much wider range of data types, and hence usage of such types as GObject property values.

GBoxed is designed so that reference counted types can be boxed. Use the type’s ‘ref’ function as the GBoxedCopyFunc, and its ‘unref’ function as the GBoxedFreeFunc. For example, for GBytes, the GBoxedCopyFunc is g_bytes_ref(), and the GBoxedFreeFunc is g_bytes_unref().

Generic Values

A polymorphic type that can hold values of any other type.

Parameters and Values

Standard Parameter and Value Types

GValue provides an abstract container structure which can be copied, transformed and compared while holding a value of any (derived) type, which is registered as a GType with a GTypeValueTable in its GTypeInfo structure. Parameter specifications for most value types can be created as GParamSpec derived instances, to implement e.g. GObject properties which operate on GValue containers.

Parameter names need to start with a letter (a-z or A-Z). Subsequent characters can be letters, numbers or a '-'. All other characters are replaced by a '-' during construction.

GParamSpec

Metadata for parameter specifications.

Signals

A means for customization of object behaviour and a general purpose notification mechanism.

The basic concept of the signal system is that of the emission of a signal. Signals are introduced per-type and are identified through strings. Signals introduced for a parent type are available in derived types as well, so basically they are a per-type facility that is inherited.

A signal emission mainly involves invocation of a certain set of callbacks in precisely defined manner. There are two main categories of such callbacks, per-object ones and user provided ones. (Although signals can deal with any kind of instantiatable type, I am referring to those types as "object types" in the following, simply because that is the context most users will encounter signals in.) The per-object callbacks are most often referred to as "object method handler" or "default (signal) handler", while user provided callbacks are usually just called "signal handler".

The object method handler is provided at signal creation time (this most frequently happens at the end of an object class' creation), while user provided handlers are frequently connected and disconnected to/from a certain signal on certain object instances.

A signal emission consists of five stages, unless prematurely stopped:

1. Invocation of the object method handler for :run-first signals.
2. Invocation of normal user-provided signal handlers (where the after flag is not set).
3. Invocation of the object method handler for :run-last signals.
4. Invocation of user provided signal handlers (where the after flag is set).
5. Invocation of the object method handler for :run-cleanup signals.

The user-provided signal handlers are called in the order they were connected in.

All handlers may prematurely stop a signal emission, and any number of handlers may be connected, disconnected, blocked or unblocked during a signal emission.

There are certain criteria for skipping user handlers in stages 2 and 4 of a signal emission.

First, user handlers may be blocked. Blocked handlers are omitted during callback invocation, to return from the blocked state, a handler has to get unblocked exactly the same amount of times it has been blocked before.

Second, upon emission of a :detailed signal, an additional detail argument passed in to the functin g-signal-emit has to match the detail argument of the signal handler currently subject to invocation. Specification of no detail argument for signal handlers (omission of the detail part of the signal specification upon connection) serves as a wildcard and matches any detail argument passed in to emission.

While the detail argument is typically used to pass an object property name (as with "notify"), no specific format is mandated for the detail string, other than that it must be non-empty.

Memory management of signal handlers

If you are connecting handlers to signals and using a g-object instance as your signal handler user data, you should remember to pair calls to the function g-signal-connect with calls to the function g-signal-handler-disconnect. While signal handlers are automatically disconnected when the object emitting the signal is finalised, they are not automatically disconnected when the signal handler user data is destroyed. If this user data is a g-object instance, using it from a signal handler after it has been finalised is an error.

There are two strategies for managing such user data. The first is to disconnect the signal handler (using the function g-signal-handler-disconnect) when the user data (object) is finalised; this has to be implemented manually. For non-threaded programs, the function g_signal_connect_object() can be used to implement this automatically. Currently, however, it is unsafe to use in threaded programs.

The second is to hold a strong reference on the user data until after the signal is disconnected for other reasons. This can be implemented automatically using the function g_signal_connect_data().

The first approach is recommended, as the second approach can result in effective memory leaks of the user data if the signal handler is never disconnected for some reason.

Closures

Functions as first-class objects

A GClosure represents a callback supplied by the programmer. It will generally comprise a function of some kind and a marshaller used to call it. It is the reponsibility of the marshaller to convert the arguments for the invocation from GValues into a suitable form, perform the callback on the converted arguments, and transform the return value back into a GValue.

In the case of C programs, a closure usually just holds a pointer to a function and maybe a data argument, and the marshaller converts between GValue and native C types. The GObject library provides the GCClosure type for this purpose. Bindings for other languages need marshallers which convert between GValues and suitable representations in the runtime of the language in order to use functions written in that languages as callbacks.

Within GObject, closures play an important role in the implementation of signals. When a signal is registered, the c_marshaller argument to g_signal_new() specifies the default C marshaller for any closure which is connected to this signal. GObject provides a number of C marshallers for this purpose, see the g_cclosure_marshal_*() functions. Additional C marshallers can be generated with the glib-genmarshal utility. Closures can be explicitly connected to signals with g_signal_connect_closure(), but it usually more convenient to let GObject create a closure automatically by using one of the g_signal_connect_*() functions which take a callback function/user data pair.

Using closures has a number of important advantages over a simple callback function/data pointer combination:

• Closures allow the callee to get the types of the callback parameters, which means that language bindings don't have to write individual glue for each callback type.
• The reference counting of GClosure makes it easy to handle reentrancy right; if a callback is removed while it is being invoked, the closure and its parameters won't be freed until the invocation finishes.
• g_closure_invalidate() and invalidation notifiers allow callbacks to be automatically removed when the objects they point to go away.

GBinding

Bind two object properties.