Align scalar state semantics and revert TableFunctionOptions (#638)

- Aligns the State associated type in VScalar and VArrowScalar traits
with DuckDB's extra_info semantics (Adding `+ 'static` is technically a
breaking change, but practically unlikely to break anything - most state
types are owned data anyway)
- Reverts the TableFunctionOptions wrapper from #637 in favor of keeping
the simpler register_table_function_with_extra_info API
- Renamed (private) APIs are now aligned across table and scalar
functions

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,33 @@ 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
@@ -109,7 +110,7 @@ impl From<duckdb_function_info> for ScalarFunctionInfo {
 }
 
 impl ScalarFunctionInfo {
-    pub unsafe fn get_scalar_extra_info<T>(&self) -> &T {
+    pub unsafe fn get_extra_info<T>(&self) -> &T {
         &*(duckdb_scalar_function_get_extra_info(self.0).cast())
     }
 
@@ -125,14 +126,14 @@ where
 {
     let info = ScalarFunctionInfo::from(info);
     let mut input = DataChunkHandle::new_unowned(input);
-    let result = T::invoke(info.get_scalar_extra_info(), &mut input, &mut output);
+    let result = T::invoke(info.get_extra_info(), &mut input, &mut output);
     if let Err(e) = result {
         info.set_error(&e.to_string());
     }
 }
 
 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,9 @@ 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.
+    ///
+    /// The state is cloned once per function signature (overload) and stored in DuckDB's catalog.
     #[inline]
     pub fn register_scalar_function_with_state<S: VScalar>(&self, name: &str, state: &S::State) -> crate::Result<()>
     where

crates/duckdb/src/vtab/function.rs

@@ -111,7 +111,7 @@ impl BindInfo {
     pub fn set_cardinality(&self, cardinality: idx_t, is_exact: bool) {
         unsafe { duckdb_bind_set_cardinality(self.ptr, cardinality, is_exact) }
     }
-    /// Retrieves the extra info of the function as set in [`TableFunction::with_extra_info`].
+    /// Retrieves the extra info of the function as set in [`TableFunction::set_extra_info`].
     pub fn get_extra_info<T>(&self) -> *const T {
         unsafe { duckdb_bind_get_extra_info(self.ptr).cast() }
     }
@@ -163,7 +163,7 @@ impl InitInfo {
         indices
     }
 
-    /// Retrieves the extra info of the function as set in [`TableFunction::with_extra_info`].
+    /// Retrieves the extra info of the function as set in [`TableFunction::set_extra_info`].
     pub fn get_extra_info<T>(&self) -> *const T {
         unsafe { duckdb_init_get_extra_info(self.0).cast() }
     }
@@ -306,35 +306,33 @@ impl TableFunction {
         self
     }
 
-    /// Assigns extra information to the table function that can be fetched during binding, etc.
+    /// Assigns extra information to the table function using raw pointers.
     ///
-    /// For most use cases, prefer [`with_extra_info`](Self::with_extra_info) which handles memory management automatically.
+    /// 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
     /// 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(&self, extra_info: *mut c_void, destroy: duckdb_delete_callback_t) {
+    pub unsafe fn set_extra_info_raw(&self, extra_info: *mut c_void, destroy: duckdb_delete_callback_t) {
         duckdb_table_function_set_extra_info(self.ptr, extra_info, destroy);
     }
 
     /// Assigns extra information to the table function that can be fetched during binding, init, and execution.
     ///
-    /// This is a safe wrapper around [`set_extra_info`](Self::set_extra_info) that handles memory management automatically.
-    ///
     /// # Arguments
     /// * `info`: The extra information to store
-    pub fn with_extra_info<T>(&self, info: T) -> &Self
+    pub fn set_extra_info<T>(&self, info: T) -> &Self
     where
         T: Send + Sync + 'static,
     {
         unsafe {
             let boxed = Box::new(info);
             let ptr = Box::into_raw(boxed) as *mut c_void;
-            self.set_extra_info(ptr, Some(drop_boxed::<T>));
+            self.set_extra_info_raw(ptr, Some(drop_boxed::<T>));
         }
         self
     }
@@ -404,7 +402,7 @@ impl<V: VTab> TableFunctionInfo<V> {
         }
     }
 
-    /// Retrieves the extra info of the function as set in [`TableFunction::with_extra_info`].
+    /// Retrieves the extra info of the function as set in [`TableFunction::set_extra_info`].
     pub fn get_extra_info<T>(&self) -> *mut T {
         unsafe { duckdb_function_get_extra_info(self.ptr).cast() }
     }

crates/duckdb/src/vtab/mod.rs

@@ -23,20 +23,6 @@ mod excel;
 pub use function::{BindInfo, InitInfo, TableFunction, TableFunctionInfo};
 pub use value::Value;
 
-/// Options for registering a table function.
-pub struct TableFunctionOptions<E> {
-    /// Extra info passed to the function at runtime.
-    /// Accessible via `BindInfo::get_extra_info`, `InitInfo::get_extra_info`,
-    /// or `TableFunctionInfo::get_extra_info`.
-    pub extra_info: Option<E>,
-}
-
-impl<E> Default for TableFunctionOptions<E> {
-    fn default() -> Self {
-        Self { extra_info: None }
-    }
-}
-
 use crate::core::{DataChunkHandle, LogicalTypeHandle};
 use ffi::{duckdb_bind_info, duckdb_data_chunk, duckdb_function_info, duckdb_init_info};
 
@@ -165,26 +151,25 @@ impl Connection {
         self.db.borrow_mut().register_table_function(table_function)
     }
 
-    /// Register the given TableFunction with options.
+    /// Register the given TableFunction with custom extra info.
+    ///
+    /// This allows you to pass extra info that can be accessed during bind, init, and execution
+    /// via `BindInfo::get_extra_info`, `InitInfo::get_extra_info`, or `TableFunctionInfo::get_extra_info`.
+    ///
+    /// The extra info is cloned once during registration and stored in DuckDB's catalog.
     #[inline]
-    pub fn register_table_function_with_options<T: VTab, E>(
-        &self,
-        name: &str,
-        options: TableFunctionOptions<E>,
-    ) -> Result<()>
+    pub fn register_table_function_with_extra_info<T: VTab, E>(&self, name: &str, extra_info: &E) -> Result<()>
     where
-        E: Send + Sync + 'static,
+        E: Clone + Send + Sync + 'static,
     {
         let table_function = TableFunction::default();
         table_function
             .set_name(name)
             .supports_pushdown(T::supports_pushdown())
             .set_bind(Some(bind::<T>))
             .set_init(Some(init::<T>))
-            .set_function(Some(func::<T>));
-        if let Some(extra_info) = options.extra_info {
-            table_function.with_extra_info(extra_info);
-        }
+            .set_function(Some(func::<T>))
+            .set_extra_info(extra_info.clone());
         for ty in T::parameters().unwrap_or_default() {
             table_function.add_parameter(&ty);
         }
@@ -371,14 +356,9 @@ mod test {
     }
 
     #[test]
-    fn test_table_function_with_options() -> Result<(), Box<dyn Error>> {
+    fn test_table_function_with_extra_info() -> Result<(), Box<dyn Error>> {
         let conn = Connection::open_in_memory()?;
-        conn.register_table_function_with_options::<PrefixVTab, _>(
-            "greet",
-            TableFunctionOptions {
-                extra_info: Some("Howdy".to_string()),
-            },
-        )?;
+        conn.register_table_function_with_extra_info::<PrefixVTab, _>("greet", &"Howdy".to_string())?;
 
         let val = conn.query_row("select * from greet('partner')", [], |row| <(String,)>::try_from(row))?;
         assert_eq!(val, ("Howdy partner".to_string(),));