Bug 1897264 - interruption support for ingestion

Added an `interrupt_everything` method that interrupts both the read and
write connection.  This is intended for iOS to use to interrupt the
suggest component during shutdown.  See
https://bugzilla.mozilla.org/show_bug.cgi?id=1897299 for a discussion on
next steps here.

Created a new `WriteScope` type that stores an interrupt scope that can
be used for multiple `write` calls.  This allows the ingestion code to
catch all interruptions that happened after the ingestion started. With
the old system, if `interrupt_everything` was called in-between
ingestion two types then we might miss it.

Author: bendk

components/suggest/README.md

@@ -20,9 +20,9 @@ While the store provides most of the functionality, the application has a few re
 
 **1. Create and manage a `SuggestStore` as a singleton.** Under the hood, the store holds multiple connections to the database: a read-write connection for ingestion, and a read-only connection for queries. The store uses the right connection for each operation, so applications shouldn't create multiple stores. The application is responsible for specifying the correct platform-specific storage directory for the database. The database contains _cached data_, like suggestions, and _user data_, like which suggestions have been dismissed. For this reason, applications should persist the database in their durable storage or "profile" directory. Applications specify the storage directory, and create a store, using the `SuggestStoreBuilder` interface.
 
-**2. Periodically call the store's `ingest()` method to ingest new suggestions.** While the store takes care of efficiently downloading and persisting suggestions from Remote Settings, the application is still responsible for scheduling this work. This is because the Suggest component doesn't have access to the various platform-specific background work scheduling mechanisms, like `nsIUpdateTimerManager` on Desktop, `WorkManager` on Android, or `BGTaskScheduler` on iOS. These are three different APIs with different constraints, written in three different languages. Instead of trying to bind to these different mechanisms, the component leaves it up to the application to use the right one on each platform. Ingestion is network- and disk I/O-bound, and should be done in the background.
+**2. Periodically call the store's `ingest()` method to ingest new suggestions.** While the store takes care of efficiently downloading and persisting suggestions from Remote Settings, the application is still responsible for scheduling this work. This is because the Suggest component doesn't have access to the various platform-specific background work scheduling mechanisms, like `nsIUpdateTimerManager` on Desktop, `WorkManager` on Android, or `BGTaskScheduler` on iOS. These are three different APIs with different constraints, written in three different languages. Instead of trying to bind to these different mechanisms, the component leaves it up to the application to use the right one on each platform. Ingestion is network- and disk I/O-bound, and should be done in the background.  If the ingestion needs to be cancelled, call `interrupt(InterruptKind::Write)`.
 
-**3. Use the store's `query()` and `interrupt()` methods to query for fresh suggestions as the user types.** The application passes the user's input, and additional options like which suggestion types to return, to `query()`. Querying the database is disk I/O-bound, so applications should use their respective platforms' facilities for asynchronous work—Kotlin coroutines on Android, and Swift actors on iOS; the UniFFI bindings for Desktop take care of dispatching work to a background thread pool—to avoid blocking the main thread. Running `query()` off-main-thread also lets applications `interrupt()` those queries from the main thread when the user's input changes. This avoids waiting for a query to return suggestions that are now stale.
+**3. Use the store's `query()` and `interrupt()` methods to query for fresh suggestions as the user types.** The application passes the user's input, and additional options like which suggestion types to return, to `query()`. Querying the database is disk I/O-bound, so applications should use their respective platforms' facilities for asynchronous work—Kotlin coroutines on Android, and Swift actors on iOS; the UniFFI bindings for Desktop take care of dispatching work to a background thread pool—to avoid blocking the main thread. Running `query()` off-main-thread also lets applications `interrupt(InterruptKind::Read)` those queries from the main thread when the user's input changes. This avoids waiting for a query to return suggestions that are now stale.
 
 ### For contributors
 

components/suggest/src/db.rs

@@ -6,7 +6,7 @@
 use std::{collections::HashSet, path::Path, sync::Arc};
 
 use interrupt_support::{SqlInterruptHandle, SqlInterruptScope};
-use parking_lot::Mutex;
+use parking_lot::{Mutex, MutexGuard};
 use rusqlite::{
     named_params,
     types::{FromSql, ToSql},
@@ -98,7 +98,7 @@ impl SuggestDb {
     pub fn read<T>(&self, op: impl FnOnce(&SuggestDao) -> Result<T>) -> Result<T> {
         let conn = self.conn.lock();
         let scope = self.interrupt_handle.begin_interrupt_scope()?;
-        let dao = SuggestDao::new(&conn, scope);
+        let dao = SuggestDao::new(&conn, &scope);
         op(&dao)
     }
 
@@ -107,11 +107,45 @@ impl SuggestDb {
         let mut conn = self.conn.lock();
         let scope = self.interrupt_handle.begin_interrupt_scope()?;
         let tx = conn.transaction()?;
-        let mut dao = SuggestDao::new(&tx, scope);
+        let mut dao = SuggestDao::new(&tx, &scope);
         let result = op(&mut dao)?;
         tx.commit()?;
         Ok(result)
     }
+
+    /// Create a new write scope.
+    ///
+    /// This enables performing multiple `write()` calls with the same shared interrupt scope.
+    /// This is important for things like ingestion, where you want the operation to be interrupted
+    /// if [Self::interrupt_handle::interrupt] is called after the operation starts.  Calling
+    /// [Self::write] multiple times during the operation risks missing a call that happens after
+    /// between those calls.
+    pub fn write_scope(&self) -> Result<WriteScope> {
+        Ok(WriteScope {
+            conn: self.conn.lock(),
+            scope: self.interrupt_handle.begin_interrupt_scope()?,
+        })
+    }
+}
+
+pub(crate) struct WriteScope<'a> {
+    pub conn: MutexGuard<'a, Connection>,
+    pub scope: SqlInterruptScope,
+}
+
+impl WriteScope<'_> {
+    /// Accesses the Suggest database in a transaction for reading and writing.
+    pub fn write<T>(&mut self, op: impl FnOnce(&mut SuggestDao) -> Result<T>) -> Result<T> {
+        let tx = self.conn.transaction()?;
+        let mut dao = SuggestDao::new(&tx, &self.scope);
+        let result = op(&mut dao)?;
+        tx.commit()?;
+        Ok(result)
+    }
+
+    pub fn err_if_interrupted(&self) -> Result<()> {
+        Ok(self.scope.err_if_interrupted()?)
+    }
 }
 
 /// A data access object (DAO) that wraps a connection to the Suggest database
@@ -122,11 +156,11 @@ impl SuggestDb {
 /// reference (`&mut self`).
 pub(crate) struct SuggestDao<'a> {
     pub conn: &'a Connection,
-    pub scope: SqlInterruptScope,
+    pub scope: &'a SqlInterruptScope,
 }
 
 impl<'a> SuggestDao<'a> {
-    fn new(conn: &'a Connection, scope: SqlInterruptScope) -> Self {
+    fn new(conn: &'a Connection, scope: &'a SqlInterruptScope) -> Self {
         Self { conn, scope }
     }
 

components/suggest/src/lib.rs

@@ -25,7 +25,7 @@ pub use config::{SuggestGlobalConfig, SuggestProviderConfig};
 pub use error::SuggestApiError;
 pub use provider::SuggestionProvider;
 pub use query::SuggestionQuery;
-pub use store::{SuggestIngestionConstraints, SuggestStore, SuggestStoreBuilder};
+pub use store::{InterruptKind, SuggestIngestionConstraints, SuggestStore, SuggestStoreBuilder};
 pub use suggestion::{raw_suggestion_url_matches, Suggestion};
 
 pub(crate) type Result<T> = std::result::Result<T, error::Error>;