Philip Withnall
philip.withnall@collabora.co.uk 2015

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

Als besondere Ausnahme gewähren die Inhaber des Urheberrechts die Erlaubnis, den Beispiel-Code in diesem Dokument ohne Einschränkungen unter den Bedingungen Ihrer Wahl zu kopieren, zu verändern und weiterzugeben.

Verwendung von asynchronen Methoden im Glib-Stil in verschiedenen Situationen
Mario Blättermann
mario.blaettermann@gmail.com 2016, 2018
Christian Kirbach
christian.kirbach@gmail.com 2016, 2020
Stefan Melmuk
stefan.melmuk@gmail.com 2018
Tim Sabsch
tim@sabsch.com 2021

# Asynchrone Programmierung

#

        Zusammenfassung

          Bevorzugen Sie asynchrone gegenüber synchronen Aufrufen oder der expliziten Verwendung von Threads ()
          Lernen und wenden Sie die GLib-Muster zur Deklaration asynchroner APIs an ()
          Platzieren Sie Callbacks asynchroner Funktionen in der richtigen Reihenfolge innerhalb der Datei, damit dem Kontrollfluss leicht gefolgt werden kann ()
          Verwenden Sie ein GTask oder GCancellable, um anzugeben, ob eine Operation gerade läuft (, )
          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 ()
          Separieren Sie den Status von Operationen in »Task-Daten«-Strukturen für GTasks, wodurch Operationen einfacher wiederverwendet werden können, ohne dass Änderungen auf der globalen Statusbehandlung nötig werden ()
          Überlegen Sie sich, wie sich asynchrone Methoden einer Objektinstanz verhalten sollen, wenn die Instanz finalisiert wird ()

# Konzepte

GLib unterstützt asynchrone 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 synchronen lang-laufenden Operationen, bei denen ein einzelner Funktionsaufruf den gesamten Programmfluss blockiert, bis er geendet hat.

Wie in und 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.

# API-Muster

Asynchrone Aufrufe folgen in GLib-Code einem Standardmuster. Für eine Operation namens `load_data` in der Klasse `File` im `Foo`-Namensraum gibt es:

foo_file_load_data_async (FooFile *self, …, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data)
foo_file_load_data_finish (FooFile *self, GAsyncResult *result, …, GError **error)

Die Parameter`…` für `foo_file_load_data_async()` sind die operationsspezifischen Parameter — in diesem Fall vermutlich die Größe eines Puffers, in den geladen werden soll. Äquivalent dazu handelt es sich bei `foo_file_load_data_finish()` um die operationsspezifischen Rückgabewerte — in diesem Fall vielleicht ein Ort, in dem ein Content-Typ-String zurückgegeben wird.

Wenn `foo_file_load_data_async()` aufgerufen wird, plant es die Laden-Operation im Hintergrund ein (zum Beispiel als ein neuer Dateideskriptor auf dem `GMainContext` oder als Arbeits-Thread) und kehrt nicht-blockend zurück.

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

Aus dem Callback heraus kann `foo_file_load_data_finish()` aufgerufen werden, um Rückgabewerte und Fehlerdetails zu erhalten. Dabei wird die `GAsyncResult`-Instanz übergeben, die dem Callback übergeben wurde.

# Lebensdauer von Operationen

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:

## Stark

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.

## Schwach

Die laufende Operation erhält keine Referenz der Klasseninstanz. Die Klasse bricht die Operation in ihrer Dispose-Funktion (mittels `g_cancellable_cancel()`) ab.

Welcher Ansatz verwendet wird, hängt vom Design der Klasse ab. Eine Klasse, die eine bestimmte Operation verpackt (vielleicht etwa eine `MyFileTransfer`-Klasse) könnte den schwachen Ansatz verwenden. Eine Klasse hingegen, die mehrere Netzwerkverbindungen mit asynchronen Operationen verwaltet, könnte den starken 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.

# Beispiele für die Verwendung asynchroner Funktionen

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.

## Einzelne Operation

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.

Dieses Beispiel demonstriert das Kopieren einer Datei von einem Ort im Dateisystem an einen anderen. Die hier demonstrierten Schlüsselprinzipien sind:

Platzieren der Funktionen `copy_button_clicked_cb()` (Start) und `copy_finish_cb()` (Beenden) in dieser Reihenfolge durch Verwendung eines Funktionskopfes (»forward declaration«) für `copy_finish_cb()`. Dadurch folgt der Kontrollfluss linear den Zeilen der Datei, anstatt erst zum Ende von `copy_button_clicked_cb()` zu gelangen und anschließend wieder irgendwohin in die Datei zu springen, um in `copy_finish_cb()` weiterzumachen.

Verwendung einer `GCancellable`, um den Abbruch der Operation nach deren Start zu erlauben. Der Code in `cancel_button_clicked_cb()` ist sehr einfach: da der Callback von `copy_finish_cb()` garantiert aufgerufen wird, sobald die Operation geendet hat (auch vorzeitig durch einen Abbruch), können alle Status- und Benutzeroberflächen-Änderungen hier statt in `cancel_button_clicked_cb()` behandelt werden.

Eine Operation läuft genau so lange, wie `MyObjectPrivate.copy_cancellable` nicht `NULL` ist, weshalb man laufende Operationen leicht verfolgen kann. Beachten Sie, dass daher nicht mehrere Kopiervorgänge gleichzeitig per `copy_button_clicked_cb()` gestartet werden können. Ein `GCancellable` kann nicht so einfach für mehrere Operationen wie diese verwendet werden.

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->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->copy_cancellable = g_cancellable_new ();

g_file_copy_async (source, destination, G_FILE_COPY_NONE, G_PRIORITY_DEFAULT, priv->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, &error);

if (error != NULL && !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->message); }

g_clear_error (&error);

/* Clear the cancellable to signify the operation has finished. */ g_clear_object (&priv->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->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->copy_cancellable);

/* Do other dispose calls here. */ …

/* Chain up. */ G_OBJECT_CLASS (my_object_parent_class)->dispose (obj); }

Zum Vergleich ist hier der gleiche Code als synchrone Version von `g_file_copy()` 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 `GCancellable`-Parameter der Wert `NULL` übergeben. Dies ist der Hauptgrund, weshalb dieser Code nicht verwendet werden sollte.

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, &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->message); }

g_clear_error (&error);

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

## Operationen in Serie

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

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

Die Hauptpunkte in diesem Beispiel sind:

Jeder Callback ist durchgängig nummeriert und in der richtigen Reihenfolge in der Datei platziert, sodass der Code sequentiell durchläuft.

Wie in weist ein einzelnes `GCancellable` darauf hin, dass die Serie an Operationen gerade läuft. Ein Abbruch beendet die gesamte Serie.

Wie in wird eine ausstehende Operation abgebrochen, wenn die `MyObject`-Instanz, zu dem die Operation gehört, entsorgt wird. Dadurch wird vermieden, dass Callbacks später mit einem ungültigen `MyObject`-Zeiger aufgerufen werden.

zeigt eine Version dieses Beispiels, in dem es in einem `GTask` eingebettet ist.

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->connect_cancellable != NULL) { /* Already connecting. */ return; }

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

/* Read the socket address. */ address_file = build_address_file (); g_file_load_contents_async (address_file, priv->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, &address, &address_size, NULL, &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 (&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->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->message); }

g_clear_object (&priv->connect_cancellable); g_error_free (error); }

g_free (address); g_clear_object (&inet_address); g_clear_object (&inet_socket_address); g_clear_object (&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, &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->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->message_buffer, sizeof (priv->message_buffer), G_PRIORITY_DEFAULT, priv->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->message); }

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

g_clear_object (&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, &error);

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

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

handle_received_message (self, priv->message_buffer, len, &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 (&priv->connect_cancellable); g_clear_object (&priv->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->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->connect_cancellable);

/* Do other dispose calls here. */ …

/* Chain up. */ G_OBJECT_CLASS (my_object_parent_class)->dispose (obj); }

## Parallele Operationen

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

In diesem Beispiel entfernt die Anwendung mehrere Dateien parallel.

Die Hauptpunkte in diesem Beispiel sind:

Die Anzahl der laufenden asynchronen Operationen (Operationen, die gestartet aber noch nicht beendet sind) wird in `n_deletions_pending` verfolgt. Der Callback `delete_files_cb()` betrachtet die gesamte Operation erst als abgeschlossen, sobald diese Variable null erreicht hat.

`n_deletions_to_start` enthält die Anzahl der gestarteten Löschen-Operationen für den Fall, dass `g_file_delete_async()` einen Fast Path verwendet und synchron endet (nicht-blockend).

Wie in werden ausstehende Operationen abgebrochen, wenn die `MyObject`-Instanz, zu dem die Operationen gehören, entsorgt wird. Dadurch wird vermieden, dass Callbacks später mit einem ungültigen `MyObject`-Zeiger aufgerufen werden.

static void delete_files_cb (GObject *source_object, GAsyncResult *result, gpointer user_data);

static void delete_files (MyObject *self, GPtrArray/*<owned GFile*>>*/ *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->delete_cancellable == NULL) { priv->delete_cancellable = g_cancellable_new (); priv->n_deletions_pending = 0; priv->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->n_deletions_pending += files->len; priv->n_deletions_total += files->len; priv->n_deletions_to_start = files->len;

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

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

priv->n_deletions_to_start--; g_file_delete_async (file, G_PRIORITY_DEFAULT, priv->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, &error);

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

g_clear_error (&error);

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

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

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

/* Clear the operation state. */ g_clear_object (&priv->delete_cancellable); priv->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->delete_cancellable);

/* Do other dispose calls here. */ …

/* Chain up. */ G_OBJECT_CLASS (my_object_parent_class)->dispose (obj); }

## In einen `GTask` einbetten

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 `GTask` hilft dabei, indem er eine Struktur zum Einbetten dieser drei Teile sowie einige zusätzliche »Task-Daten« vorgibt.

Die Nutzung eines `GTask`s ersetzt die Verwendung eines `GCancellable` um anzugeben, ob eine Operation gerade läuft.

Dieses Beispiel ist inhaltlich gleich zu dem in , verwendet aber einen `GTask`, um die Serie an Operationen einzubetten.

Die Hauptpunkte in diesem Beispiel sind:

Der Status, der in in `MyObjectPrivate` gespeichert war, befindet sich hier im Funktionsabschluss (»Closure«) `ConnectToServerData`, der dem `GTask` als »Task-Daten« übergeben wird und die gesamte Operation repräsentiert. Das bedeutet, dass er automatisch freigegeben wird, sobald die Operation beendet ist.

Weiterhin sind Statusänderungen von `MyObjectPrivate` 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.

Da der `GTask` eine Referenz auf `MyObject` besitzt, kann das Objekt unmöglich entsorgt werden, während die Serie an Operationen gerade läuft. `my_object_dispose()` wurde daher entfernt. Stattdessen gibt es nun die Methode `my_object_close()`, mit der ausstehende Operationen abgebrochen werden können, sodass das `MyObject` auf Wunsch entsorgt werden kann.

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 (&data->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->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->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 (&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, &address, &address_size, NULL, &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 (&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 (&priv->connect_task); g_task_return_error (task, error); }

g_free (address); g_clear_object (&inet_address); g_clear_object (&inet_socket_address); g_clear_object (&socket_client); g_clear_object (&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, &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->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->message_buffer, sizeof (data->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 (&priv->connect_task); g_task_return_error (task, error); }

g_clear_object (&connection); g_clear_object (&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, &error);

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

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

handle_received_message (self, data->message_buffer, len, &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 (&priv->connect_task);

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

g_clear_object (&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->connect_task != NULL) { GCancellable *cancellable = g_task_get_cancellable (priv->connect_task); g_cancellable_cancel (cancellable); } }