GSource
implementation
This article is a tutorial on creating a custom GSource
. For
the reference documentation, see the
GLib
API reference.
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.
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.
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;
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);
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.
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);
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);
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;
}
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.