<?xml version="1.0" encoding="utf-8"?>
<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="topic" id="async-programming" xml:lang="es">

  <info>
    <link type="guide" xref="index#specific-how-tos"/>

    <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="cc-by-sa-3-0.xml"/>

    <desc>Uso de métodos asíncronos al estilo de GLib en varias situaciones</desc>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Daniel Mustieles</mal:name>
      <mal:email>daniel.mustieles@gmail.com</mal:email>
      <mal:years>2016-2020</mal:years>
    </mal:credit>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Javier Mazorra</mal:name>
      <mal:email>mazi.debian@gmail.com</mal:email>
      <mal:years>2016, 2020</mal:years>
    </mal:credit>
  </info>

  <title>Programación asíncrona</title>

  <synopsis>
    <title>Resumen</title>

    <list>
      <item><p>Uso de llamadas asíncronas con preferencia a las llamadas síncronas o uso explícito de hilos (<link xref="#concepts"/>)</p></item>
      <item><p>Aprenda y siga el patrón de GLib para declarar API asíncronas (<link xref="#api-pattern"/>)</p></item>
      <item><p>Coloque el retorno de llamadas de funciones asíncronas en orden descendente del archivo para que el control del flujo sea fácil de seguir (<link xref="#single-call"/>)</p></item>
      <item><p>Use la presencia de un <link href="https://developer.gnome.org/gio/stable/GTask.html"><code>GTask</code></link> o <link href="https://developer.gnome.org/gio/stable/GCancellable.html"><code>GCancellable</code></link> para indicar si una operación está en curso (<link xref="#single-call"/>, <link xref="#gtask"/>)</p></item>
      <item><p>Si ejecuta operaciones en paralelo, realice un seguimiento de cuántas operaciones aún deben comenzar y cuántas aún deben finalizar — la operación global se completa una vez que ambos recuentos son cero (<link xref="#parallel"/>)</p></item>
      <item><p>Separe el estado de las operaciones en estructuras ‘task data’ para <link href="https://developer.gnome.org/gio/stable/GTask.html"><code>GTask</code>s</link>, permitiendo que se reutilicen las operaciones más fácilmente sin necesidad de cambios en la gestión del estado global (<link xref="#gtask"/>)</p></item>
      <item><p>Considere cómo los métodos asíncronos en una instancia de un objeto interactúan con la finalización de esa instancia (<link xref="#lifetimes"/>)</p></item>
    </list>
  </synopsis>

  <section id="concepts">
    <title>Conceptos</title>

    <p>GLib soporta programación <em>asíncrona</em>, donde se pueden iniciar operaciones de larga duración, ejecutarlas ‘en segundo plano’, e invocar un retorno de función cuando se completan y sus resultados están disponibles. Esto está en contraste directo con las operaciones de larga duración <em>asíncronas</em>, que son una única llamada de función que bloquea el control de flujo del programa hasta que se completa.</p>

    <p>Como se discutió en <link xref="main-contexts"/> y <link xref="threading#when-to-use-threading"/>, las operaciones asíncronas deberían ser favorecidas sobre las síncronas y sobre el uso explícito de hilos. No bloquean el contexto principal como las operaciones síncronas y son más fáciles de utilizar correctamente que los hilos. Frecuentemente tienen una menor penalización en el rendimiento que generar un hilo y enviarle trabajo.</p>
  </section>

  <section id="api-pattern">
    <title>Patrón API</title>

    <p>Las llamadas asíncronas siguen un patrón estándar en código GLib. Para una operación llamada <code>load_data</code> en la clase <code>File</code> en el espacio de nombres <code>Foo</code>, habrá:</p>
    <list>
      <item>
        <code mime="text/x-csrc">
foo_file_load_data_async (FooFile             *self,
                          …,
                          GCancellable        *cancellable,
                          GAsyncReadyCallback  callback,
                          gpointer             user_data)</code>
      </item>
      <item>
        <code mime="text/x-csrc">
foo_file_load_data_finish (FooFile       *self,
                           GAsyncResult  *result,
                           …,
                           GError       **error)</code>
      </item>
    </list>

    <p>Los parámetros <code>…</code> para <code>foo_file_load_data_async()</code> son los específicos para la operación, en este caso, quizá el tamaño de un búfer para cargar. De manera similar para <code>foo_file_load_data_finish()</code> son los valores de retorno específicos de la operación, quizá una ubicación para devolver una cadena de tipo de contenido en este caso.</p>

    <p>Cuando se llama a <code>foo_file_load_data_async()</code>, planifica la carga de la operación en segundo plano (como un nuevo descriptor de un archivo en el <link xref="main-contexts"><code>GMainContext</code></link> o como un nuevo hilo activo, por ejemplo), después vuelve sin bloquear.</p>

    <p>Cuando se completa la operación, el <code>retorno de función</code> se ejecuta en el mismo <code>GMainContext</code> que la llamada asíncrona original. El retorno de función se invoca <em>exactamente</em> una vez, tanto si la operación concluyó con éxito como si concluyó con error.</p>

    <p>Desde el retorno de llamada <code>foo_file_data_finish()</code> se puede llamar por el código del usuario para obtener valores de retorno y detalles de error, pasando la instancia <link href="https://developer.gnome.org/gio/stable/GAsyncResult.html"><code>GAsyncResult</code></link> que se pasó al retorno de llamada.</p>
  </section>

  <section id="lifetimes">
    <title>Tiempos de vida de la operación</title>

    <p>Al escribir operaciones asíncronas, es común escribirlas como métodos de una clase. En este caso, es importante definir cómo las operaciones en curso en una instancia de clase interactúan con la finalización de esa instancia. Hay dos enfoques:</p>

    <terms>
      <item>
        <title>Fuerte</title>
        <p>La operación en curso mantiene una referencia a la instancia de clase, forzándola a permanecer viva mientras dure la operación. La clase debe proporcionar algún tipo de método de «cierre» o «cancelación» que otras clases puedan utilizar para forzar la cancelación de la operación y permitir que se finalice esa instancia.</p>
      </item>

      <item>
        <title>Débil</title>
        <p>La operación en curso <em>no</em> mantiene una referencia a la instancia de la clase, y la clase cancela la operación (usando <link href="https://developer.gnome.org/gio/stable/GCancellable.html#g-cancellable-cancel"><code>g_cancellable_cancel()</code></link>) en su función de disposición.</p>
      </item>
    </terms>

    <p>
      Which approach is used depends on the class’ design. A class which wraps
      a particular operation (perhaps a <code>MyFileTransfer</code> class, for
      example) might want to use the <em style="strong">weak</em> approach.
      A class which manages multiple network connections and asynchronous
      operations on them may use the <em style="strong">strong</em> approach
      instead. Due to incoming network connections, for example, it might not be
      in complete control of the scheduling of its asynchronous calls, so the
      weak approach would not be appropriate — any code dropping a reference to
      the object could not be sure it was not accidentally killing a new network
      connection.
    </p>
  </section>

  <section id="async-examples">
    <title>Ejemplos de uso de funciones asíncronas</title>

    <p>
      It is often the case that multiple asynchronous calls need to be used to
      complete an operation. For example, opening a file for reading, then
      performing a couple of reads, and then closing the file. Or opening
      several network sockets in parallel and waiting until they are all open
      before continuing with other work. Some examples of these situations are
      given below.
    </p>

    <section id="single-call">
      <title>Operación individual</title>

      <p>Una sola llamada asincrónica requiere dos funciones: una para iniciar la operación y otra para completarla. En C, la parte exigente de ejecarut una llamada asíncrona es almacenar correctamente el estado entre estas dos funciones y manejar los cambios a ese estado en el tiempo entre esas dos funciones que se están llamando. Por ejemplo, la cancelación de una llamada asíncrona en curso es un cambio de estado, y si no se implementa con cuidado, algunas actualizaciones de la IU (por ejemplo) realizadas al cancelar una operación serán deshechas por las actualizaciones en el retorno de llamada de la operación.</p>

      <example>
        <p>Este ejemplo muestra cómo copiar un archivo de una ubicación en el sistema de archivos a otra. Los principios clave demostrados aquí son:</p>
        <list>
          <item><p>
            Placing the <code>copy_button_clicked_cb()</code> (start) and
            <code>copy_finish_cb()</code> (finish) functions in order by using
            a forward declaration for <code>copy_finish_cb()</code>. This means
            the control flow continues linearly down the file, rather than
            getting to the bottom of <code>copy_button_clicked_cb()</code> and
            resuming in <code>copy_finish_cb()</code> somewhere else in the
            file.
          </p></item>
          <item><p>
            Use of a
            <link href="https://developer.gnome.org/gio/stable/GCancellable.html"><code>GCancellable</code></link>
            to allow cancelling the operation
            after it has started. The code in
            <code>cancel_button_clicked_cb()</code> is very simple: as the
            <code>copy_finish_cb()</code> callback is <em>guaranteed</em> to be
            invoked when the operation completes (even when completing early
            due to cancellation), all the UI and state updates for cancellation
            can be handled there, rather than in
            <code>cancel_button_clicked_cb()</code>.
          </p></item>
          <item><p>
            An operation is ongoing exactly while
            <code>MyObjectPrivate.copy_cancellable</code> is
            non-<code>NULL</code>, making it easy to track running operations.
            Note that this means only one file copy operation can be started
            via <code>copy_button_clicked_cb()</code> at a time. One
            <code>GCancellable</code> cannot easily be used for multiple
            operations like this.
          </p></item>
        </list>

        <code mime="text/x-csrc" style="valid">
static void
copy_finish_cb (GObject      *source_object,
                GAsyncResult *result,
                gpointer      user_data);

static void
copy_button_clicked_cb (GtkButton *button
                        gpointer   user_data)
{
  MyObjectPrivate *priv;
  GFile *source = NULL, *destination = NULL;  /* owned */

  priv = my_object_get_instance_private (MY_OBJECT (user_data));

  /* Operation already in progress? */
  if (priv-&gt;copy_cancellable != NULL)
    {
      g_debug ("Copy already in progress.");
      return;
    }

  /* Build source and destination file paths. */
  source = g_file_new_for_path (/* some path generated from UI */);
  destination = g_file_new_for_path (/* some other path generated from UI */);

  /* Set up a cancellable. */
  priv-&gt;copy_cancellable = g_cancellable_new ();

  g_file_copy_async (source, destination, G_FILE_COPY_NONE, G_PRIORITY_DEFAULT,
                     priv-&gt;copy_cancellable, NULL, NULL,
                     copy_finish_cb, user_data);

  g_object_unref (destination);
  g_object_unref (source);

  /* Update UI to show copy is in progress. */
  …
}

static void
copy_finish_cb (GObject      *source_object,
                GAsyncResult *result,
                gpointer      user_data)
{
  MyObjectPrivate *priv;
  GFile *source;  /* unowned */
  GError *error = NULL;

  source = G_FILE (source_object);
  priv = my_object_get_instance_private (MY_OBJECT (user_data));

  /* Handle completion of the operation. */
  g_file_copy_finish (source, result, &amp;error);

  if (error != NULL &amp;&amp;
      !g_error_matches (error, G_IO_ERROR, G_IO_ERROR_CANCELLED))
    {
      /* Should update the UI to signal failure.
       * Ignore failure due to cancellation. */
      g_warning ("Failed to copy file: %s", error-&gt;message);
    }

  g_clear_error (&amp;error);

  /* Clear the cancellable to signify the operation has finished. */
  g_clear_object (&amp;priv-&gt;copy_cancellable);

  /* Update UI to show copy as complete. */
  …
}

static void
cancel_button_clicked_cb (GtkButton *button,
                          gpointer   user_data)
{
  MyObjectPrivate *priv;
  GFile *source = NULL, *destination = NULL;  /* owned */

  priv = my_object_get_instance_private (MY_OBJECT (user_data));

  /* Operation in progress? No-op if @copy_cancellable is %NULL. */
  g_cancellable_cancel (priv-&gt;copy_cancellable);
}

static void
my_object_dispose (GObject *obj)
{
  MyObjectPrivate *priv;

  priv = my_object_get_instance_private (MY_OBJECT (obj));

  /* Cancel any ongoing copy operation.
   *
   * This ensures that if #MyObject is disposed part-way through a copy, the
   * callback doesn’t get invoked with an invalid #MyObject pointer. */
  g_cancellable_cancel (priv-&gt;copy_cancellable);

  /* Do other dispose calls here. */
  …

  /* Chain up. */
  G_OBJECT_CLASS (my_object_parent_class)-&gt;dispose (obj);
}</code>

        <p>
          For comparison, here is the same code implemented using the
          <em>synchronous</em> version of
          <link href="https://developer.gnome.org/gio/stable/GFile.html#g-file-copy"><code>g_file_copy()</code></link>.
          Note how the order of statements is almost identical. Cancellation
          cannot be supported here, as the UI is blocked from receiving ‘click’
          events on the cancellation button while the copy is ongoing, so
          <code>NULL</code> is passed to the <code>GCancellable</code>
          parameter. This is the main reason why this code should <em>not</em>
          be used in practice.
        </p>

        <code mime="text/x-csrc" style="invalid">
static void
copy_button_clicked_cb (GtkButton *button
                        gpointer   user_data)
{
  MyObjectPrivate *priv;
  GFile *source = NULL, *destination = NULL;  /* owned */

  priv = my_object_get_instance_private (MY_OBJECT (user_data));

  /* Build source and destination file paths. */
  source = g_file_new_for_path (/* some path generated from UI */);
  destination = g_file_new_for_path (/* some other path generated from UI */);

  g_file_copy (source, destination, G_FILE_COPY_NONE,
               NULL  /* cancellable */, NULL, NULL,
               &amp;error);

  g_object_unref (destination);
  g_object_unref (source);

  /* Handle completion of the operation. */
  if (error != NULL)
    {
      /* Should update the UI to signal failure.
       * Ignore failure due to cancellation. */
      g_warning ("Failed to copy file: %s", error-&gt;message);
    }

  g_clear_error (&amp;error);

  /* Update UI to show copy as complete. */
  …
}</code>
      </example>
    </section>

    <section id="series">
      <title>Operaciones en serie</title>

      <p>Una situación común es ejecutar múltiples operaciones asincrónicas en serie, cuando cada operación depende de que se complete la anterior.</p>

      <example>
        <p>En este ejemplo, la aplicación lee una dirección de socket desde un archivo, abre una conexión a esa dirección, lee un mensaje y luego termina.</p>

        <p>Los puntos clave en este ejemplo son:</p>
        <list>
          <item><p>Cada retorno de llamada es numerada consistentemente y están todas colocadas en orden en el archivo para que el código siga secuencialmente.</p></item>
          <item><p>Como en <link xref="#single-call"/>, un único <code>GCancellable</code> indica que la serie de operaciones está en curso. Al cancelarlo se aborta toda la secuencia.</p></item>
          <item><p>Como en <link xref="#single-call"/>, la operación pendiente se cancela si se elimina la instancia propietaria de <code>MyObject</code> para evitar que se llame a los retornos de función después con un puntero a <code>MyObject</code> no válido.</p></item>
        </list>

        <p>
          <link xref="#gtask"/> gives a version of this example wrapped in a
          <link href="https://developer.gnome.org/gio/stable/GTask.html"><code>GTask</code></link>
          for convenience.
        </p>

        <code mime="text/x-csrc" style="valid">
static void
connect_to_server_cb1 (GObject      *source_object,
                       GAsyncResult *result,
                       gpointer      user_data);
static void
connect_to_server_cb2 (GObject      *source_object,
                       GAsyncResult *result,
                       gpointer      user_data);
static void
connect_to_server_cb3 (GObject      *source_object,
                       GAsyncResult *result,
                       gpointer      user_data);

static void
connect_to_server (MyObject *self)
{
  MyObjectPrivate *priv;
  GFile *address_file = NULL;  /* owned */

  priv = my_object_get_instance_private (self);

  if (priv-&gt;connect_cancellable != NULL)
    {
      /* Already connecting. */
      return;
    }

  /* Set up a cancellable. */
  priv-&gt;connect_cancellable = g_cancellable_new ();

  /* Read the socket address. */
  address_file = build_address_file ();
  g_file_load_contents_async (address_file, priv-&gt;connect_cancellable,
                              connect_to_server_cb1, self);
  g_object_unref (address_file);
}

static void
connect_to_server_cb1 (GObject      *source_object,
                       GAsyncResult *result,
                       gpointer      user_data)
{
  MyObject *self;
  MyObjectPrivate *priv;
  GFile *address_file;  /* unowned */
  gchar *address = NULL;  /* owned */
  gsize address_size = 0;
  GInetAddress *inet_address = NULL;  /* owned */
  GInetSocketAddress *inet_socket_address = NULL;  /* owned */
  guint16 port = 123;
  GSocketClient *socket_client = NULL;  /* owned */
  GError *error = NULL;

  address_file = G_FILE (source_object);
  self = MY_OBJECT (user_data);
  priv = my_object_get_instance_private (self);

  /* Finish loading the address. */
  g_file_load_contents_finish (address_file, result, &amp;address,
                               &amp;address_size, NULL, &amp;error);

  if (error != NULL)
    {
      goto done;
    }

  /* Parse the address. */
  inet_address = g_inet_address_new_from_string (address);

  if (inet_address == NULL)
    {
      /* Error. */
      g_set_error (&amp;error, G_IO_ERROR, G_IO_ERROR_INVALID_ARGUMENT,
                   "Invalid address ‘%s’.", address);
      goto done;
    }

  inet_socket_address = g_inet_socket_address_new (inet_address, port);

  /* Connect to the given address. */
  socket_client = g_socket_client_new ();

  g_socket_client_connect_async (socket_client,
                                 G_SOCKET_CONNECTABLE (inet_socket_address),
                                 priv-&gt;connect_cancellable,
                                 connect_to_server_cb2,
                                 self);

done:
  if (error != NULL)
    {
      /* Stop the operation. */
      if (!g_error_matches (error, G_IO_ERROR, G_IO_ERROR_CANCELLED))
        {
          g_warning ("Failed to load server address: %s", error-&gt;message);
        }

      g_clear_object (&amp;priv-&gt;connect_cancellable);
      g_error_free (error);
    }

  g_free (address);
  g_clear_object (&amp;inet_address);
  g_clear_object (&amp;inet_socket_address);
  g_clear_object (&amp;socket_client);
}

static void
connect_to_server_cb2 (GObject      *source_object,
                       GAsyncResult *result,
                       gpointer      user_data)
{
  MyObject *self;
  MyObjectPrivate *priv;
  GSocketClient *socket_client;  /* unowned */
  GSocketConnection *connection = NULL;  /* owned */
  GInputStream *input_stream;  /* unowned */
  GError *error = NULL;

  socket_client = G_SOCKET_CLIENT (source_object);
  self = MY_OBJECT (user_data);
  priv = my_object_get_instance_private (self);

  /* Finish connecting to the socket. */
  connection = g_socket_client_connect_finish (socket_client, result,
                                               &amp;error);

  if (error != NULL)
    {
      goto done;
    }

  /* Store a reference to the connection so it is kept open while we read from
   * it: #GInputStream does not keep a reference to a #GIOStream which contains
   * it. */
  priv-&gt;connection = g_object_ref (connection);

  /* Read a message from the connection. This uses a single buffer stored in
   * #MyObject, meaning that only one connect_to_server() operation can run at
   * any time. The buffer could instead be allocated dynamically if this is a
   * problem. */
  input_stream = g_io_stream_get_input_stream (G_IO_STREAM (connection));

  g_input_stream_read_async (input_stream,
                             priv-&gt;message_buffer,
                             sizeof (priv-&gt;message_buffer),
                             G_PRIORITY_DEFAULT, priv-&gt;connect_cancellable,
                             connect_to_server_cb3, self);

done:
  if (error != NULL)
    {
      /* Stop the operation. */
      if (!g_error_matches (error, G_IO_ERROR, G_IO_ERROR_CANCELLED))
        {
          g_warning ("Failed to connect to server: %s", error-&gt;message);
        }

      g_clear_object (&amp;priv-&gt;connect_cancellable);
      g_clear_object (&amp;priv-&gt;connection);
      g_error_free (error);
    }

  g_clear_object (&amp;connection);
}

static void
connect_to_server_cb3 (GObject      *source_object,
                       GAsyncResult *result,
                       gpointer      user_data)
{
  MyObject *self;
  MyObjectPrivate *priv;
  GInputStream *input_stream;  /* unowned */
  gssize len = 0;
  GError *error = NULL;

  input_stream = G_INPUT_STREAM (source_object);
  self = MY_OBJECT (user_data);
  priv = my_object_get_instance_private (self);

  /* Finish reading from the socket. */
  len = g_input_stream_read_finish (input_stream, result, &amp;error);

  if (error != NULL)
    {
      goto done;
    }

  /* Handle the message. */
  g_assert_cmpint (len, &gt;=, 0);
  g_assert_cmpuint ((gsize) len, &lt;=, sizeof (priv-&gt;message_buffer));

  handle_received_message (self, priv-&gt;message_buffer, len, &amp;error);

  if (error != NULL)
    {
      goto done;
    }

done:
  /* Unconditionally mark the operation as finished.
   *
   * The streams should automatically close as this
   * last reference is dropped. */
  g_clear_object (&amp;priv-&gt;connect_cancellable);
  g_clear_object (&amp;priv-&gt;connection);

  if (error != NULL)
    {
      /* Warn about the error. */
      if (!g_error_matches (error, G_IO_ERROR, G_IO_ERROR_CANCELLED))
        {
          g_warning ("Failed to read from the server: %s", error-&gt;message);
        }

      g_error_free (error);
    }
}

static void
my_object_dispose (GObject *obj)
{
  MyObjectPrivate *priv;

  priv = my_object_get_instance_private (MY_OBJECT (obj));

  /* Cancel any ongoing connection operations.
   *
   * This ensures that if #MyObject is disposed part-way through the
   * connect_to_server() sequence of operations, the sequence gets cancelled and
   * doesn’t continue with an invalid #MyObject pointer. */
  g_cancellable_cancel (priv-&gt;connect_cancellable);

  /* Do other dispose calls here. */
  …

  /* Chain up. */
  G_OBJECT_CLASS (my_object_parent_class)-&gt;dispose (obj);
}</code>
      </example>
    </section>

    <section id="parallel">
      <title>Operaciones en paralelo</title>

      <p>Otra situación común es ejecutar múltiples operaciones asincrónicas en paralelo, considerando que la operación general se completa cuando todos sus componentes están completos.</p>

      <example>
        <p>En este ejemplo, la aplicación elimina varios archivos en paralelo.</p>

        <p>Los puntos clave en este ejemplo son:</p>
        <list>
          <item><p>
            The number of pending asynchronous operations (ones which have
            started but not yet finished) is tracked as
            <code>n_deletions_pending</code>. The <code>delete_files_cb()</code>
            callback only considers the entire operation complete once this
            reaches zero.
          </p></item>
          <item><p>
            <code>n_deletions_to_start</code> tracks deletion operations being
            started, in case
            <link href="https://developer.gnome.org/gio/stable/GFile.html#g-file-delete-async"><code>g_file_delete_async()</code></link>
            manages to use a fast path and complete synchronously (without
            blocking).
          </p></item>
          <item><p>
            As in <link xref="#single-call"/>, all pending deletions are
            cancelled if the owning <code>MyObject</code> instance is disposed,
            to prevent callbacks being called later with an invalid
            <code>MyObject</code> pointer.
          </p></item>
        </list>

        <code mime="text/x-csrc" style="valid">
static void
delete_files_cb (GObject      *source_object,
                 GAsyncResult *result,
                 gpointer      user_data);

static void
delete_files (MyObject *self,
              GPtrArray/*&lt;owned GFile*&gt;&gt;*/ *files)
{
  MyObjectPrivate *priv;
  GFile *address_file = NULL;  /* owned */

  priv = my_object_get_instance_private (self);

  /* Set up a cancellable if no operation is ongoing already. */
  if (priv-&gt;delete_cancellable == NULL)
    {
      priv-&gt;delete_cancellable = g_cancellable_new ();
      priv-&gt;n_deletions_pending = 0;
      priv-&gt;n_deletions_total = 0;
    }

  /* Update internal state, and temporarily set @n_deletions_to_start. This is
   * used in delete_files_cb() to avoid indicating the overall operation has
   * completed while deletions are still being started. This can happen if
   * g_file_delete_async() completes synchronously, for example if there’s a
   * non-blocking fast path for the given file system. */
  priv-&gt;n_deletions_pending += files-&gt;len;
  priv-&gt;n_deletions_total += files-&gt;len;
  priv-&gt;n_deletions_to_start = files-&gt;len;

  /* Update the UI to indicate the files are being deleted. */
  update_ui_to_show_progress (self,
                              priv-&gt;n_deletions_pending,
                              priv-&gt;n_deletions_total);

  /* Start all the deletion operations in parallel. They share the same
   * #GCancellable. */
  for (i = 0; i &lt; files-&gt;len; i++)
    {
      GFile *file = files-&gt;pdata[i];

      priv-&gt;n_deletions_to_start--;
      g_file_delete_async (file, G_PRIORITY_DEFAULT, priv-&gt;delete_cancellable,
                           delete_files_cb, self);
    }
}

static void
delete_files_cb (GObject      *source_object,
                 GAsyncResult *result,
                 gpointer      user_data)
{
  MyObject *self;
  MyObjectPrivate *priv;
  GFile *file;  /* unowned */
  GError *error = NULL;

  file = G_FILE (source_object);
  self = MY_OBJECT (user_data);
  priv = my_object_get_instance_private (self);

  /* Finish deleting the file. */
  g_file_delete_finish (file, result, &amp;error);

  if (error != NULL &amp;&amp;
      !g_error_matches (error, G_IO_ERROR, G_IO_ERROR_CANCELLED))
    {
      g_warning ("Error deleting file: %s", error-&gt;message);
    }

  g_clear_error (&amp;error);

  /* Update the internal state. */
  g_assert_cmpuint (priv-&gt;n_deletions_pending, &gt;, 0);
  priv-&gt;n_deletions_pending--;

  /* Update the UI to show progress. */
  update_ui_to_show_progress (self,
                              priv-&gt;n_deletions_pending,
                              priv-&gt;n_deletions_total);

  /* If all deletions have completed, and no more are being started,
   * update the UI to show completion. */
  if (priv-&gt;n_deletions_pending == 0 &amp;&amp; priv-&gt;n_deletions_to_start == 0)
    {
      update_ui_to_show_completion (self);

      /* Clear the operation state. */
      g_clear_object (&amp;priv-&gt;delete_cancellable);
      priv-&gt;n_deletions_total = 0;
    }
}

static void
my_object_dispose (GObject *obj)
{
  MyObjectPrivate *priv;

  priv = my_object_get_instance_private (MY_OBJECT (obj));

  /* Cancel any ongoing deletion operations.
   *
   * This ensures that if #MyObject is disposed part-way through the
   * delete_files() set of operations, the set gets cancelled and
   * doesn’t continue with an invalid #MyObject pointer. */
  g_cancellable_cancel (priv-&gt;delete_cancellable);

  /* Do other dispose calls here. */
  …

  /* Chain up. */
  G_OBJECT_CLASS (my_object_parent_class)-&gt;dispose (obj);
}</code>
      </example>
    </section>

    <section id="gtask">
      <title>Envoltorio con <code>GTask</code></title>

      <p>
        Often when an asynchronous operation (or set of operations) becomes more
        complex, it needs associated state. This is typically stored in a custom
        structure — but defining a new structure to store the standard callback,
        user data and cancellable tuple is laborious.
        <link href="https://developer.gnome.org/gio/stable/GTask.html"><code>GTask</code></link>
        eases this by providing a standardized way to wrap all three, plus extra
        custom ‘task data’.
      </p>

      <p>
        The use of a <code>GTask</code> can replace the use of a
        <link href="https://developer.gnome.org/gio/stable/GCancellable.html"><code>GCancellable</code></link>
        for indicating whether an operation is ongoing.
      </p>

      <example>
        <p>
          This example is functionally the same as <link xref="#series"/>, but
          refactored to use a <code>GTask</code> to wrap the sequence of
          operations.
        </p>

        <p>Los puntos clave en este ejemplo son:</p>
        <list>
          <item><p>
            State which was in <code>MyObjectPrivate</code> in
            <link xref="#series"/> is now in the
            <code>ConnectToServerData</code> closure, which is set as the ‘task
            data’ of the <code>GTask</code> representing the overall operation.
            This means it’s automatically freed after the operation returns.
          </p></item>
          <item><p>
            Furthermore, this means that manipulations of
            <code>MyObjectPrivate</code> state are limited to the start and end
            of the sequence of operations, so reusing the task in different
            situations becomes easier — for example, it is now a lot easier to
            support running multiple such tasks in parallel.
          </p></item>
          <item><p>
            As the <code>GTask</code> holds a reference to
            <code>MyObject</code>, it is impossible for the object to be
            disposed while the sequence of operations is ongoing, so the
            <code>my_object_dispose()</code> code has been removed. Instead, a
            <code>my_object_close()</code> method exists to allow any pending
            operations can be cancelled so <code>MyObject</code> can be disposed
            when desired.
          </p></item>
        </list>

        <code mime="text/x-csrc" style="valid">
static void
connect_to_server_cb1 (GObject      *source_object,
                       GAsyncResult *result,
                       gpointer      user_data);
static void
connect_to_server_cb2 (GObject      *source_object,
                       GAsyncResult *result,
                       gpointer      user_data);
static void
connect_to_server_cb3 (GObject      *source_object,
                       GAsyncResult *result,
                       gpointer      user_data);

typedef struct {
  GSocketConnection *connection;  /* nullable; owned */
  guint8 message_buffer[128];
} ConnectToServerData;

static void
connect_to_server_data_free (ConnectToServerData *data)
{
  g_clear_object (&amp;data-&gt;connection);
}

void
my_object_connect_to_server_async (MyObject            *self,
                                   GCancellable        *cancellable,
                                   GAsyncReadyCallback  callback,
                                   gpointer             user_data)
{
  MyObjectPrivate *priv;
  GTask *task = NULL;  /* owned */
  ConnectToServerData *data = NULL;  /* owned */
  GFile *address_file = NULL;  /* owned */

  g_return_if_fail (MY_IS_OBJECT (self));
  g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));

  priv = my_object_get_instance_private (self);

  if (priv-&gt;connect_task != NULL)
    {
      g_task_report_new_error (self, callback, user_data, NULL,
                               G_IO_ERROR, G_IO_ERROR_PENDING,
                               "Already connecting to the server.");
      return;
    }

  /* Set up a cancellable. */
  if (cancellable != NULL)
    {
      g_object_ref (cancellable);
    }
  else
    {
      cancellable = g_cancellable_new ();
    }

  /* Set up the task. */
  task = g_task_new (self, cancellable, callback, user_data);
  g_task_set_check_cancellable (task, FALSE);

  data = g_malloc0 (sizeof (ConnectToServerData));
  g_task_set_task_data (task, data,
                        (GDestroyNotify) connect_to_server_data_free);

  g_object_unref (cancellable);

  priv-&gt;connect_task = g_object_ref (task);

  /* Read the socket address. */
  address_file = build_address_file ();
  g_file_load_contents_async (address_file, g_task_get_cancellable (task),
                              connect_to_server_cb1, g_object_ref (task));
  g_object_unref (address_file);

  g_clear_object (&amp;task);
}

static void
connect_to_server_cb1 (GObject      *source_object,
                       GAsyncResult *result,
                       gpointer      user_data)
{
  MyObject *self;
  MyObjectPrivate *priv;
  GTask *task = NULL;  /* owned */
  GFile *address_file;  /* unowned */
  gchar *address = NULL;  /* owned */
  gsize address_size = 0;
  GInetAddress *inet_address = NULL;  /* owned */
  GInetSocketAddress *inet_socket_address = NULL;  /* owned */
  guint16 port = 123;
  GSocketClient *socket_client = NULL;  /* owned */
  GError *error = NULL;

  address_file = G_FILE (source_object);
  task = G_TASK (user_data);
  self = g_task_get_source_object (task);
  priv = my_object_get_instance_private (self);

  /* Finish loading the address. */
  g_file_load_contents_finish (address_file, result, &amp;address,
                               &amp;address_size, NULL, &amp;error);

  if (error != NULL)
    {
      goto done;
    }

  /* Parse the address. */
  inet_address = g_inet_address_new_from_string (address);

  if (inet_address == NULL)
    {
      /* Error. */
      g_set_error (&amp;error, G_IO_ERROR, G_IO_ERROR_INVALID_ARGUMENT,
                   "Invalid address ‘%s’.", address);
      goto done;
    }

  inet_socket_address = g_inet_socket_address_new (inet_address, port);

  /* Connect to the given address. */
  socket_client = g_socket_client_new ();

  g_socket_client_connect_async (socket_client,
                                 G_SOCKET_CONNECTABLE (inet_socket_address),
                                 g_task_get_cancellable (task),
                                 connect_to_server_cb2,
                                 g_object_ref (task));

done:
  if (error != NULL)
    {
      /* Stop the operation and propagate the error. */
      g_clear_object (&amp;priv-&gt;connect_task);
      g_task_return_error (task, error);
    }

  g_free (address);
  g_clear_object (&amp;inet_address);
  g_clear_object (&amp;inet_socket_address);
  g_clear_object (&amp;socket_client);
  g_clear_object (&amp;task);
}

static void
connect_to_server_cb2 (GObject      *source_object,
                       GAsyncResult *result,
                       gpointer      user_data)
{
  MyObject *self;
  MyObjectPrivate *priv;
  GTask *task = NULL;  /* owned */
  ConnectToServerData *data;  /* unowned */
  GSocketClient *socket_client;  /* unowned */
  GSocketConnection *connection = NULL;  /* owned */
  GInputStream *input_stream;  /* unowned */
  GError *error = NULL;

  socket_client = G_SOCKET_CLIENT (source_object);
  task = G_TASK (user_data);
  data = g_task_get_task_data (task);
  self = g_task_get_source_object (task);
  priv = my_object_get_instance_private (self);

  /* Finish connecting to the socket. */
  connection = g_socket_client_connect_finish (socket_client, result,
                                               &amp;error);

  if (error != NULL)
    {
      goto done;
    }

  /* Store a reference to the connection so it is kept open while we read from
   * it: #GInputStream does not keep a reference to a #GIOStream which contains
   * it. */
  data-&gt;connection = g_object_ref (connection);

  /* Read a message from the connection. As the buffer is allocated as part of
   * the per-task @data, multiple tasks can run concurrently. */
  input_stream = g_io_stream_get_input_stream (G_IO_STREAM (connection));

  g_input_stream_read_async (input_stream,
                             data-&gt;message_buffer,
                             sizeof (data-&gt;message_buffer),
                             G_PRIORITY_DEFAULT, g_task_get_cancellable (task),
                             connect_to_server_cb3, g_object_ref (task));

done:
  if (error != NULL)
    {
      /* Stop the operation and propagate the error. */
      g_clear_object (&amp;priv-&gt;connect_task);
      g_task_return_error (task, error);
    }

  g_clear_object (&amp;connection);
  g_clear_object (&amp;task);
}

static void
connect_to_server_cb3 (GObject      *source_object,
                       GAsyncResult *result,
                       gpointer      user_data)
{
  MyObject *self;
  MyObjectPrivate *priv;
  GTask *task = NULL;  /* owned */
  ConnectToServerData *data;  /* unowned */
  GInputStream *input_stream;  /* unowned */
  gssize len = 0;
  GError *error = NULL;

  input_stream = G_INPUT_STREAM (source_object);
  task = G_TASK (user_data);
  data = g_task_get_task_data (task);
  self = g_task_get_source_object (task);
  priv = my_object_get_instance_private (self);

  /* Finish reading from the socket. */
  len = g_input_stream_read_finish (input_stream, result, &amp;error);

  if (error != NULL)
    {
      goto done;
    }

  /* Handle the message. */
  g_assert_cmpint (len, &gt;=, 0);
  g_assert_cmpuint ((gsize) len, &lt;=, sizeof (data-&gt;message_buffer));

  handle_received_message (self, data-&gt;message_buffer, len, &amp;error);

  if (error != NULL)
    {
      goto done;
    }

  /* Success! */
  g_task_return_boolean (task, TRUE);

done:
  /* Unconditionally mark the operation as finished.
   *
   * The streams should automatically close as this
   * last reference is dropped. */
  g_clear_object (&amp;priv-&gt;connect_task);

  if (error != NULL)
    {
      /* Stop the operation and propagate the error. */
      g_task_return_error (task, error);
    }

  g_clear_object (&amp;task);
}

void
my_object_connect_to_server_finish (MyObject      *self,
                                    GAsyncResult  *result,
                                    GError       **error)
{
  g_return_if_fail (MY_IS_OBJECT (self));
  g_return_if_fail (g_task_is_valid (result, self));
  g_return_if_fail (error == NULL || *error == NULL);

  g_task_propagate_boolean (G_TASK (result), error);
}

void
my_object_close (MyObject *self)
{
  MyObjectPrivate *priv;

  g_return_if_fail (MY_IS_OBJECT (self));

  priv = my_object_get_instance_private (self);

  if (priv-&gt;connect_task != NULL)
    {
      GCancellable *cancellable = g_task_get_cancellable (priv-&gt;connect_task);
      g_cancellable_cancel (cancellable);
    }
}</code>
      </example>
    </section>
  </section>
</page>