<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" xmlns:xi="http://www.w3.org/2003/XInclude" type="guide" style="task" id="custom-gsource.c" xml:lang="ca">

  <info>

    <link type="guide" xref="c#examples"/>

    <credit type="author copyright">

      <name>Philip Withnall</name>

      <email its:translate="no">philip.withnall@collabora.co.uk</email>

      <years>2015</years>

    </credit>

    <include xmlns="http://www.w3.org/2001/XInclude" href="legal.xml"/>

    <desc>

      Tutorial for writing a custom GSource implementation

    </desc>

  </info>

  <title>Custom GSources</title>

  <synopsis>

    <title>Summary</title>

      This article is a tutorial on creating a custom GSource. For

      the reference documentation, see the

      <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#GSource">GLib

      API reference</link>.

  </synopsis>

  <section id="what-is-gsource">

    <title>What is GSource?</title>

      A <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#GSource">GSource</link>

      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

      <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#GSourceFuncs">GLib

      API reference</link>.

  </section>

  <section id="queue-source">

    <title>A Message Queue Source</title>

      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 GSources.

    <section id="gsource-structure">

      <title>Structure</title>

        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;

    </section>

    <section id="prepare-function">

      <title>Prepare Function</title>

        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);

    </section>

    <section id="check-function">

      <title>Check Function</title>

        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.

    </section>

    <section id="dispatch-function">

      <title>Dispatch Function</title>

        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);

    </section>

    <section id="callback">

      <title>Callback Functions</title>

        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);

    </section>

    <section id="constructor">

      <title>Constructor</title>

        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

        GSources, 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;

}

    </section>

  </section>

  <section id="full-listing">

    <title>Complete Example</title>

    <listing>

      <title>Complete Example Code</title>

      /**

 * 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;

}

    </listing>

  </section>

  <section id="further-examples">

    <title>Further Examples</title>

      Sources can be more complex than the example given above. In

      <link href="http://nice.freedesktop.org/">libnice</link>, a custom

      GSource is needed to poll a set of sockets which changes

      dynamically. The implementation is given as ComponentSource

      in <link href="http://cgit.freedesktop.org/libnice/libnice/tree/agent/component.c#n941">component.c</link>

      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.

      <link href="https://git.gnome.org/browse/glib-networking/tree/tls/gnutls/gtlsconnection-gnutls.c#n871">GTlsConnectionGnutlsSource</link>

      synchronizes the main thread and a TLS worker thread which performs the

      blocking TLS operations.

  </section>

</page>