Philip Withnall
philip.withnall@collabora.co.uk 2015
Tutorial para escribir una implementación de `GSource` personalizada
Daniel Mustieles
daniel.mustieles@gmail.com 2011 - 2019
Nicolás Satragno
nsatragno@gmail.com 2012 - 2013
Jorge González
jorgegonz@svn.gnome.org 2011

# GSources personalizadas

#

        Resumen

        Este artículo es un tutorial para escribir una GSource personalizada. Para ver la documentación de referencia, consulte la  referencia de la API de GLib.

# ¿qué es `GSource`?

Una `GSource` es un evento esperado con una función de retorno de llamada asociada que se invocará cuando se reciba un evento. Un evento puede ser una expiración de tiempo o datos que se reciben en un socket, por ejemplo.

GLib contiene varios tipos de `GSource`, pero también permite que las aplicaciones definan las suyas propias, permitiendo integrar eventos personalizados en el bucle principal.

La estructura de una `GSource` y sus funciones virtuales están documentadas detalladamente en la referencia de la API GLib.

# Una fuente de cola de mensajes

Como ejemplo de ejecución, se usará una cola de fuentes de mensajes que ejecuta su función de retorno de llamada cuando se mete en la cola un mensaje en la cola interna de la fuente (potencialmente de otro hilo).

Este tipo de fuente es útil para transferir de manera eficiente un gran número de mensajes entre contextos principales. LA alternativa es transferir cada mensaje en una `GSource` libre separada, usando `g_source_attach()`. Para un gran número de mensajes esto implica reservar y liberar muchas `GSource`.

## Estructura

Primero se debe declarar una estructura para la fuente. Esta debe contener una `GSource` como su padre, seguida de los campos privados para la fuente: la cola y una función para llamar a cada mensaje libre cuando termine con él.

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

## Función de preparación

Lo siguiente es definir la función de preparación para la fuente. Esto determina si la fuente está lista para servirse. Dado que esta fuente usa una cola en memoria, se puede determinar comprobando la longitud de la cola: si hay elementos en la cola, se puede usar la fuente para gestionarlos.

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

## Función de comprobación

Como esta fuente no tiene descriptores de archivos, las funciones de preparación y comprobación tienen esencialmente el mismo trabajo, por lo que no se necesita la función de comprobación. Establecer el campo a `NULL` en `GSourceFuncs` evita la función de comprobación para este tipo de fuente.

## Función de gestión

Para esta fuente, es en la función de gestión donde reside la complejidad. Debe sacar de la cola un mensaje y pasarlo a la función de retorno de llamada de la `GSource`. No se deben quedar mensajes en la cola: aunque la función devuelva verdadero, otra fuente que abstraiga la misma cola se puede haber gestionado en este tiempo y haber tomado el mensaje final de la cola. Además, si no se ha establecido una función de retorno de llamada para la `GSource` (algo que está permitido), el mensaje puede destruirse y descartarse silenciosamente.

Si se han definido el mensaje y la función de retorno de llamada, se puede llamar a esta última sobre el mensaje y devolverá el valor propagado como valor de retorno de la función de gestión. Este es `FALSE` para destruir la `GSource` y `TRUE` para mantenerla, igual que para `GSourceFunc`: estas consideraciones semánticas son las mismas para todas las implementaciones de las funciones de gestión.

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

## Funciones de retorno de llamada

La función de retorno de llamada de una `GSource` no tiene que tener un tipo `GSourceFunc`. Puede ser una función de cualquier tipo a la que se llame en la función de gestión de la fuente, ya que este tipo está suficientemente documentado.

Normalmente se usa `g_source_set_callback()` para configurar la función de retorno de llamada para una instancia de una fuente. Cuando es `GDestroyNotify` se hace una referencia fuerte para mantener vivo un objeto mientras la fuente sigue viva:

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

Sin embargo, `GSource` tiene una capa de indirección para obtener esta función de retorno de llamada, disponible mediante `g_source_set_callback_indirect()`. Esto permite a GObject establecer una `GClosure` como función de retorno de llamada de una fuente, lo que permite que las fuentes se destruyan automáticamente cuando un objeto termina: una referencia débil, en contraste con la referencia fuerte mencionada anteriormente:

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

También permite una función de retorno de llamada «tonta» basada en el cierre, que se puede usar cuando una fuente debe existir pero no se necesita realizar ninguna acción en su retorno:

g_source_set_dummy_callback (source);

## Constructor

Finalmente se puede escribir la definición de las `GSourceFuncs` de la `GSource` junto con la función de construcción de las `GSource`. Normalmente es práctico exponer los nuevos tipos de fuentes como `GSource` y no como el subtipo de la estructura; de este modo, el constructor devuelve un `GSource*`.

Aquí el constructor de ejemplo también muestra el uso de una fuente hija para soportar la cancelación adecuadamente. Si se cancela la `GCancellable` se gestiona el retorno de la aplicación y se puede comprobar la cancelación. (El código de la aplicación deberá crear un puntero a la `GCancellable` disponible para la función de retorno, como un campo de los datos de usuario de la función de retorno configurada en `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; }

# Ejemplo completo

## Código de ejemplo completo

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

# Ejemplos adicionales

Las fuentes pueden ser más complejas que las dadas en el ejemplo anterior. En libnice, se necesita una `GSource` personalizada para sondear un conjunto de sockets que cambia dinámicamente. La implementación se da como `ComponentSource` en component.c y muestra un uso más complejo de la función de preparación.

Otro ejemplo es una fuente personalizada para que sirva de interfaz de GnuTLS con GLib en su implementación de `GTlsConnection`. `GTlsConnectionGnutlsSource` sincroniza el hilo principal y un hilo trabajador TLS que realiza las operaciones de bloqueo de TLS.