allow backends to enable simultaneous mode to do actions in parallel

This changes the on-wire format slightly, although it should be forward
and backwards compatible. See the mailing list for discussion.

1 files changed, 133 insertions, 0 deletions

diff --git a/docs/api/spec/pk-concepts.xml b/docs/api/spec/pk-concepts.xml
index 2bfa38005..be2b8eb10 100644
--- a/docs/api/spec/pk-concepts.xml
+++ b/docs/api/spec/pk-concepts.xml
@@ -951,5 +951,138 @@
       lock is available and the transaction has started.
     </para>
   </sect1>
+
+  <sect1 id="introduction-ideas-simultaneous">
+    <title>Simultaneous Mode</title>
+    <para>
+      By default, a packagekit backend operates in a mode where only one activity is done at one
+      time, for example, epiphany is downloaded and then installed.
+      Some backends are able to download or install multiple files at once, and this may need to
+      be conveyed to a GUI tool as a list of variable length, rather than just a package_id and
+      summary.
+    </para>
+    <para>
+      The function <literal>pk_backend_set_simultaneous_mode(TRUE)</literal> is used to turn on
+      the simultaneous operation, where the backend can control the finished status of the
+      <literal>::Package()</literal> calls.
+      This is not needed for a typical backend.
+    </para>
+    <para>
+      For instance, a typical non-simultaneous backend might do:
+    </para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          1. <literal>pk_backend_package(DOWNLOADING, "epiphany")</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          2. <literal>pk_backend_package(DOWNLOADING, "nautilus")</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          3. <literal>pk_backend_package(INSTALLING, "epiphany")</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          4. <literal>pk_backend_package(INSTALLING, "nautilus")</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          5. <literal>pk_backend_finished(SUCCESS)</literal>
+        </para>
+      </listitem>
+    </itemizedlist>
+    <para>
+      This is translated by the daemon automatically into a coherent sequence that can be used to
+      update a GUI with the correct information.
+      This is done automatically and transparently from the backend.
+      The effective output from the daemon would be:
+    </para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          1. <literal>pk_backend_package(DOWNLOADING, "epiphany")</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          2. <literal>pk_backend_package(FINISHED, "epiphany")</literal>
+          <literal>pk_backend_package(DOWNLOADING, "nautilus")</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          3. <literal>pk_backend_package(FINISHED, "nautilus")</literal>
+          <literal>pk_backend_package(INSTALLING, "epiphany")</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          4. <literal>pk_backend_package(FINISHED, "epiphany")</literal>
+          <literal>pk_backend_package(INSTALLING, "nautilus")</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          5. <literal>pk_backend_package(FINISHED, "nautilus")</literal>
+          <literal>pk_backend_finished(SUCCESS)</literal>
+        </para>
+      </listitem>
+    </itemizedlist>
+    <para>
+      For a simultaneous backend, the backend is in full control of the <literal>FINISHED</literal>
+      state of the package actions.
+      This way it is possible to show the status of multiple packages in the GUI programs.
+    </para>
+    <para>
+      For instance, a typical simultaneous backend might do:
+    </para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          1. <literal>pk_backend_set_simultaneous_mode(TRUE)</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          2. <literal>pk_backend_package(DOWNLOADING, "epiphany")</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          3. <literal>pk_backend_package(DOWNLOADING, "nautilus")</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          4. <literal>pk_backend_package(FINISHED, "nautilus")</literal>
+          <literal>pk_backend_package(INSTALLING, "nautilus")</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          5. <literal>pk_backend_package(FINISHED, "epiphany")</literal>
+          <literal>pk_backend_package(INSTALLING, "epiphany")</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          6. <literal>pk_backend_package(FINISHED, "nautilus")</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          7. <literal>pk_backend_package(FINISHED, "epiphany")</literal>
+          <literal>pk_backend_finished(SUCCESS)</literal>
+        </para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
 </chapter>