Blog Archives

g_source_unref() and g_source_destroy() are your friends

After almost 2 years developing GLib-based applications, I understood the proper way of using GSource objects. Yes, quite a shame, but better now than never.

Now, after re-reading carefully the GLib Reference Manual, I see that it is quite clearly explained the difference between g_source_destroy() and g_source_unref(). So the typical suggestion is still the best one: RTFM!!

In our applications, we usually need to attach timeout operations to the context of an specific thread, not to the main thread context. Thus, we cannot use g_timeout_add() or the pretty new g_timeout_add_seconds().

For example, you could create a GThreadPool, and in the function to be executed in each thread, you could create a specific context for the thread, plus a main loop in the context:

    /* Create a GLib Main Context */
    context = g_main_context_new();

    /* Create a Main Loop in the context*/
    main_loop = g_main_loop_new(context,
                                FALSE);

Once you have a new context and main loop, you can just create a new GSource, and attach it to the main loop. As soon as you create the GSource, its reference count is 1, and as soon as you attach it to the main loop, its reference count will be 2.

    /* Create new timeout source to be called
     * every 5 seconds.
     * Reference count of source is 1 once created */
    source = g_timeout_source_new(TIMEOUT_MSECS);

    /* Set callback to be called in each timeout */
    g_source_set_callback(source,
                          (GSourceFunc)__timeout_func,
                          main_loop,
                          NULL);

    /* Attach the GSource in the GMainContext.
     * Reference count of source is 2 after this call */
    g_source_attach(source,
                    context);

Of, course, you will be now running the main loop:

    /* Run the main loop, until it is stopped */
    g_main_loop_run(main_loop);

The key now is how to destroy the GSource properly. When calling g_source_destroy(), you are doing 2 things: first, telling the main loop to forget about the GSource; and second, decrementing the reference count of the GSource. Then, you still need to call g_source_unref() to fully decrement the reference counter so that the GSource is disposed.

    /* We did an attach() with the GSource, so we need to
     * destroy() it */
    g_source_destroy(source);

    /* We need to unref() the GSource to end the last reference
     * we got */
    g_source_unref(source);

To end the example, once the main loop is stopped, you will also need to properly dispose the GMainContext and GMainLoop objects:

    /* The main loop should be destroyed before the context */
    g_main_loop_unref(main_loop);

    /* Finally, destroy the context */
    g_main_context_unref(context);

This is just one way of keeping the GSource references properly managed:

  1. You get one reference when you create the GSource
  2. You get a new reference when you attach it in the context
  3. You release one reference when you destroy it from the context
  4. You release last reference when you unref the final one

Of course, you could also choose to avoid storing the “extra” reference, and leave alive only the one inside the main context:

  1. You get one reference when you create the GSource
  2. You get a new reference when you attach it in the context
  3. You release one reference when you unref the the GSource —> Now, the only reference is inside the GMainContext
  4. You release last reference when you destroy it from the context

You can check this simple example in the following program I prepared, released into public domain:
http://es.gnu.org/~aleksander/glib/test-gsource.c

Hope it helps someone out there to fully understand the difference between g_source_destroy() and g_source_unref().

As last comment… I would really rename the following functions in the library, so that no one else is confused with the “unref” and “destroy” terms:

  • Rename g_source_attach() to g_source_attach_to_context()
  • Rename g_source_destroy() to g_source_destroy_from_context()

The main reason is that these two operations actually act on the GMainContext, while the name of the functions do not suggest that fact.

Avoid G_TYPE_INSTANCE_GET_PRIVATE() in GObjects

When developing GObjects in Glib/GObject framework, it is usual to have a structure defined in the source file with all the private members of the object. Doing this, the internals of the object are not published in its API, so that no other module outside can modify them without using the defined GObject methods.

There are several ways to achieve this, and one of them is the recommended one in GObject’s tutorial [1], which uses the G_TYPE_INSTANCE_GET_PRIVATE [2] macro to get the glib-instantiated private structure. This private structure, allocated for each instance of the object, is specified in the Class initialization function with g_type_class_add_private(), and allocated every time a new GObject instance is created.

Usually, you will have a macro for your specific GObject which will call G_TYPE_INSTANCE_GET_PRIVATE:

#define MY_GOBJECT_GET_PRIVATE(o) \
    (G_TYPE_INSTANCE_GET_PRIVATE((o), MY_GOBJECT_TYPE, MyGObjectPrivate))


This seems a good way of doing it, and quite simple to use. Glib will take care of allocating and deallocating that private structure for us… so why avoid it?

Well… if you ever tried to run Valgrind’s callgrind tool to measure how much time your program spends in a given function, you will see the reason. Other people already did that and published results on the web, so go and check them [3] or just try it with your application:

$> valgrind --tool=callgrind /usr/local/bin/your_program</span


Now, an easy way of getting the same result, with a little bit more of work but achieving the best performance, is just using an opaque pointer in the GObject’s public structure and define, allocate and deallocate it yourself in the source file (so also can be treated as private, as the users of the API don’t know the internals of the structure).

These are the basic changes you need to do to avoid calling G_TYPE_INSTANCE_GET_PRIVATE():

**** In the HEADER of the GObject, when the struct defining the Object is specified, add a “gpointer priv” variable.

struct _MyGObject
{
    /** Parent object */
    GObject parent;
    /** Private data pointer */
    gpointer priv;
}


**** Then, in the SOURCE of the GObject, modify the GET_PRIVATE macro so that instead of doing the standard GObject lookup for the correct type, we just get the opaque “priv” pointer defined in the header, and we cast it to the correct type.

#define MY_GOBJECT_GET_PRIVATE(o) \
    ((MyGObjectPrivate *)((MY_GOBJECT(o))->priv))


**** As we won’t use the automatic allocation of the Private data structure, we need to allocate it ourselves in the _init() function.

static void
my_gobject_init(MyGObject *self)
{
    /* Allocate Private data structure */
    (MY_GOBJECT(self))->priv = \
        (MyGObjectPrivate *) g_malloc0(sizeof(MyGObjectPrivate));
    /* If correctly allocated, initialize parameters */
    if((MY_GOBJECT(self))->priv != NULL)
    {
        MyGObjectPrivate *priv = MY_GOBJECT_GET_PRIVATE(self);
        /* Initialize private data, if any */
    }
}


**** And finally, the last change is just de-allocating the structure when no more needed in the _dispose() function.

static void
my_gobject_dispose(GObject *object)
{
    MyGObject *self = (MyGObject *)object;
    MyGObjectPrivate *priv = MY_GOBJECT_GET_PRIVATE(self);
    /* Check if not NULL! To avoid calling dispose multiple times */
    if(priv != NULL)
    {
        /* Deallocate contents of the private data, if any */
        /* Deallocate private data structure */
        g_free(priv);
        /* And finally set the opaque pointer back to NULL, so that
         *  we don't deallocate it twice. */
        (MY_GOBJECT(self))->priv = NULL;
    }
}


References:

Please, forget it as soon as possible

New development version of Glib just released.

GLib 2.19.1 is now available for download at:

ftp://ftp.gtk.org/pub/glib/2.19/
http://download.gnome.org/sources/glib/2.19/

glib-2.19.1.tar.bz2 md5sum: 9309139a515408d9c99558d051c18302
glib-2.19.1.tar.gz md5sum: eab90f5965f3d004b8787989be5cca85

This is the second development release leading up to GLib 2.20.

It’s great they include the changelog with fixed bugs:

* Bugs fixed:
562538 GObject interface tutorial shouldn’t finalise with
“Please forget everything”

This one is great (among others, including multiple mem-leaks fixed).

Until this last release, the GObject tutorial had the following comment at the end of the “Non-instantiable classed types: interfaces” section:

“Now that you have read this section, you can forget about it. Please, forget it as soon as possible. “

What I am not sure about is: did they remove it because now interfaces are great? or just to skip publishing the idea that even GObject developers think that interfaces suck? Who knows…

Previous documentation:
http://library.gnome.org/devel/gobject/2.18/gtype-non-instantiable-classed.html
Latest documentation:
http://library.gnome.org/devel/gobject/unstable/gtype-non-instantiable-classed.html