[gnome-software: 20/38] docs: Make refresh asynchronous

[Philip Withnall <pwithnall src gnome org>]

commit 250d8fa5627c406a7f54bfeb9621c0902b75fb1c
Author: Philip Withnall <pwithnall endlessos org>
Date:   Thu Jan 27 18:16:52 2022 +0000

    docs: Make refresh asynchronous
    
    Signed-off-by: Philip Withnall <pwithnall endlessos org>
    
    Helps: #1472

 doc/api/gnome-software-docs.xml | 84 ++++++++++++++++++++++++++++-------------
 1 file changed, 58 insertions(+), 26 deletions(-)
---
diff --git a/doc/api/gnome-software-docs.xml b/doc/api/gnome-software-docs.xml
index e20808f3f..58e39c268 100644
--- a/doc/api/gnome-software-docs.xml
+++ b/doc/api/gnome-software-docs.xml
@@ -352,7 +352,7 @@ gs_plugin_custom_list_installed_apps_finish (GsPlugin      *plugin,
         <title>Downloading Metadata and Updates</title>
 
         <para>
-          The plugin loader supports a <code>gs_plugin_refresh()</code> vfunc that
+          The plugin loader supports a <code>refresh_metadata_async()</code> vfunc that
           is called in various situations.
           To ensure plugins have the minimum required metadata on disk it is
           called at startup, but with a cache age of <emphasis>infinite</emphasis>.
@@ -360,7 +360,7 @@ gs_plugin_custom_list_installed_apps_finish (GsPlugin      *plugin,
           <emphasis role="strong">any</emphasis> data exists no matter what the age.
         </para>
         <para>
-          Usually once per hour, we'll call <code>gs_plugin_refresh()</code> but
+          Usually once per hour, we'll call <code>refresh_metadata_async()</code> but
           with the correct cache age set (typically a little over 24 hours) which
           allows the plugin to download new metadata or payload files from remote
           servers.
@@ -384,7 +384,7 @@ gs_plugin_custom_list_installed_apps_finish (GsPlugin      *plugin,
           not doing the deploy step) so that the applications can be updated live
           in the details panel without having to wait for the download to complete.
           In a similar way, the fwupd plugin downloads the tiny LVFS metadata with
-          <code>gs_plugin_refresh()</code> and then downloads the large firmware
+          <code>refresh_metadata_async()</code> and then downloads the large firmware
           files themselves when <code>gs_plugin_download_app()</code> or
           <code>gs_plugin_download_app()</code> is called.
         </para>
@@ -401,7 +401,7 @@ gs_plugin_custom_list_installed_apps_finish (GsPlugin      *plugin,
         <para>
           Note, if the downloading fails it's okay to return <code>FALSE</code>;
           the plugin loader continues to run all plugins and just logs an error
-          to the console. We'll be calling into <code>gs_plugin_refresh()</code>
+          to the console. We'll be calling into <code>refresh_metadata_async()</code>
           again in only another hour, so there's no need to bother the user.
           For actions like <code>gs_plugin_app_install</code> we also do the same
           thing, but we also save the error on the GsApp itself so that the UI is
@@ -411,30 +411,62 @@ gs_plugin_custom_list_installed_apps_finish (GsPlugin      *plugin,
         <example>
           <title>Refresh example</title>
           <programlisting>
-gboolean
-gs_plugin_refresh (GsPlugin *plugin,
-                   guint cache_age,
-                   GCancellable *cancellable,
-                   GError **error)
+static void download_file_cb (GObject *source_object,
+                              GAsyncResult *result,
+                              gpointer user_data);
+
+static void
+gs_plugin_example_refresh_metadata_async (GsPlugin *plugin,
+                                          guint64 cache_age_secs,
+                                          GsPluginRefreshMetadataFlags flags,
+                                          GCancellable *cancellable,
+                                          GError **error)
 {
-  const gchar *metadata_fn = "/var/cache/example/metadata.xml";
-  const gchar *metadata_url = "http://www.example.com/new.xml";;
-  g_autoptr(GFile) file = g_file_new_for_path (metadata_fn);
-
-  /* is the metadata missing or too old */
-  if (gs_utils_get_file_age (file) &gt; cache_age) {
-    if (!gs_plugin_download_file (plugin,
-                                  NULL,
-                                  metadata_url,
-                                  metadata_fn,
-                                  cancellable,
-                                  error)) {
-      /* it's okay to fail here */
-      return FALSE;
-    }
+  const gchar *metadata_filename = "/var/cache/example/metadata.xml";
+  const gchar *metadata_url = "https://www.example.com/new.xml";;
+  g_autoptr(GFile) file = g_file_new_for_path (metadata_filename);
+  g_autoptr(GTask) task = NULL;
+
+  task = g_task_new (plugin, cancellable, callback, user_data);
+  g_task_set_source_tag (task, gs_plugin_example_refresh_metadata_async);
+
+  /* is the metadata missing or too old? */
+  if (gs_utils_get_file_age (file) &gt; cache_age_secs) {
+    gs_plugin_download_file_async (plugin,
+                                   NULL,
+                                   metadata_url,
+                                   metadata_filename,
+                                   cancellable,
+                                   download_file_cb,
+                                   g_steal_pointer (&amp;task));
+    return;
+  }
+
+  g_task_return_boolean (task, TRUE);
+}
+
+static void
+download_file_cb (GObject *source_object,
+                  GAsyncResult *result,
+                  gpointer user_data)
+{
+  GsPlugin *plugin = GS_PLUGIN (source_object);
+  g_autoptr(GTask) task = g_steal_pointer (&amp;user_data);
+
+  if (!gs_plugin_download_file_finish (plugin, result, &amp;local_error)) {
+    g_task_return_error (task, g_steal_pointer (&amp;local_error));
+  } else {
     g_debug ("successfully downloaded new metadata");
+    g_task_return_boolean (task, TRUE);
   }
-  return TRUE;
+}
+
+static gboolean
+gs_plugin_example_refresh_metadata_finish (GsPlugin *plugin,
+                                           GAsyncResult *result,
+                                           GError **error)
+{
+  return g_task_propagate_boolean (G_TASK (result), error);
 }
           </programlisting>
         </example>
@@ -560,7 +592,7 @@ gs_plugin_example_refine_finish (GsPlugin *plugin,
           going to be shown.
           For example, the <code>steam</code> plugin downloads and parses the
           descriptions from a remote service during
-          <code>gs_plugin_refresh()</code>, and also finds the best icon types
+          <code>refresh_metadata_async()</code>, and also finds the best icon types
           and downloads them too.
           Then it exports the data to an AppStream XML file, saving it to your
           home directory.