Align VScalar State with DuckDB's extra_info semantics

Author: mlafeldt

crates/duckdb/src/vscalar/arrow.rs

@@ -73,12 +73,13 @@ impl ArrowFunctionSignature {
 
 /// A trait for scalar functions that accept and return arrow types that can be registered with DuckDB
 pub trait VArrowScalar: Sized {
-    /// State that persists across invocations of the scalar function (the lifetime of the connection)
-    /// The state can be accessed by multiple threads, so it must be `Send + Sync`.
-    type State: Default + Sized + Send + Sync;
+    /// State set at registration time. Persists for the lifetime of the catalog entry.
+    /// Shared across worker threads and invocations — must not be modified during execution.
+    /// Must be `'static` as it is stored in DuckDB and may outlive the current stack frame.
+    type State: Default + Sized + Send + Sync + 'static;
 
     /// The actual function that is called by DuckDB
-    fn invoke(info: &Self::State, input: RecordBatch) -> Result<Arc<dyn Array>, Box<dyn std::error::Error>>;
+    fn invoke(state: &Self::State, input: RecordBatch) -> Result<Arc<dyn Array>, Box<dyn std::error::Error>>;
 
     /// The possible signatures of the scalar function. These will result in DuckDB scalar function overloads.
     /// The invoke method should be able to handle all of these signatures.
@@ -92,11 +93,11 @@ where
     type State = T::State;
 
     unsafe fn invoke(
-        info: &Self::State,
+        state: &Self::State,
         input: &mut DataChunkHandle,
         out: &mut dyn WritableVector,
     ) -> Result<(), Box<dyn std::error::Error>> {
-        let array = T::invoke(info, data_chunk_to_arrow(input)?)?;
+        let array = T::invoke(state, data_chunk_to_arrow(input)?)?;
         write_arrow_array_to_vector(&array, out)
     }
 
@@ -200,8 +201,8 @@ mod test {
     impl VArrowScalar for ArrowOverloaded {
         type State = MockState;
 
-        fn invoke(s: &Self::State, input: RecordBatch) -> Result<Arc<dyn Array>, Box<dyn std::error::Error>> {
-            assert_eq!("some meta", s.info);
+        fn invoke(state: &Self::State, input: RecordBatch) -> Result<Arc<dyn Array>, Box<dyn std::error::Error>> {
+            assert_eq!("some meta", state.info);
 
             let a = input.column(0);
             let b = input.column(1);

crates/duckdb/src/vscalar/function.rs

@@ -112,25 +112,34 @@ impl ScalarFunction {
         self
     }
 
-    /// Assigns extra information to the scalar function that can be fetched during binding, etc.
+    /// Assigns extra information to the scalar function using raw pointers.
+    ///
+    /// For most use cases, prefer [`set_extra_info`](Self::set_extra_info) which handles memory management automatically.
     ///
     /// # Arguments
-    /// * `extra_info`: The extra information
-    /// * `destroy`: The callback that will be called to destroy the bind data (if any)
+    /// * `extra_info`: The extra information as a raw pointer
+    /// * `destroy`: The callback that will be called to destroy the data (if any)
     ///
     /// # Safety
-    unsafe fn set_extra_info_impl(&self, extra_info: *mut c_void, destroy: duckdb_delete_callback_t) {
+    /// The caller must ensure that `extra_info` is a valid pointer and that `destroy`
+    /// properly cleans up the data when called.
+    pub unsafe fn set_extra_info_raw(&self, extra_info: *mut c_void, destroy: duckdb_delete_callback_t) {
         duckdb_scalar_function_set_extra_info(self.ptr, extra_info, destroy);
     }
 
+    /// Assigns extra information to the scalar function that can be fetched during execution.
+    ///
+    /// # Arguments
+    /// * `info`: The extra information to store
+    /// ```
     pub fn set_extra_info<T>(&self, info: T) -> &Self
     where
-        T: Send + Sync,
+        T: Send + Sync + 'static,
     {
         unsafe {
             let t = Box::new(info);
             let c_void = Box::into_raw(t) as *mut c_void;
-            self.set_extra_info_impl(c_void, Some(drop_ptr::<T>));
+            self.set_extra_info_raw(c_void, Some(drop_ptr::<T>));
         }
         self
     }

crates/duckdb/src/vscalar/mod.rs

@@ -23,9 +23,10 @@ pub use arrow::{ArrowFunctionSignature, ArrowScalarParams, VArrowScalar};
 
 /// Duckdb scalar function trait
 pub trait VScalar: Sized {
-    /// State that persists across invocations of the scalar function (the lifetime of the connection)
-    /// The state can be accessed by multiple threads, so it must be `Send + Sync`.
-    type State: Sized + Send + Sync;
+    /// State set at registration time. Persists for the lifetime of the catalog entry.
+    /// Shared across worker threads and invocations — must not be modified during execution.
+    /// Must be `'static` as it is stored in DuckDB and may outlive the current stack frame.
+    type State: Sized + Send + Sync + 'static;
     /// The actual function
     ///
     /// # Safety
@@ -132,7 +133,7 @@ where
 }
 
 impl Connection {
-    /// Register the given ScalarFunction with default state
+    /// Register the given ScalarFunction with default state.
     #[inline]
     pub fn register_scalar_function<S: VScalar>(&self, name: &str) -> crate::Result<()>
     where
@@ -149,7 +150,7 @@ impl Connection {
         self.db.borrow_mut().register_scalar_function_set(set)
     }
 
-    /// Register the given ScalarFunction with custom state
+    /// Register the given ScalarFunction with custom state.
     #[inline]
     pub fn register_scalar_function_with_state<S: VScalar>(&self, name: &str, state: &S::State) -> crate::Result<()>
     where