GObject tutorial next version

[Ryan McDougall <NQG24419 nifty com>]

This covers everything except signals, which is the last thing to do.

Warning currently its in plain text format since I haven't gotten around
to fancifying it yet, however it WILL be prettied up.

I'd appreciate feedback on technical, spelling, grammar, or style
points.

Cheers,
Ryan

GObject Tutorial
Copyright Ryan McDougall (2004)

Purpose
-----
This document is used for two purposes: one is as a tutorial on learning Glib's GObject Type System, and the other is a step-by-step how-to for using the system. The tutorial proceeds from the point of view of designing an Object-Oriented type system in C, where GObject is the presumed solution. It is thought that this manner of presenting the material will better justify the form that the library currently takes, and help explain the steps required use it. The how-to is presented after the tutorial in a step-by-step, matter-of-fact, form with no explanations, so that it will be useful to the merely pragmatic programmer.

Audience
-----
The tutorial is meant for those who are familiar with OO concepts, but are just beginning to learn GObject or GTK+. I will assume previous knowledge of an OO'ed language, and a basic command of C.

Motivation
-----
While writing an OO system in a language that doesn't support it may sound like a foolish exercise in masochism to some, there are indeed some good reasons why one would want to do such a thing. While I will not try to justify the authors' decision, and will assume that the reader has some good reason for using Glib, I will point out some important features of the system: 
- C is the most portable programming language
- system is fully dynamic, so types can be added at run-time
- system is more extensible than a standard language, so new features can be added quickly

In OO languages object oriented features and abilities are a matter of syntax. However since C doesn't support OO natively, the GObject system has to graft on object orientation manually. Often this requires some tedious, or occasionally mystifying things in order to accomplish this goal. It is my intention to enumerate all the necessary steps and incantations necessary to make this process work; and hopefully even elaborate on what it means to your program.

1. Creating a single Object with no Inheritance

Design
-----
In OO, an object consists of two types of members bound under one object reference: data fields and method functions. One way to accomplish this in C is with C structs, where data fields are regular public members and methods are implemented as function pointers. This implementation however has several serious flaws: awkward syntax, type-safety, and lack of encapsulation to name a few. However there is more practical problem -- it is a serious waste of space. Every instance object needs a 4-byte pointer for each of its methods; all of which will be identical class wide, and thus totally redundant. That is to say if we have a class with only four methods, and a program with 1000 instantiation objects of that class, we are wasting almost 16KB. Clearly we'd be better off memory-wise if we only kept one copy of those pointers in a table that could be accessed by any object in its class.

Such as table is called a virtual method table (vtable), and one copy is kept in memory by the GObject system for each class. When you want to call a virtual method, you must ask the system to find the object's vtable; which as we have said above is just a struct with function pointers. With this you can now dereference the pointer and thus call the method. 

<definition>
We will call these two types "instance struct" and "class struct", and instantiations of those structs "instance objects" and "class objects" respectively. The combination of the two structs as a conceptual unit will be called a "class" and an instantiation of that class will be called an "object".
</definition>

The reason why functions given by this process are called "virtual" is because it dynamically looks up the appropriate function pointer at run-time and thus allows inherited classes to override a class method (by simply assigning a new function pointer to the corresponding entry in the vtable). This allows derived objects to behave correctly when cast to a base class, and corresponds to what we know of virtual methods in C++. 

<convention>
Although this saves space and allows virtual methods, it also means that methods can no longer be tied syntactically to an object via the dot operator.Therefore we will use the convention that class methods will be called on objects as follows:

NAMESPACE_TYPE_METHOD (OBJECT*, PARAMETERS)
</convention>

Non-virtual methods will be implemented inside a regular C function, and virtual functions will be implemented by calling the appropriate method from the vtable inside a regular C function. Private methods will be implemented within the source file, but not be exported via the header file. 

<notice>
While OO normally uses information hiding as part of encapsulation, there is no easy way to hide private members in C. One method is to put your private members into a separate struct that is defined in the source file only, then place a pointer to the private class in your public object struct. However, in a open-source world this is small protection against a user determined to do the wrong thing. Most developers simply label with a comment those members they wish to protect as private, and hope the user respects the distinction.
</notice>

At this point we have two distinct structs, and no obvious way to find to get the proper vtable given an instantiated object. As we implied above, it is the system's responsibility to do so, and it is able to handle this only by requiring us to register the types we create. The system also requires us to register both (instance and class) structs' initialization and finalization functions (and some other important information), which will allow the system to properly instantiate our objects. The system keeps track of our objects by enumerating all types registered with it, and requiring that all instance objects start with a pointer to its own class vtable, and each vtable start with the number that corresponds to its enumerated type.

<notice>
The type system requires that all types' instance and class structs start with with a special struct. In the case of instance structs, this struct is basically just a pointer to the type's class object. Since C guarantees that the first member declared in a struct is also the first found in memory, one can get the class object quickly by simply casting the instance object. Since the type system also requires that we declare the parent struct as the first member when we use inheritance, this same feature means that we need only declare this special struct once in the parent class, and we can always find the vtable of any instance object via a cast.
</notice>

Lastly we need some functions to define how our objects' lifetimes are managed: a function to call when we wish to create a class object, a function to call when we wish to create an instance object, and a function to call when we are finished with a class object. We do not include a function for finalizing instance objects because instance memory management is generally a complicated problem, and we wish to leave this up to higher levels of code to handle.

Code (header)
-----

<step>
Create "C-style" objects using the struct keyword to implement our instance and class objects.
</step>

<notice>
We prepend an underscore to the name of our struct, then add a forward typedef which gives our struct a proper name. This is due to the grammar of C, which won't let you declare SomeObject pointers inside SomeObject (which is handy for such things as linked lists). We have also created an artificial namespace called "Some", as described by our convention above.
</notice>

/* Our "Instance struct" defines all the data fields that make our object unique. */
typedef struct _SomeObject SomeObject;
struct _SomeObject
{
	GTypeInstance	gtype;

	gint 		m_a;
	gchar*		m_b;
	gfloat		m_c;
};

/* Our "Class struct" defines all the method functions that our objects will share. */
typedef struct _SomeObjectClass SomeObjectClass;
struct _SomeObjectClass
{
	GTypeClass	gtypeclass;

	void		(*method1)	(SomeObject *self, gint);
	void		(*method2)	(SomeObject *self, gchar*);
};

<step>
Declare the function that will both register our type in the system upon first use, then thereafter will return the unique number that the system uses to track the types we declare. We will call this function get_type and have it return a GType, which is the integral type the system declares to identify registered types. Since this function is specific to our type SomeObject by design and definition, we prepend "some_object_".
</step>

/* This method returns the GType associated with our new object type. */
GType	some_object_get_type (void);

<step>
Declare the functions which manage our objects' lifetimes; that is they set up an object on instantiation, and tear it down on finalization.
</step>

/* These are the Class/Instance Initialize/Finalize functions. Their signature is determined in gtype.h. */
void	some_object_class_init		(gpointer g_class, gpointer class_data);
void	some_object_class_final		(gpointer g_class, gpointer class_data);
void	some_object_instance_init	(GTypeInstance *instance, gpointer g_class);

<step>
Declare our class methods using the C function convention we defined above.
</step>

/* All these functions are methods of SomeObject. */
void	some_object_method1 (SomeObject *self, gint);	/* virtual */
void	some_object_method2 (SomeObject *self, gchar*);	/* virtual */
void	some_object_method3 (SomeObject *self, gfloat);	/* non-virtual */

<step>
Create some boiler-plate code which will make our code comply to existing standards and generally make our lives easier.
</step>

/* Handy macros */
#define SOME_OBJECT_TYPE		(some_object_get_type ())
#define SOME_OBJECT(obj)		(G_TYPE_CHECK_INSTANCE_CAST ((obj), SOME_OBJECT_TYPE, SomeObject))
#define SOME_OBJECT_CLASS(c)		(G_TYPE_CHECK_CLASS_CAST ((c), SOME_OBJECT_TYPE, SomeObjectClass))
#define SOME_IS_OBJECT(obj)		(G_TYPE_CHECK_TYPE ((obj), SOME_OBJECT_TYPE))
#define SOME_IS_OBJECT_CLASS(c)		(G_TYPE_CHECK_CLASS_TYPE ((c), SOME_OBJECT_TYPE))
#define SOME_OBJECT_GET_CLASS(obj)	(G_TYPE_INSTANCE_GET_CLASS ((obj), SOME_OBJECT_TYPE, SomeObjectClass))

Code (source)
-----
Now we can move on to implementing in the source file what we've just declared. 

<notice>
Since our virtual methods are just function pointers, we have to create some normal C functions that actually reside in addressable memory (declared as ending in "_impl" and *not* exported in the header), which actually implement the code we want to point to.
</notice>

<notice>
All functions preceded by "some_object_" are specific to SomeObject by definition; usually because we explicitly cast various pointers to SomeObject, or make use of some other class specific feature.
</notice>

<step>
Implement the code corresponding to our virtual methods.
</step>

/* Implementation of virtual functions. */
void	some_object_method1_impl (SomeObject *self, gint a)
{
	self->m_a = a;
	g_print ("Method1: %i\n", self->m_a);
}

void	some_object_method2_impl (SomeObject *self, gchar* b)
{
	self->m_b = b;
	g_print ("Method2: %s\n", self->m_b);
}

<step>
Implement the code for all public methods. In the case of virtual methods, we must use the macro "GET_CLASS" to ask the type system to return the class object so we can access the vtable where our virtual methods reside. If the method is non-virtual, we just write the code.
</step>

/* Public methods. */
void	some_object_method1 (SomeObject *self, gint a)
{
	SOME_OBJECT_GET_CLASS (self)->method1 (self, a);
}

void	some_object_method2 (SomeObject *self, gchar* b)
{
	SOME_OBJECT_GET_CLASS (self)->method2 (self, b);
}

void	some_object_method3 (SomeObject *self, gfloat c)
{
	self->m_c = c;
	g_print ("Method3: %f\n", self->m_c);
}

<step>
Implement the code for initialization/finalization. We are given generic pointers by the system (that we trust points to a proper object), so we must cast them to the appropriate type before we can do anything.
</step>

/* This is called when the class object is created. */
void	some_object_class_init		(gpointer g_class, gpointer class_data)
{
	SomeObjectClass	*this_class	= SOME_OBJECT_CLASS (g_class);
	
	/* fill in the class struct members (in this case just a vtable) */
	this_class->method1 = &some_object_method1_impl;
	this_class->method2 = &some_object_method2_impl;
}

/* This is called when the class object is no longer used. */
void	some_object_class_final		(gpointer g_class, gpointer class_data)
{
	/* No class finalization needed since the class object holds no 
	pointers or references to any dynamic resources which would need 
	to be released when the class object is no longer in use. */
}

/* This is called when a instance object is created. The instance's class is passed as g_class. */
void	some_object_instance_init	(GTypeInstance *instance, gpointer g_class)
{
	SomeObject *this_object = SOME_OBJECT (instance);

	/* fill in the instance struct members */
	this_object->m_a = 42;
	this_object->m_b = 3.14;
	this_object->m_c = NULL;
}

<step>
Implement a function for informing the caller of SomeObject's GType. The first time this function is run, it determines the GType by fully registering SomeObject with the system. Thereafter the GType is stored in a static variable, and returns without any processing. While its possible to register the type in a separate function, this implementation ensures that the type is always registered before its used, which is usually when the first object is instantiated.
</step>

/* Since there is no base class to derive from, base_init/finalize are NULL */
GType	some_object_get_type (void)
{
	static GType type = 0;

	if (type == 0) 
	{
		/* This is the structure that the system uses to fully describe
		how a type should be created, initialized and finalized. */

		static const GTypeInfo type_info = 
		{
			sizeof (SomeObjectClass),
			NULL,				/* base_init */
			NULL,				/* base_finalize */
			some_object_class_init,		/* class_init */
			some_object_class_final,	/* class_finalize */
			NULL,				/* class_data */
			sizeof (SomeObject),
			0,				/* n_preallocs */
			some_object_instance_init	/* instance_init */
    		};

		/* Since our type has no parent, it is considered 
		"fundamental", and we have to inform the system that our
		type is both classed (unlike say a float, int, or pointer),
		and is instantiable (the system can create instance objects.
		for example, Interfaces or Abstract classes are not 
		instantiable. */

		static const GTypeFundamentalInfo fundamental_info =
		{
			G_TYPE_FLAG_CLASSED | G_TYPE_FLAG_INSTANTIATABLE
		};	

		type = g_type_register_fundamental
		(
			g_type_fundamental_next (),	/* next available GType number */
			"SomeObjectType",		/* type name as string */
			&type_info,			/* type info as above */
			&fundamental_info,		/* fundamental info as above */
			0				/* type is not abstract */
		);
	}

	return	type;
}

/* Lets build a simple test driver for out our code! */

int	main()
{
	SomeObject	*testobj = NULL;

	/* This gets the type system up and running. */
	g_type_init ();

	/* Create an instance object from the system. */
	testobj = SOME_OBJECT (g_type_create_instance (some_object_get_type()));

	/* Call our methods. */
	if (testobj)
	{
		g_print ("%d\n", testobj->m_a);
		some_object_method1 (testobj, 32);

		g_print ("%s\n", testobj->m_b);
		some_object_method2 (testobj, "New string.");

		g_print ("%f\n", testobj->m_c);
		some_object_method3 (testobj, 6.9);
	}

	return	0;
}

Final Thoughts
-----

We have implemented our first object in C, but it was a lot of work, and there is no real object orientation here since we have purposely not said anything about inheritance. In the next section we will see how to make our lives much easier when interacting with other people's code by deriving our class SomeObject from the built-in base class GObject. 

<notice>
While we will reuse the ideas and patterns we have discussed above throughout the text, attempting to create a fundamental type that behaves as it should with other GTK+ code is very difficult and in-depth. It is recommended that you always create new types by deriving from GObject, since it does a lot of background work to make things behave how GTK+ assumes it should.
</notice>

2. Making use of built-in Macros to auto generate code

Design
-----
As you may have noticed, much of what we have done above ranges from the merely mechanical, to down-right boiler-plate. Most of our funtions are not general-purpose, and have to be individually re-written for each type we create. Surely this is why we have computers in the first place -- to automate such tasks and make our lives simpler! 

Well, we are in luck, since C's preprocessor will allow us to write macros that allow us to simply define a new type, which at compile time expands into the proper C code. Using macros also helps reduce human errors which may appear when declaring everything manually.

However with this automation we lose flexibility. There are a huge number of possible variations on the steps we have described above that we may want to make use of, but a macro can only implement one expansion. If the macro provides a light-weight expansion, and we want a complete type, then we have to write a lot of manual code anyways. If the macro provides a complete expansion, and we want a light-weight type then we either end up with code bloat, spending a lot of time filling in stubs we will never use, or just plain incorrect code. There is also the fact that C's preprocessor was simply not designed to do the find of code generation we are interested in, and has limited features we can make use of.

Code
-----
The code for creating a new type is pretty simple: 
G_DEFINE_TYPE_EXTENDED (TypeName, function_prefix, PARENT_TYPE, GTypeFlags, CODE)

The first parameter is the name of the type. The second is the prefix that will be prepended to the names of functions, and thus conform to our naming convention. The third is the GType of the object that we wish to inherit from. The fourth is the GTypeFlag which will be added to the GTypeInfo struct. The fifth parameter is for any code we want to run immediately after the type has been registered.

What would be more enlightening, however, would be to look at what code the above actually expands to.

G_DEFINE_TYPE_EXTENDED (SomeObject, some_object, 0, some_function())

<notice>
The exact code which the macro will expand to is dependent on the version's implementation. You should always check the expansion before you make assumptions about what a macro genereates.
</notice>

expands to (after cleaning up the whitespace):

static void some_object_init (SomeObject *self);
static void some_object_class_init (SomeObjectClass *klass);
static gpointer some_object_parent_class = ((void *)0);

static void some_object_class_intern_init (gpointer klass) 
{
	some_object_parent_class = g_type_class_peek_parent (klass); 
	some_object_class_init ((SomeObjectClass*) klass);
} 

GType some_object_get_type (void) 
{
	static GType g_define_type_id = 0; 
	if ((g_define_type_id == 0)) 
	{ 
		static const GTypeInfo g_define_type_info = 
		{ 
			sizeof (SomeObjectClass), 
			(GBaseInitFunc) ((void *)0), 
			(GBaseFinalizeFunc) ((void *)0), 
			(GClassInitFunc) some_object_class_intern_init, 
			(GClassFinalizeFunc) ((void *)0), 
			((void *)0), 
			sizeof (SomeObject), 
			0, 
			(GInstanceInitFunc) some_object_init, 
		}; 

		g_define_type_id = g_type_register_static 
		(
			G_TYPE_OBJECT, 
			"SomeObject", 
			&g_define_type_info, 
			(GTypeFlags) 0
		);
		
		{ some_function(); } 
	} 

	return g_define_type_id; 
}

<notice>
The macro defines a static variable called "<PREFIX>_parent_class", which is a pointer to the parent class of the object we are creating. This is needed when you want to discover the parent of the virtual method, and not the parent of the given GObject derived object, and is used primarily in chaining dispose/finalize, which are almost always virtual. Our code further on will not use this construct, since there are functions that do this without keeping a static variable.
</notice>

As you should have noticed, there is not code generated for base_init/finalize or class_finalize. If you need these functions, then you should write your code from scratch.
 
3. Creating a single Object derived from GObject

Design
-----

While we can now make a rudimentary object, we have intentionally ignored the context of our type system: as the basis of a sophisticated suite of libraries; chiefly the GUI library GTK+. The design of GTK+ calls for a root object that all others derive from. This allows a least common denominator functionality that all objects will share: signal support (for passing messages easily from one object to another), lifetime management via reference counting, properties support (for easily setting and getting an object's data fields), and constructor/destructor support (which know how to setup signals,refernces and properties). When we derive our object from GObject, we get all of the above, and generally make things easier when interacting with other GObject based libraries. However, we will not talk about signals, reference counting, properties, or any other specific features in this chapter; instead this chapter will concentrate on how inheritance works in the type system.

As we already know, if LuxuryCar inherits from Car, we know that LuxuryCar *is* a Car, plus some new specific features. How can we get our system to mimic this behaviour? We can use a trick that exploits a feature of C structs: the first member listed in a struct's definition must be the first member found in memory. If we insist that all objects declare their parent as the first member of their own struct, then we can quickly turn a pointer to any object into a pointer to its parent by simply casting the pointer to it's parent! While this trick is very handy, and syntactically very clean, this kind of cast only works with pointers -- you can't cast regular structs this way.

<notice>
This casting trick is *not* at all type safe. Casting an object to something other than its parent is perfectly valid, but highly unwise. It is up to the programmer to ensure his casts are safe.
</notice>

Creating Type Instances
-----
With this technique in mind, how does the type system instantiate objects? The first time we ask the system to create an instance object through the function g_type_create_instance, it must first create a class object for the instance to use. If the class struct is derived from another, the system needs to create and initialize those parent class objects too. The system can do this because we have specified a structure (the GTypeInfo struct in *_get_type), that describes each object's instance size, class size, initialization functions, and finalize functions.

- to instanciate an object with g_type_create_instace
	if there is no corresponding class object
		create it and add it to the class hierarchy
	create instance object and return a pointer to it

When the system creates a new class object, it first allocates enough space to put the final requested class object in. It then proceeds from parent-most class object to child-most class object in the inheritance tree, overwriting the final class object's fields with its parents' at the memory level. This is how children inherit from their parents. After it has copied one parent's data over, the system runs that parent class's "base_init" function on the class object in its current state. This process of overwriting and executing "base_init"s continues until it has been completed for every parent of the final class. Next the system runs the final class's "base_init" and "class_init" on the final class object. The function "class_init" takes a parameter, which could be considered a class object constructor parameter, called "class_data" above.

The observant reader will wonder why the parent's base_init is needed when we have an exact copy of the parent object already? We need base_init when exact copy won't do, when some data has to be re-created for each class. For example a class member might point to another object, and we want each class to point to its own object (a memory copy is a "shallow copy", and we may want a "deep copy"). Experienced GObject programmers tell me that base_init is rarely used in practice.

When the system creates a new instance object, it first allocates enough space to put the instance object in. It then proceeds from parent-most instance object to child-most instance object and runs that parent class's "instance_init" function on the class object in its current state. Finally the system runs the final class's "instance_init" on the final class object.

I will try to summarize the algorithms I have described in some pseudo-code:

- to instantiate class object
	allocate memory for final_object
	for each class object from parent to child
		copy object over final_object
		run object's own base_init on final_object
	run final_object's base_init on final_object
	run final_object's class_init on final_object with class_data

- to instantiate instance object
	allocate memory for final_object
	for each class object from parent to child
		run object's own instance_init on final_object
	run final_object's instance_init on final_object


Now that there are two initialized class and instance objects, the system sets the instance object's class pointer to the class object, so that the instance object can access its class object containing its vtable. This is how the system instantiates any registered type; however GObject implements its own constructor and destructor semantics on top of what we have described above!

Creating GObject Instances
-----

Previously we used the function g_type_create_instance to give us a working instance object. However GObject gives us a new API for creating gobjects, built on top of everything we have discussed so far. GObject implements three new methods which are used by this API to create and destroy new GObjects: constructor, dispose, and finalize.

Since C lacks many of the polymorphic features of true OO languages, specifically the ability to admit multiple constructors, GObject's constructor requires some digression:

How can we flexibly pass various kinds of initialization information to our object in a way that makes object construction easy to do? We might consider restricting ourselves to only using copy constructors, filling in a static "init object" with what ever specific fields we want, and passing the "init object" to the copy constructor to finish the job -- simple but not very flexible. 

However the GObject authors have devised a much more general solution that also provides a handy getting-and-setting mechanism called "properties", which encasulates raw access to an object's data fields. With this system our properties are named with a string, and protected with bounds and type checking. Properties can also be specified to be writable at contruction-time only, like const variables in C++.

Properties makes use of a polymorphic type called GValue, which allows the programmer to safely copy a value without knowing the specific type beforehand. GValue works by tracking the GType of the value it holds, and using the type system to make sure it always has a virtual function which can handle copying to another GValue or conversion to another GType. We will discuss GValues and Properties in following sections.

To create a new property for a GObject, we define it's type, name, and default value, then create an object that ecapsulates that information called a "property specification". In the GObject's class_init function we use the function g_object_class_install_property to attach the property specification to the GObject's class object.

<notice>
Any child object that adds a new property must override the set_property and get_property virtual functions it inherited from GObject. Exactly what these methods do will be covered in a later section.
</notice>

With properties we can pass our constructor an array on property specifications, and the initial values we want, then simply call set_property on the GObject, and get all the benefits of properties magically. However as we will see later, we never call the constructor directly.

Another feature of GObject's constructor that is not so obvious is that each constructor needs to accept a GType argument and pass that GType to its parent's constructor in case it becomes a parent to another object. This is because GObject's constructor must know the GType of the final child object since it is GObject's constructor that calls g_type_create_instance using the that child's GType.

<notice>
If we specify our own constructor, then we must override the default constructor given to us from our parent. The constructor must then "chain up" to the parent class by calling the parent's constructor *before* it has done any work. However since we are using properties, in practice we never need to override the default constructor.
</notice>

I must appologize of the above digressions, but it is a complexity we must come to grips with to understand how the whole things works. With what we have discussed above, we can now understand GObject's constuction function, g_object_new. This function takes a GType corresponding to the GType of the GObject derived object we wish to create, and a series of property names (which you recall are just C strings) and GValue pairs. 

This series is converted into a list of pairs, and the corresponding property specifications, that we installed in the system in our class_init function, are found. The constructor defined in the class object is called with the GType and construction properties as arguments. From child-most constructor to parent-most constructor, the chain is followed until GObject's constructor is run -- in effect it is the first real initialization code to run. GObject's constructor first calls g_type_create_instance using the GType we carried all the way from g_object_new, and the process we descibed in detail previously occurs in order to create an instance. Next it gets the final object's class, and calls the set_property method on all the construction properties passed via the constructor. That is why we always have to override the get_/set_preoprty methods any time we add a new property. As the chained constructors return, the code contained therein gets executed from parent to child. 

As parent constructors return, it becomes the child's turn to execute its own initialization code. In effect the order of execution of code becomes:
1. from GObject to ChildObject run instance_init
2. from GObject to ChildObject run constructor

Lastly any remaining properties that weren't passed to the constructor are set using the set_property methods one last time. 

The astute read may wonder then under what circumstances should they override the default constructor and put their own code in their own constructor? Since all our properties are set with the virtual method set_property, there is almost never any need to override GObject's default constructor.

I will attempt to summarize the GObject construction process with the following pseudo-code:

- to create a proper GObject based object given type a list of property+value pairs:
	lookup the specifications corresponding to pairs and place in list
	call final_object's constructor on with specification_list and type
		recursively descend to GObject's constructor
			call g_type_create_instance with type
			call virtual set_property with specification_list
	call virtual set_property with remaining properties

<notice>
GObject divides properties into two classes, construct and "regular" properties.
</notice>

Destroying GObject instances
-----

With that work done, we can look to what happens when we no longer need the object. However the destructor concept from other OO languages is in GObject decomposed into two methods: dispose and finalize.

The dispose method is called when the object first knows it will be destroyed. It is supposed to release any references to resources that may need some advance warning due to reference cycles, or may be scarce and thus contended for by other objects. The dispose method may be called any number of times, and thus the code therein should be safe in that case. Guarding the dispose code with a static variable is a common practise. The object is also expected to be usable without unrecoverable error (such as a SEGFAULT) after dispose has been run, so some members cannot be freed or altered during the dispose process. Recoverable errors, such as returning error codes or NULL values, are fine.

The finalize method finishes releasing the remaining resources just before the object itself will be freed from memory, and therefore it will only be called once. The two step process helps reduce cycles in reference counting schemes. 

<notice>
If we specify our own dispose and finalize, then we must override the default dispose and finalize given to us from our parent. Both dispose and finalize must "chain up" to the parent class by calling the parent's respective dispose and finalize methods *after* they have destroyed their own members.
</notice>

Unlike the constructor, we will frequently need to override the dispose and finalize methods whenever our object allocates resources which must be freed.

Knowing which method is the appropriate place to put certain destruction code is in general not an easy problem to solve. However, when dealing with reference counted libraries (such as GTK+), one should unreference all objects in dispose, and free all memory or close file descriptors in finalize.

We discussed g_object_new, but when do we get to destroy our objects? As we have alluded to above, GObjects are reference counted, which is to say that it keeps an integer value counting how many other objects or functions are currently "using" or referencing it. When you want to work with a GObject, and thus want to guarentee that it doesn't destroy itself while you're using it, you must call g_object_ref with the object as a parameter as soon as possible. This simply increments the reference count. Failing to do so may allow the object to be destroyed, and cause your program to crash.

Similarly, when you are finished working with the object, you must call g_object_unref. This will decrement the reference count, and check if it is zero. When the count reaches zero, the object will be disposed then eventually finalized. Failing to unreference a GObject is a memory leak since the count can never reach zero.

Finally, we are now ready to write some code! But don't let the above lengthy and difficult prose intimidate you. If you don't totally understand what is being said yet, don't worry -- GObject is complex! Read on for more details, try out some sample programs, or just get some sleep and read it over tomorrow.

What we write will look very similar to our first example, in fact I will leave some of the more inconsequential or redundant code out. 

Code (header)
-----

<step>
We proceed as before, but this time we create our structs with the first member being the parent object. In this case the parent object is GObject.
</step>

/* Our "Instance struct" defines all the data fields that make our object unique. */
typedef struct _SomeObject SomeObject;
struct _SomeObject
{
	GObject		parent_obj;

	/* Some useful fields may follow. */
};

/* Our "Class struct" defines all the method functions that our objects will share. */
typedef struct _SomeObjectClass SomeObjectClass;
struct _SomeObjectClass
{
	GTypeClass	parent_class;

	/* Some useful methods may follow. */
};

<step>
The rest of the header file proceeds familiarly.
</step>


Code (source)
-----

<notice>
We need to add declarations for the GObject specific methods we are going to override.
</notice>

/* These are the GObject Construct/Destroy methods. Their signatures are determined in gobject.h. */
void	some_object_constructor (GType this_type, guint n_properties, GObjectConstructParam *properties)
{
	/* If our class is derived from, and the child wants to chain to us, then this_type will
	   NOT be SOME_OBJECT_TYPE, rather g_type_peek_parent will be SOME_OBJECT_TYPE, and we will 
	   have an infinite loop. */

	GObjectClass *parent_class = g_type_class_peek (g_type_peek_parent (SOME_OBJECT_TYPE()));
	 
	some_object_parent_class-> constructor (self_type, n_properties, properties);

	/* There is rarely need to do work here */
}

void	some_object_dispose (GObject *self)
{
	GObjectClass *parent_class = g_type_class_peek (g_type_peek_parent (SOME_OBJECT_TYPE()));
	static gboolean first_run = TRUE;

	if (first_run)
	{
		first_run = FALSE;
		
		/* Call g_object_unref on any GObjects that we hold, but don't break the object */

		parent_class-> dispose (self);
	}
}

void	some_object_finalize (GObject *self)
{
	GObjectClass *parent_class = g_type_class_peek (g_type_peek_parent (SOME_OBJECT_TYPE()));

	/* Free any memory or close any files */ 

	parent_class-> finalize (self);
}

<notice>
GObjectConstructParam is a struct with two members, one is an array of parameter specifications of type GParamSpec, and the other is an array of corresponding values of type GValue.
</notice>

/* These are the GObject Get and Set Property methods. Their signatures are determined in gobject.h. */
void	some_object_get_property (GObject *object, guint property_id, GValue *value, GParamSpec *pspec)
{
}

void	some_object_set_property (GObject *object, guint property_id, const GValue *value, GParamSpec *pspec)
{
}


/* Here is where we override any functions. Since we have no properties or even fields, none of the below are needed. */
void	some_object_class_init		(gpointer g_class, gpointer class_data)
{
	GObjectClass	*this_class	= G_OBJECT_CLASS (g_class);
	
	this_class-> constructor	= &some_object_constructor;
	this_class-> dispose		= &some_object_dispose;
	this_class-> finalize		= &some_object_finalize;

	this_class-> set_property	= &some_object_set_property;
	this_class-> get_property	= &some_object_get_property;
}

In order to talk about creating and destroying GObjects, by necessity we had to touch on properties and certain other quirks. However I left property code from the example, deffering that discussion to the next section. Try not to let the complexity of it all overwhelm you. After you've wrestled with the ideas a little more, they will start to make more sense. As for above, we have contrained ourselves to making a basic GObject, which in the next sections we will actually make function. The important part, is that we have learned the tools that we will need to make the rest of the document easier to understand.


4. Properties

We have alluded to what a wonderful thing properties are, and how they go about it, but to get into any more detail we need to digress yet again.

GValues
-----

C is a strongly type-checked language, meaning the compiler makes you declare the type of variable you want to use, and complains any time you use it in a way inconsistent with that type. This is a good thing since it makes the resulting code fast, and helps us catch type mistakes that could cause crashes or insecure behaviour. This is also a bad thing since we programmers live and think in a world that is hardly as strict, and we wish to have our type behave polymorphically -- that is change their behaviour in different contexts. And as we have seen above in our discussions of inheritance, to get a little polymorphism we can to resort to C casts. However when declaring functions and passing simple values to them, using raw pointers can become troublesome. Lucky, the type system gives us another tool that C doesn't have: the GType. 

Lets frame the problem more clearly. I want a data type that implements a list of various types of values, and I want to be able to write an interface to that list that doesn't depend on the specific type of the value given and doesn't require me specify redundant functions for each value type. Such an interface must have some type, so we'll call it GValue (for Generic Value). How can we implement such a beast?

We create a structure that encapsulates our value, and has two fields: a union of all representable fundamental types (ie: char, int, double, pointer, ...), and the GType of the value stored in that union. In this way we can hide the value's type within GValue, yet still guarentee type safety by checking any GValue operations against the GType. This also downloads the specification of redundant type based operations (such as get_int, set_float, ...) into g_value_* which keeps your API free from such trouble. 

The wary reader will notice that each GValue takes up at least as much memory as the largest fundamental type (usually 8 bytes), plus the size of GType. GValues are not space efficient, have a non-trivial overhead, and therefore should not be used in mass quantities. The most common usage is for specifying generic APIs. 

Exactly how GValue works outside of this is a little beyond the scope of this discussion, but it is helpful to understanding properties.

<example>
/* Lets copy an integer around using GValue! */
#define g_value_new(type) g_value_init (g_new (GValue, 1), type)

GValue *a = g_value_new (G_TYPE_UCHAR);
GValue *b = g_value_new (G_TYPE_INT);
int c = 0;

g_value_set_uchar (a, 'a');
g_value_copy (a, b);

c = g_value_get (b);
g_print ("w00t: %d\n", c);

g_free (a);
g_free (b);
</example>

Design
-----

We have already touched on properties above, so we already have a justification for their existance, but lets continue to motivate the rest of their design for tradition's sake!

To continue building a general property setting mechanism, we need a way to parameterize, and then later find the property name independently of what we might have named the variable in our instance struct. Externally we wish to use C strings to specify the property from the public API, but internally that is far slower than necessary. Therefore we enumerate the properties, and use an index into that enumeration to identify the property within our own code.

We have already mentioned the property specification, called GParamSpec in Glib, which holds our object's GType, our object's property name, our property enumerated ID, default value, boundary values, and more. Thus the GParamSpec is what allows the type system to map string names to enumerated property IDs, and is the glue that holds everything together.

When we wish to set or get a property, we call g_object_set/get_property on our object with the property name, and a GValue that holds the value we wish to set. The g_object_set_property function then looks up the GParamSpec associated with the property name, looks up our object's class, and calls the object's set_property method on the object. This implies that if we introduce any properties, we must override the set/get_property method. Also any properties introduced by the parent class are handled properly by the parent's set/get_property methods, since that is the class where the GParamSpec was installed from. Finally it imples that we must install a GParamSpec from our object's class_init! 

Lets add the code to handle properties to our SomeObject! We will assume we already have a working skeleton as presented in the previous section.

Code (header)
-----

<step>
AS above, except we added two properties.
</step>

/* Our "Instance struct" defines all the data fields that make our object unique. */
typedef struct _SomeObject SomeObject;
struct _SomeObject
{
	GObject		parent_obj;

	/* Our properties */
	int		a;
	float		b;

	/* Some useful fields may follow. */
};


Code (source)
-----

<step>
Create an enumeration for internally tracking properties.
</step>

enum
{
	OBJECT_PROPERTY_A = 1 << 1;
	OBJECT_PROPERTY_B = 1 << 2;
};

<step>
Implement the handlers for the properties we introduced.
</step>

/* These are the GObject Get and Set Property methods. Their signatures are determined in gobject.h. */
void	some_object_get_property (GObject *object, guint property_id, GValue *value, GParamSpec *pspec)
{
	SomeObject *self = SOME_OBJECT (object);

	switch (property_id)
	{
		case OBJECT_PROPERTY_A:
			g_value_set_int (value, self-> a);
			break;

		case OBJECT_PROPERTY_B:
			g_value_set_float (value, self-> b);
			break;

		default: /* No property with that ID!! */
	}
}

void	some_object_set_property (GObject *object, guint property_id, const GValue *value, GParamSpec *pspec)
{
	SomeObject *self = SOME_OBJECT (object);

	switch (property_id)
	{
		case OBJECT_PROPERTY_A:
			self-> a = g_value_get_int (value);
			break;

		case OBJECT_PROPERTY_B:
			self-> b = g_value_get_float (value);
			break;

		default: /* No property with that ID!! */
	}
}

<step>
Override the set/get_property methods inherited from our parent and install GParamSpecs.
</step>

/* Here is where we override any functions. */
void	some_object_class_init		(gpointer g_class, gpointer class_data)
{
	GObjectClass	*this_class	= G_OBJECT_CLASS (g_class);
	GParamSpec	*spec;
	
	this_class-> constructor	= &some_object_constructor;
	this_class-> dispose		= &some_object_dispose;
	this_class-> finalize		= &some_object_finalize;

	this_class-> set_property	= &some_object_set_property;
	this_class-> get_property	= &some_object_get_property;

	spec = g_param_spec_int
	(
		"property-a",				/* property name */
 		"a",					/* nickname */
		"Mysterty value 1",			/* description */
		5,					/* minimum */
		10,					/* maximum */
		5,					/* default */
		G_PARAM_READABLE |G_PARAM_WRITABLE	/* GParamSpecFlags */
	);
	g_object_class_install_property (this_class, OBJECT_PROPERTY_A, spec);

	spec = g_param_spec_float
	(
		"property-b",				/* property name */
 		"b",					/* nickname */
		"Mysterty value 2			/* description */
		0.0,					/* minimum */
		1.0,					/* maximum */
		0.5,					/* default */
		G_PARAM_READABLE |G_PARAM_WRITABLE	/* GParamSpecFlags */
	);
	g_object_class_install_property (this_class, OBJECT_PROPERTY_B, spec);
}

5. Signals
-----