feat: Cursors can now have shared ownership over Connections using

`Connection::execute_arc`.

Author: pacman82

odbc-api/src/connection.rs

@@ -11,6 +11,7 @@ use std::{
     fmt::{self, Debug, Display},
     mem::ManuallyDrop,
     str,
+    sync::Arc,
     thread::panicking,
 };
 
@@ -294,6 +295,38 @@ impl<'c> Connection<'c> {
         Ok(Some(cursor))
     }
 
+    /// Like [`Connection::execute`], but takes ownership of an `Arc<Self>`.
+    pub fn execute_arc(
+        self: Arc<Self>,
+        query: &str,
+        params: impl ParameterCollectionRef,
+        query_timeout_sec: Option<usize>,
+    ) -> Result<Option<CursorImpl<StatementConnection<Arc<Connection<'c>>>>>, Error>  {
+        // With the current Rust version the borrow checker needs some convincing, so that it allows
+        // us to return the Connection, even though the Result of execute borrows it.
+        let mut error = None;
+        let mut cursor = None;
+        match self.execute(query, params, query_timeout_sec) {
+            Ok(Some(c)) => cursor = Some(c),
+            Ok(None) => return Ok(None),
+            Err(e) => error = Some(e),
+        };
+        if let Some(e) = error {
+            drop(cursor);
+            return Err(e);
+        }
+        let cursor = cursor.unwrap();
+        // The rust compiler needs some help here. It assumes otherwise that the lifetime of the
+        // resulting cursor would depend on the lifetime of `params`.
+        let mut cursor = ManuallyDrop::new(cursor);
+        let handle = cursor.as_sys();
+        // Safe: `handle` is a valid statement, and we are giving up ownership of `self`.
+        let statement = unsafe { StatementConnection::new(handle, self) };
+        // Safe: `statement is in the cursor state`.
+        let cursor = unsafe { CursorImpl::new(statement) };
+        Ok(Some(cursor))
+    }
+
     /// Prepares an SQL statement. This is recommended for repeated execution of similar queries.
     ///
     /// Should your use case require you to execute the same query several times with different
@@ -759,14 +792,24 @@ impl Debug for Connection<'_> {
     }
 }
 
-/// We need to implement ConnectionOwner in order to be able to use Connection together with
-/// [`StatementConnection`].
+/// We need to implement ConnectionOwner for [`Connection`] in order to express ownership of a
+/// connection for a statement handle. This is e.g. needed for [`Connection::into_cursor`].
 ///
 /// # Safety:
 /// 
 /// Connection wraps an open Connection. It keeps the handle alive and valid during its lifetime.
 unsafe impl ConnectionOwner for Connection<'_> {}
 
+/// We need to implement ConnectionOwner for `Arc<Connection>` in order to be able to express
+/// ownership of a shared connection from a statement handle. This is e.g. needed for
+/// [`Connection::execute_arc`].
+///
+/// # Safety:
+/// 
+/// Arc<Connection> wraps an open Connection. It keeps the handle alive and valid during its
+/// lifetime.
+unsafe impl ConnectionOwner for Arc<Connection<'_>> {}
+
 /// Options to be passed then opening a connection to a datasource.
 #[derive(Default, Clone, Copy)]
 pub struct ConnectionOptions {

odbc-api/src/handles/statement_connection.rs

@@ -14,6 +14,10 @@ impl<C> StatementConnection<C>
 where
     C: ConnectionOwner,
 {
+    /// # Safety
+    /// 
+    /// Handle must be a valid statement handle and the parent connection must be valid for the
+    /// lifetime of parent.
     pub(crate) unsafe fn new(handle: HStmt, parent: C) -> Self {
         Self {
             _parent: parent,
@@ -97,4 +101,4 @@ where
     fn as_stmt_ref(&mut self) -> StatementRef<'_> {
         self.as_stmt_ref()
     }
-}
+}

odbc-api/tests/integration.rs

@@ -41,7 +41,9 @@ use std::{
     iter,
     num::NonZeroUsize,
     ptr::null_mut,
-    str, thread,
+    str,
+    sync::Arc,
+    thread,
     time::{Duration, Instant},
 };
 
@@ -571,6 +573,37 @@ fn into_cursor(profile: &Profile) {
     assert_eq!(expected, actual);
 }
 
+/// We want to be able to create multiple statements with the utilizing the same connection, yet we
+/// in some cases it might be hard to keep track of the ownership of the connection separately. So
+/// essentially we want our statements to be owning an `Arc` to connection.
+#[test_case(MSSQL; "Microsoft SQL Server")]
+#[test_case(MARIADB; "Maria DB")]
+#[test_case(SQLITE_3; "SQLite 3")]
+#[test_case(POSTGRES; "PostgreSQL")]
+fn shared_ownership_of_connections_by_statement(profile: &Profile) {
+    // Given
+    let table_name = table_name!();
+    let (conn, table) = Given::new(&table_name)
+        .column_types(&["INT"])
+        .values_by_column(&[&[Some("42")]])
+        .build(profile)
+        .unwrap();
+
+    // When
+    let conn = Arc::new(conn);
+    let cursor = conn
+        .clone()
+        .execute_arc(&table.sql_all_ordered_by_id(), (), None)
+        .unwrap()
+        .unwrap();
+    // We can drop the connection, even though, the cursor still exists.
+    drop(conn);
+
+    // Then
+    let expected = "42";
+    assert_eq!(expected, cursor_to_string(cursor));
+}
+
 /// Strong exception safety for `into_cursor`. Our first query will fail, because it will query a
 /// non-existing table, but our second one using the same connection will succeed. This is one
 /// scenario in which it is useful not to "swallow" the connection in case of an error.
@@ -1483,20 +1516,20 @@ fn var_char_slice_mut_as_input_output_parameter(profile: &Profile) {
     let conn = profile.connection().unwrap();
     conn.execute(
         r#"
-        IF EXISTS (SELECT name FROM sysobjects WHERE name = 'TestInOutText')  
-        DROP PROCEDURE TestInOutText  
+        IF EXISTS (SELECT name FROM sysobjects WHERE name = 'TestInOutText')
+        DROP PROCEDURE TestInOutText
         "#,
         (),
         None,
     )
     .unwrap();
 
     conn.execute(
-        r#"CREATE PROCEDURE TestInOutText   
-        @OutParm VARCHAR(15) OUTPUT   
+        r#"CREATE PROCEDURE TestInOutText
+        @OutParm VARCHAR(15) OUTPUT
         AS
-        SELECT @OutParm = 'Hello, World!'  
-        RETURN 99  
+        SELECT @OutParm = 'Hello, World!'
+        RETURN 99
         "#,
         (),
         None,
@@ -2822,20 +2855,20 @@ fn output_parameter(profile: &Profile) {
     let conn = profile.connection().unwrap();
     conn.execute(
         r#"
-        IF EXISTS (SELECT name FROM sysobjects WHERE name = 'TestOutputParam')  
-        DROP PROCEDURE TestOutputParam  
+        IF EXISTS (SELECT name FROM sysobjects WHERE name = 'TestOutputParam')
+        DROP PROCEDURE TestOutputParam
         "#,
         (),
         None,
     )
     .unwrap();
 
     conn.execute(
-        r#"CREATE PROCEDURE TestOutputParam   
-        @OutParm int OUTPUT   
+        r#"CREATE PROCEDURE TestOutputParam
+        @OutParm int OUTPUT
         AS
-        SELECT @OutParm = @OutParm + 5  
-        RETURN 99  
+        SELECT @OutParm = @OutParm + 5
+        RETURN 99
         "#,
         (),
         None,