Add Connection.call_timeout() and Connection.set_call_timeout().

Author: kubo

src/connection.rs

@@ -19,6 +19,7 @@ use std::mem;
 use std::ptr;
 use std::sync::Arc;
 use std::sync::Mutex;
+use std::time::Duration;
 
 use crate::binding::*;
 use crate::chkerr;
@@ -30,6 +31,7 @@ use crate::sql_type::ToSql;
 use crate::to_odpi_str;
 use crate::to_rust_slice;
 use crate::to_rust_str;
+use crate::util::duration_to_msecs;
 use crate::AssertSend;
 use crate::AssertSync;
 use crate::Context;
@@ -986,6 +988,73 @@ impl Connection {
         Ok(())
     }
 
+    /// Gets the current call timeout used for round-trips to
+    /// the database made with this connection. `None` means that no timeouts
+    /// will take place.
+    pub fn call_timeout(&self) -> Result<Option<Duration>> {
+        let mut value = 0;
+        chkerr!(
+            self.ctxt,
+            dpiConn_getCallTimeout(self.handle.raw(), &mut value)
+        );
+        if value != 0 {
+            Ok(Some(Duration::from_millis(value.into())))
+        } else {
+            Ok(None)
+        }
+    }
+
+    /// Sets the call timeout to be used for round-trips to the
+    /// database made with this connection. None means that no timeouts
+    /// will take place.
+    ///
+    /// The call timeout value applies to each database round-trip
+    /// individually, not to the sum of all round-trips. Time spent
+    /// processing in rust-oracle before or after the completion of each
+    /// round-trip is not counted.
+    ///
+    /// - If the time from the start of any one round-trip to the
+    ///   completion of that same round-trip exceeds call timeout,
+    ///   then the operation is halted and an exception occurs.
+    ///
+    /// - In the case where an rust-oracle operation requires more than one
+    ///   round-trip and each round-trip takes less than call timeout,
+    ///   then no timeout will occur, even if the sum of all round-trip
+    ///   calls exceeds call timeout.
+    ///
+    /// - If no round-trip is required, the operation will never be
+    ///   interrupted.
+    ///
+    /// After a timeout is triggered, rust-oracle attempts to clean up the
+    /// internal connection state. The cleanup is allowed to take another
+    /// `duration`.
+    ///
+    /// If the cleanup was successful, an exception DPI-1067 will be
+    /// raised but the application can continue to use the connection.
+    ///
+    /// For small values of call timeout, the connection cleanup may not
+    /// complete successfully within the additional call timeout
+    /// period. In this case an exception ORA-3114 is raised and the
+    /// connection will no longer be usable. It should be closed.
+    pub fn set_call_timeout(&self, dur: Option<Duration>) -> Result<()> {
+        if let Some(dur) = dur {
+            let msecs = duration_to_msecs(dur).ok_or(Error::OutOfRange(format!(
+                "Too large duration {:?}. It must be less than 49.7 days",
+                dur
+            )))?;
+            if msecs == 0 {
+                return Err(Error::OutOfRange(format!(
+                    "Too short duration {:?}. It must not be submilliseconds",
+                    dur
+                )));
+            }
+            chkerr!(self.ctxt, dpiConn_setCallTimeout(self.handle.raw(), msecs));
+        } else {
+            chkerr!(self.ctxt, dpiConn_setCallTimeout(self.handle.raw(), 0));
+        }
+        Ok(())
+    }
+
     /// Gets current schema associated with the connection
     pub fn current_schema(&self) -> Result<String> {
         let mut s = new_odpi_str();

src/util.rs

@@ -16,6 +16,7 @@
 use std::fmt;
 use std::result;
 use std::str;
+use std::time::Duration;
 
 use crate::sql_type::OracleType;
 use crate::Error;
@@ -194,6 +195,18 @@ pub fn write_literal(
     }
 }
 
+pub fn duration_to_msecs(dur: Duration) -> Option<u32> {
+    let msecs = dur
+        .as_secs()
+        .checked_mul(1000)?
+        .checked_add(dur.subsec_nanos() as u64 / 1_000_000)?;
+    if msecs <= u32::max_value() as u64 {
+        Some(msecs as u32)
+    } else {
+        None
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -256,4 +269,20 @@ mod tests {
             Ok(vec![0x9a, 0xab, 0xbc, 0xcd, 0xde, 0xef, 0xf0])
         );
     }
+
+    #[test]
+    fn test_duration_to_msecs() {
+        assert_eq!(duration_to_msecs(Duration::new(0, 0)), Some(0));
+        assert_eq!(duration_to_msecs(Duration::from_nanos(999_999)), Some(0));
+        assert_eq!(duration_to_msecs(Duration::from_nanos(1_000_000)), Some(1));
+        assert_eq!(
+            duration_to_msecs(Duration::from_millis(u32::max_value() as u64)),
+            Some(u32::max_value())
+        );
+        assert_eq!(
+            duration_to_msecs(Duration::from_millis(u32::max_value() as u64 + 1)),
+            None
+        );
+        assert_eq!(duration_to_msecs(Duration::new(50 * 24 * 60 * 60, 0)), None);
+    }
 }