[geary/mjog/mutex-lock-cleanup: 2/3] engine: Document various uses of lock to be clear why they are there

[Michael Gratton <mjog src gnome org>]

commit 847fd0320a86013baf2ae06d3f71e2615ee3402e
Author: Michael Gratton <mike vee net>
Date:   Sun Apr 4 13:58:02 2021 +1000

    engine: Document various uses of lock to be clear why they are there

 src/engine/db/db-database-connection.vala | 3 +++
 src/engine/db/db-database.vala            | 8 ++++++--
 src/engine/outbox/outbox-folder.vala      | 2 ++
 3 files changed, 11 insertions(+), 2 deletions(-)
---
diff --git a/src/engine/db/db-database-connection.vala b/src/engine/db/db-database-connection.vala
index da7d98600..9064d2ef3 100644
--- a/src/engine/db/db-database-connection.vala
+++ b/src/engine/db/db-database-connection.vala
@@ -84,6 +84,9 @@ public class Geary.Db.DatabaseConnection : Context, Connection {
         throws GLib.Error {
         this._database = database;
 
+        // async transactions are executed in the thread pool, so lock
+        // to ensure consistency if multiple constructed
+        // simultaneously
         lock (next_cx_number) {
             this.cx_number = next_cx_number++;
         }
diff --git a/src/engine/db/db-database.vala b/src/engine/db/db-database.vala
index df5bed216..b09e6eb33 100644
--- a/src/engine/db/db-database.vala
+++ b/src/engine/db/db-database.vala
@@ -32,7 +32,7 @@ public class Geary.Db.Database : Context {
     public File? file { get; private set; }
 
     /**
-     * The path passed to Sqlite when opening the database.
+     * The path passed to Sqlite when constructing the database.
      *
      * This will be the path to the database file on disk for
      * persistent databases, else {@link MEMORY_PATH} for transient
@@ -217,6 +217,7 @@ public class Geary.Db.Database : Context {
         return cx;
     }
 
+    // This method must be thread-safe
     private DatabaseConnection internal_open_connection(bool is_primary,
                                                         GLib.Cancellable? cancellable)
         throws GLib.Error {
@@ -381,6 +382,8 @@ public class Geary.Db.Database : Context {
             );
         }
 
+        // async transactions are executed in the thread pool, so lock
+        // to ensure consistency if multiple added simultaneously
         lock (this.outstanding_async_jobs) {
             this.outstanding_async_jobs++;
         }
@@ -404,7 +407,8 @@ public class Geary.Db.Database : Context {
         // No-op by default;
     }
 
-    // This method must be thread-safe.
+    // Invoked by the thread pool to execute a transaction. As such,
+    // this method must be thread-safe.
     private void on_async_job(owned TransactionAsyncJob job) {
         // *never* use primary connection for threaded operations
         var cx = job.default_cx;
diff --git a/src/engine/outbox/outbox-folder.vala b/src/engine/outbox/outbox-folder.vala
index 51c3c7b2a..88d0ccdf3 100644
--- a/src/engine/outbox/outbox-folder.vala
+++ b/src/engine/outbox/outbox-folder.vala
@@ -424,6 +424,8 @@ public class Geary.Outbox.Folder :
     //
 
     private int64 do_get_next_ordering(Db.Connection cx, Cancellable? cancellable) throws Error {
+        // Geary.Db executes SQlite transactions in a thread pool, so
+        // this needs to be thread-safe.
         lock (next_ordering) {
             if (next_ordering == 0) {
                 Db.Statement stmt = cx.prepare("SELECT COALESCE(MAX(ordering), 0) + 1 FROM SmtpOutboxTable");