<?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="de">

  <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>Verwendung von asynchronen Methoden im Glib-Stil in verschiedenen Situationen</desc>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Mario Blättermann</mal:name>
      <mal:email>mario.blaettermann@gmail.com</mal:email>
      <mal:years>2016, 2018</mal:years>
    </mal:credit>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Christian Kirbach</mal:name>
      <mal:email>christian.kirbach@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>Stefan Melmuk</mal:name>
      <mal:email>stefan.melmuk@gmail.com</mal:email>
      <mal:years>2018</mal:years>
    </mal:credit>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Tim Sabsch</mal:name>
      <mal:email>tim@sabsch.com</mal:email>
      <mal:years>2021</mal:years>
    </mal:credit>
  </info>

  <title>Asynchrone Programmierung</title>

  <synopsis>
    <title>Zusammenfassung</title>

    <list>
      <item><p>Bevorzugen Sie asynchrone gegenüber synchronen Aufrufen oder der expliziten Verwendung von Threads (<link xref="#concepts"/>)</p></item>
      <item><p>Lernen und wenden Sie die GLib-Muster zur Deklaration asynchroner APIs an (<link xref="#api-pattern"/>)</p></item>
      <item><p>Platzieren Sie Callbacks asynchroner Funktionen in der richtigen Reihenfolge innerhalb der Datei, damit dem Kontrollfluss leicht gefolgt werden kann (<link xref="#single-call"/>)</p></item>
      <item><p>Verwenden Sie ein <link href="https://developer.gnome.org/gio/stable/GTask.html"><code>GTask</code></link> oder <link href="https://developer.gnome.org/gio/stable/GCancellable.html"><code>GCancellable</code></link>, um anzugeben, ob eine Operation gerade läuft (<link xref="#single-call"/>, <link xref="#gtask"/>)</p></item>
      <item><p>Wenn Sie Operationen parallel laufen lassen, sollten Sie verfolgen, wie viele Operationen noch gestartet werden müssen und wieviele noch nicht beendet sind — die übergeordnete Operation ist abgeschlossen, sobald beide Zähler null sind (<link xref="#parallel"/>)</p></item>
      <item><p>Separieren Sie den Status von Operationen in »Task-Daten«-Strukturen für <link href="https://developer.gnome.org/gio/stable/GTask.html"><code>GTask</code>s</link>, wodurch Operationen einfacher wiederverwendet werden können, ohne dass Änderungen auf der globalen Statusbehandlung nötig werden (<link xref="#gtask"/>)</p></item>
      <item><p>Überlegen Sie sich, wie sich asynchrone Methoden einer Objektinstanz verhalten sollen, wenn die Instanz finalisiert wird (<link xref="#lifetimes"/>)</p></item>
    </list>
  </synopsis>

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

    <p>GLib unterstützt <em>asynchrone</em> Programme, bei denen lang-laufende Operationen gestartet werden können, die dann »im Hintergrund« laufen und einen Callback aufrufen, sobald sie geendet haben und die Ergebnisse verfügbar sind. Dies steht im unmittelbaren Kontrast zu <em>synchronen</em> lang-laufenden Operationen, bei denen ein einzelner Funktionsaufruf den gesamten Programmfluss blockiert, bis er geendet hat.</p>

    <p>Wie in <link xref="main-contexts"/> und <link xref="threading#when-to-use-threading"/> besprochen, sollten asynchrone Operationen gegenüber synchronen Operationen und explizitem Threading bevorzugt werden. Sie blocken nicht den Hauptkontext wie synchrone Operationen und sind einfacher zu verwenden als Threads. Ebenfalls haben sie oft einen geringeren Leistungsverlust als einen Thread zu erzeugen und Arbeit an ihn zu senden.</p>
  </section>

  <section id="api-pattern">
    <title>API-Muster</title>

    <p>Asynchrone Aufrufe folgen in GLib-Code einem Standardmuster. Für eine Operation namens <code>load_data</code> in der Klasse <code>File</code> im <code>Foo</code>-Namensraum gibt es:</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>Die Parameter<code>…</code> für <code>foo_file_load_data_async()</code> sind die operationsspezifischen Parameter — in diesem Fall vermutlich die Größe eines Puffers, in den geladen werden soll. Äquivalent dazu handelt es sich bei <code>foo_file_load_data_finish()</code> um die operationsspezifischen Rückgabewerte — in diesem Fall vielleicht ein Ort, in dem ein Content-Typ-String zurückgegeben wird.</p>

    <p>Wenn <code>foo_file_load_data_async()</code> aufgerufen wird, plant es die Laden-Operation im Hintergrund ein (zum Beispiel als ein neuer Dateideskriptor auf dem <link xref="main-contexts"><code>GMainContext</code></link> oder als Arbeits-Thread) und kehrt nicht-blockend zurück.</p>

    <p>Sobald die Operation beendet ist, wird der <code>callback</code> im selben <code>GMainContext</code> wie der ursprüngliche asynchrone Aufruf ausgeführt. Der Callback wird <em>genau</em> einmal aufgerufen, egal ob die Operation erfolgreich war oder fehlgeschlagen ist.</p>

    <p>Aus dem Callback heraus kann <code>foo_file_load_data_finish()</code> aufgerufen werden, um Rückgabewerte und Fehlerdetails zu erhalten. Dabei wird die <link href="https://developer.gnome.org/gio/stable/GAsyncResult.html"><code>GAsyncResult</code></link>-Instanz übergeben, die dem Callback übergeben wurde.</p>
  </section>

  <section id="lifetimes">
    <title>Lebensdauer von Operationen</title>

    <p>Beim Schreiben von asynchronen Operationen ist es üblich, sie als Klassenmethoden zu definieren. Sie sollten hierbei überlegen, wie laufende Operationen einer Klasseninstanz damit umgehen sollen, wenn die Instanz finalisiert wird. Es gibt zwei Ansätze:</p>

    <terms>
      <item>
        <title>Stark</title>
        <p>Die laufende Operation erhält eine Referenz der Klasseninstanz, wodurch die Instanz bis zum Ende der Operation am Leben bleibt. Die Klasse sollte dann eine Methode wie »close« oder »cancel« enthalten, die von anderen Klassen verwendet werden kann, um einen Abbruch der Operation zu erzwingen und damit die Instanz zu finalisieren.</p>
      </item>

      <item>
        <title>Schwach</title>
        <p>Die laufende Operation erhält <em>keine</em> Referenz der Klasseninstanz. Die Klasse bricht die Operation in ihrer Dispose-Funktion (mittels <link href="https://developer.gnome.org/gio/stable/GCancellable.html#g-cancellable-cancel"><code>g_cancellable_cancel()</code></link>) ab.</p>
      </item>
    </terms>

    <p>Welcher Ansatz verwendet wird, hängt vom Design der Klasse ab. Eine Klasse, die eine bestimmte Operation verpackt (vielleicht etwa eine <code>MyFileTransfer</code>-Klasse) könnte den <em style="strong">schwachen</em> Ansatz verwenden. Eine Klasse hingegen, die mehrere Netzwerkverbindungen mit asynchronen Operationen verwaltet, könnte den <em style="strong">starken</em> Ansatz verwenden. Aufgrund eingehender Netzwerkverbindungen könnte sie nicht die vollständige Kontrolle über die asynchronen Aufrufe besitzen. In diesem Fall wäre der schwache Ansatz nicht angebracht, da man versehentlich eine neue Netzwerkverbindung verlieren könnte, wenn man eine Referenz des Objekts freigibt.</p>
  </section>

  <section id="async-examples">
    <title>Beispiele für die Verwendung asynchroner Funktionen</title>

    <p>Häufig werden mehrere asynchrone Aufrufe benötigt, um eine Operation durchzuführen. Um etwa den Inhalt einer Datei zu lesen, muss man erst die Datei öffnen, dann einige Lese-Befehle ausführen und anschließend die Datei wieder schließen. Ein anderes Beispiel wäre das parallele Öffnen mehrerer Netwerk-Sockets und anschließende Warten, bis alle geöffnet sind, bevor man weiterarbeiten kann. Einige Beispiele für solche Situationen sind im Folgenden aufgeführt.</p>

    <section id="single-call">
      <title>Einzelne Operation</title>

      <p>Ein einzelner asynchroner Aufruf erfordert zwei Funktionen: eine zum Starten und eine zum Beenden der Operation. Die Herausforderung von asynchronen Aufrufen in C liegt darin, den Status in der Zeit zwischen den beiden Funktionen richtig zu speichern, und Statusänderungen zu behandeln. Das Abbrechen einer laufenden asynchronen Operation ist zum Beispiel eine Statusänderung; wird sie nicht sorgfältig behandelt, könnten Änderungen in der Benutzeroberfläche, die eigentlich durch den Abbruch der Operation entstanden sind, durch den Callback anschließend wieder rückgängig gemacht werden.</p>

      <example>
        <p>Dieses Beispiel demonstriert das Kopieren einer Datei von einem Ort im Dateisystem an einen anderen. Die hier demonstrierten Schlüsselprinzipien sind:</p>
        <list>
          <item><p>Platzieren der Funktionen <code>copy_button_clicked_cb()</code> (Start) und <code>copy_finish_cb()</code> (Beenden) in dieser Reihenfolge durch Verwendung eines Funktionskopfes (»forward declaration«) für <code>copy_finish_cb()</code>. Dadurch folgt der Kontrollfluss linear den Zeilen der Datei, anstatt erst zum Ende von <code>copy_button_clicked_cb()</code> zu gelangen und anschließend wieder irgendwohin in die Datei zu springen, um in <code>copy_finish_cb()</code> weiterzumachen.</p></item>
          <item><p>Verwendung einer <link href="https://developer.gnome.org/gio/stable/GCancellable.html"><code>GCancellable</code></link>, um den Abbruch der Operation nach deren Start zu erlauben. Der Code in <code>cancel_button_clicked_cb()</code> ist sehr einfach: da der Callback von <code>copy_finish_cb()</code> <em>garantiert</em> aufgerufen wird, sobald die Operation geendet hat (auch vorzeitig durch einen Abbruch), können alle Status- und Benutzeroberflächen-Änderungen hier statt in <code>cancel_button_clicked_cb()</code> behandelt werden.</p></item>
          <item><p>Eine Operation läuft genau so lange, wie <code>MyObjectPrivate.copy_cancellable</code> nicht <code>NULL</code> ist, weshalb man laufende Operationen leicht verfolgen kann. Beachten Sie, dass daher nicht mehrere Kopiervorgänge gleichzeitig per <code>copy_button_clicked_cb()</code> gestartet werden können. Ein <code>GCancellable</code> kann nicht so einfach für mehrere Operationen wie diese verwendet werden.</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>Zum Vergleich ist hier der gleiche Code als <em>synchrone</em> Version von <link href="https://developer.gnome.org/gio/stable/GFile.html#g-file-copy"><code>g_file_copy()</code></link> implementiert. Wie Sie sehen, ist die Reihenfolge der Statements fast identisch. Ein Abbruch kann nicht unterstützt werden, da die Benutzeroberfläche blockiert ist und daher keine »Klick«-Events auf dem Abbruchknopf empfangen kann, während der Kopiervorgang läuft. Deshalb wurde dem <code>GCancellable</code>-Parameter der Wert <code>NULL</code> übergeben. Dies ist der Hauptgrund, weshalb dieser Code <em>nicht</em> verwendet werden sollte.</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>Operationen in Serie</title>

      <p>Eine typische Situation besteht darin, mehrere asynchrone Operationen hintereinander auszuführen, wobei jede Operation von der Beendigung der vorangegangenen abhängt.</p>

      <example>
        <p>In diesem Beispiel liest die Anwendung eine Socketadresse aus einer Datei aus, öffnet eine Verbindung zu dieser Adresse, liest eine Nachricht und endet dann.</p>

        <p>Die Hauptpunkte in diesem Beispiel sind:</p>
        <list>
          <item><p>Jeder Callback ist durchgängig nummeriert und in der richtigen Reihenfolge in der Datei platziert, sodass der Code sequentiell durchläuft.</p></item>
          <item><p>Wie in <link xref="#single-call"/> weist ein einzelnes <code>GCancellable</code> darauf hin, dass die Serie an Operationen gerade läuft. Ein Abbruch beendet die gesamte Serie.</p></item>
          <item><p>Wie in <link xref="#single-call"/> wird eine ausstehende Operation abgebrochen, wenn die <code>MyObject</code>-Instanz, zu dem die Operation gehört, entsorgt wird. Dadurch wird vermieden, dass Callbacks später mit einem ungültigen <code>MyObject</code>-Zeiger aufgerufen werden.</p></item>
        </list>

        <p><link xref="#gtask"/> zeigt eine Version dieses Beispiels, in dem es in einem <link href="https://developer.gnome.org/gio/stable/GTask.html"><code>GTask</code></link> eingebettet ist.</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>Parallele Operationen</title>

      <p>Eine andere typische Situation besteht darin, mehrere asynchrone Operationen gleichzeitig zu starten, wobei der Vorgang insgesamt als abgeschlossen gilt, wenn alle Bestandteile geendet haben.</p>

      <example>
        <p>In diesem Beispiel entfernt die Anwendung mehrere Dateien parallel.</p>

        <p>Die Hauptpunkte in diesem Beispiel sind:</p>
        <list>
          <item><p>Die Anzahl der laufenden asynchronen Operationen (Operationen, die gestartet aber noch nicht beendet sind) wird in <code>n_deletions_pending</code> verfolgt. Der Callback <code>delete_files_cb()</code> betrachtet die gesamte Operation erst als abgeschlossen, sobald diese Variable null erreicht hat.</p></item>
          <item><p><code>n_deletions_to_start</code> enthält die Anzahl der gestarteten Löschen-Operationen für den Fall, dass <link href="https://developer.gnome.org/gio/stable/GFile.html#g-file-delete-async"><code>g_file_delete_async()</code></link> einen Fast Path verwendet und synchron endet (nicht-blockend).</p></item>
          <item><p>Wie in <link xref="#single-call"/> werden ausstehende Operationen abgebrochen, wenn die <code>MyObject</code>-Instanz, zu dem die Operationen gehören, entsorgt wird. Dadurch wird vermieden, dass Callbacks später mit einem ungültigen <code>MyObject</code>-Zeiger aufgerufen werden.</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>In einen <code>GTask</code> einbetten</title>

      <p>Wenn eine asynchrone Operation (oder mehrere) komplexer wird, benötigt sie einen zugeordneten Status. Dieser ist für gewöhnlich in einer selbst geschriebenen Struktur hinterlegt. So eine Struktur zum Speichern des Standard-Callbacks, der Benutzerdaten sowie der Abbruchfunktion zu definieren erfordert aber eine Menge Arbeit. Der <link href="https://developer.gnome.org/gio/stable/GTask.html"><code>GTask</code></link> hilft dabei, indem er eine Struktur zum Einbetten dieser drei Teile sowie einige zusätzliche »Task-Daten« vorgibt.</p>

      <p>Die Nutzung eines <code>GTask</code>s ersetzt die Verwendung eines <link href="https://developer.gnome.org/gio/stable/GCancellable.html"><code>GCancellable</code></link> um anzugeben, ob eine Operation gerade läuft.</p>

      <example>
        <p>Dieses Beispiel ist inhaltlich gleich zu dem in <link xref="#series"/>, verwendet aber einen <code>GTask</code>, um die Serie an Operationen einzubetten.</p>

        <p>Die Hauptpunkte in diesem Beispiel sind:</p>
        <list>
          <item><p>Der Status, der in <link xref="#series"/> in <code>MyObjectPrivate</code> gespeichert war, befindet sich hier im Funktionsabschluss (»Closure«) <code>ConnectToServerData</code>, der dem <code>GTask</code> als »Task-Daten« übergeben wird und die gesamte Operation repräsentiert. Das bedeutet, dass er automatisch freigegeben wird, sobald die Operation beendet ist.</p></item>
          <item><p>Weiterhin sind Statusänderungen von <code>MyObjectPrivate</code> auf den Beginn und das Ende der Operationen-Sequenz beschränkt. Daher ist es viel einfacher, den Task in verschiedenen Situationen wiederzuverwenden. Beispielsweise ist es viel einfacher, mehrere Operationen gleichzeitig laufen zu lassen.</p></item>
          <item><p>Da der <code>GTask</code> eine Referenz auf <code>MyObject</code> besitzt, kann das Objekt unmöglich entsorgt werden, während die Serie an Operationen gerade läuft. <code>my_object_dispose()</code> wurde daher entfernt. Stattdessen gibt es nun die Methode <code>my_object_close()</code>, mit der ausstehende Operationen abgebrochen werden können, sodass das <code>MyObject</code> auf Wunsch entsorgt werden kann.</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>