Philip Withnall
philip.withnall@collabora.co.uk 2015
Tutorial for writing a custom `GSource` implementation
Rafael Fontenelle
rafaelff@gnome.org 2013, 2018

# Custom GSources

#

        Summary

          This article is a tutorial on creating a custom GSource. For
          the reference documentation, see the
          GLib
          API reference.

# What is `GSource`?

A `GSource` is an expected event with an associated callback function which will be invoked when that event is received. An event could be a timeout or data being received on a socket, for example.

GLib contains various types of `GSource`, but also allows applications to define their own, allowing custom events to be integrated into the main loop.

The structure of a `GSource` and its virtual functions are documented in detail in the GLib API reference.

# A Message Queue Source

As a running example, a message queue source will be used which dispatches its callback whenever a message is enqueued to a queue internal to the source (potentially from another thread).

This type of source is useful for efficiently transferring large numbers of messages between main contexts. The alternative is transferring each message as a separate idle `GSource` using `g_source_attach()`. For large numbers of messages, this means a lot of allocations and frees of `GSource`s.

## Structure

Firstly, a structure for the source needs to be declared. This must contain a `GSource` as its parent, followed by the private fields for the source: the queue and a function to call to free each message once finished with.

typedef struct { GSource parent; GAsyncQueue *queue; /* owned */ GDestroyNotify destroy_message; } MessageQueueSource;

## Prepare Function

Next, the prepare function for the source must be defined. This determines whether the source is ready to be dispatched. As this source is using an in-memory queue, this can be determined by checking the queue’s length: if there are elements in the queue, the source can be dispatched to handle them.

return (g_async_queue_length (message_queue_source->queue) > 0);

## Check Function

As this source has no file descriptors, the prepare and check functions essentially have the same job, so a check function is not needed. Setting the field to `NULL` in `GSourceFuncs` bypasses the check function for this source type.

## Dispatch Function

For this source, the dispatch function is where the complexity lies. It needs to dequeue a message from the queue, then pass that message to the `GSource`’s callback function. No messages may be queued: even through the prepare function returned true, another source wrapping the same queue may have been dispatched in the mean time and taken the final message from the queue. Further, if no callback has been set for the `GSource` (which is allowed), the message must be destroyed and silently dropped.

If both a message and callback are set, the callback can be invoked on the message and its return value propagated as the return value of the dispatch function. This is `FALSE` to destroy the `GSource` and `TRUE` to keep it alive, just as for `GSourceFunc` — these semantics are the same for all dispatch function implementations.

/* Pop a message off the queue. */ message = g_async_queue_try_pop (message_queue_source->queue);

/* If there was no message, bail. */ if (message == NULL) { /* Keep the source around to handle the next message. */ return TRUE; }

/* @func may be %NULL if no callback was specified. * If so, drop the message. */ if (func == NULL) { if (message_queue_source->destroy_message != NULL) { message_queue_source->destroy_message (message); }

/* Keep the source around to consume the next message. */ return TRUE; }

return func (message, user_data);

## Callback Functions

The callback from a `GSource` does not have to have type `GSourceFunc`. It can be whatever function type is called in the source’s dispatch function, as long as that type is sufficiently documented.

Normally, `g_source_set_callback()` is used to set the callback function for a source instance. With its `GDestroyNotify`, a strong reference can be held to keep an object alive while the source is still alive:

g_source_set_callback (source, callback_func, g_object_ref (object_to_strong_ref), (GDestroyNotify) g_object_unref);

However, `GSource` has a layer of indirection for retrieving this callback, exposed as `g_source_set_callback_indirect()`. This allows GObject to set a `GClosure` as the callback for a source, which allows for sources which are automatically destroyed when an object is finalized — a weak reference, in contrast to the strong reference above:

g_source_set_closure (source, g_cclosure_new_object (callback_func, object_to_weak_ref));

It also allows for a generic, closure-based ‘dummy’ callback, which can be used when a source needs to exist but no action needs to be performed in its callback:

g_source_set_dummy_callback (source);

## Constructor

Finally, the `GSourceFuncs` definition of the `GSource` can be written, alongside a construction function. It is typical practice to expose new source types simply as `GSource`s, not as the subtype structure; so the constructor returns a `GSource*`.

The example constructor here also demonstrates use of a child source to support cancellation conveniently. If the `GCancellable` is cancelled, the application’s callback will be dispatched and can check for cancellation. (The application code will need to make a pointer to the `GCancellable` available to its callback, as a field of the callback’s user data set in `g_source_set_callback()`).

GSource * message_queue_source_new (GAsyncQueue *queue, GDestroyNotify destroy_message, GCancellable *cancellable) { GSource *source; /* alias of @message_queue_source */ MessageQueueSource *message_queue_source; /* alias of @source */

g_return_val_if_fail (queue != NULL, NULL); g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);

source = g_source_new (&message_queue_source_funcs, sizeof (MessageQueueSource)); message_queue_source = (MessageQueueSource *) source;

/* The caller can overwrite this name with something more useful later. */ g_source_set_name (source, "MessageQueueSource");

message_queue_source->queue = g_async_queue_ref (queue); message_queue_source->destroy_message = destroy_message;

/* Add a cancellable source. */ if (cancellable != NULL) { GSource *cancellable_source;

cancellable_source = g_cancellable_source_new (cancellable); g_source_set_dummy_callback (cancellable_source); g_source_add_child_source (source, cancellable_source); g_source_unref (cancellable_source); }

return source; }

# Complete Example

## Complete Example Code

/** * MessageQueueSource: * * This is a #GSource which wraps a #GAsyncQueue and is dispatched whenever a * message can be pulled off the queue. Messages can be enqueued from any * thread. * * The callbacks dispatched by a #MessageQueueSource have type * #MessageQueueSourceFunc. * * #MessageQueueSource supports adding a #GCancellable child source which will * additionally dispatch if a provided #GCancellable is cancelled. */ typedef struct { GSource parent; GAsyncQueue *queue; /* owned */ GDestroyNotify destroy_message; } MessageQueueSource;

/** * MessageQueueSourceFunc: * @message: (transfer full) (nullable): message pulled off the queue * @user_data: user data provided to g_source_set_callback() * * Callback function type for #MessageQueueSource. */ typedef gboolean (*MessageQueueSourceFunc) (gpointer message, gpointer user_data);

static gboolean message_queue_source_prepare (GSource *source, gint *timeout_) { MessageQueueSource *message_queue_source = (MessageQueueSource *) source;

return (g_async_queue_length (message_queue_source->queue) > 0); }

static gboolean message_queue_source_dispatch (GSource *source, GSourceFunc callback, gpointer user_data) { MessageQueueSource *message_queue_source = (MessageQueueSource *) source; gpointer message; MessageQueueSourceFunc func = (MessageQueueSourceFunc) callback;

/* Pop a message off the queue. */ message = g_async_queue_try_pop (message_queue_source->queue);

/* If there was no message, bail. */ if (message == NULL) { /* Keep the source around to handle the next message. */ return TRUE; }

/* @func may be %NULL if no callback was specified. * If so, drop the message. */ if (func == NULL) { if (message_queue_source->destroy_message != NULL) { message_queue_source->destroy_message (message); }

/* Keep the source around to consume the next message. */ return TRUE; }

return func (message, user_data); }

static void message_queue_source_finalize (GSource *source) { MessageQueueSource *message_queue_source = (MessageQueueSource *) source;

g_async_queue_unref (message_queue_source->queue); }

static gboolean message_queue_source_closure_callback (gpointer message, gpointer user_data) { GClosure *closure = user_data; GValue param_value = G_VALUE_INIT; GValue result_value = G_VALUE_INIT; gboolean retval;

/* The invoked function is responsible for freeing @message. */ g_value_init (&result_value, G_TYPE_BOOLEAN); g_value_init (&param_value, G_TYPE_POINTER); g_value_set_pointer (&param_value, message);

g_closure_invoke (closure, &result_value, 1, &param_value, NULL); retval = g_value_get_boolean (&result_value);

g_value_unset (&param_value); g_value_unset (&result_value);

return retval; }

static GSourceFuncs message_queue_source_funcs = { message_queue_source_prepare, NULL, /* check */ message_queue_source_dispatch, message_queue_source_finalize, (GSourceFunc) message_queue_source_closure_callback, NULL, };

/** * message_queue_source_new: * @queue: the queue to check * @destroy_message: (nullable): function to free a message, or %NULL * @cancellable: (nullable): a #GCancellable, or %NULL * * Create a new #MessageQueueSource, a type of #GSource which dispatches for * each message queued to it. * * If a callback function of type #MessageQueueSourceFunc is connected to the * returned #GSource using g_source_set_callback(), it will be invoked for each * message, with the message passed as its first argument. It is responsible for * freeing the message. If no callback is set, messages are automatically freed * as they are queued. * * Returns: (transfer full): a new #MessageQueueSource */ GSource * message_queue_source_new (GAsyncQueue *queue, GDestroyNotify destroy_message, GCancellable *cancellable) { GSource *source; /* alias of @message_queue_source */ MessageQueueSource *message_queue_source; /* alias of @source */

g_return_val_if_fail (queue != NULL, NULL); g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);

source = g_source_new (&message_queue_source_funcs, sizeof (MessageQueueSource)); message_queue_source = (MessageQueueSource *) source;

/* The caller can overwrite this name with something more useful later. */ g_source_set_name (source, "MessageQueueSource");

message_queue_source->queue = g_async_queue_ref (queue); message_queue_source->destroy_message = destroy_message;

/* Add a cancellable source. */ if (cancellable != NULL) { GSource *cancellable_source;

cancellable_source = g_cancellable_source_new (cancellable); g_source_set_dummy_callback (cancellable_source); g_source_add_child_source (source, cancellable_source); g_source_unref (cancellable_source); }

return source; }

# Further Examples

Sources can be more complex than the example given above. In libnice, a custom `GSource` is needed to poll a set of sockets which changes dynamically. The implementation is given as `ComponentSource` in component.c and demonstrates a more complex use of the prepare function.

Another example is a custom source to interface GnuTLS with GLib in its `GTlsConnection` implementation. `GTlsConnectionGnutlsSource` synchronizes the main thread and a TLS worker thread which performs the blocking TLS operations.