feat!(ffi): new visit_schema FFI and rename old visit_schema to visit_snapshot_schema (#683)

## What changes are proposed in this pull request?
When given a schema (e.g. in `global_scan_state`) the engine needs a way
to visit this schema. This introduces a new API `visit_schema` to allow
engines to visit any schema over FFI. An API called `visit_schema`
previously existed but visited the schema of a given _snapshot_; this
has now been renamed to `visit_snapshot_schema`.


### This PR affects the following public APIs
Renamed `visit_schema` to `visit_snapshot_schema` and now `visit_schema`
takes `SharedSchema` as an argument instead of a snapshot.


## How was this change tested?
updated read_table test

Author: zachschuermann

ffi/examples/read-table/schema.h

@@ -273,7 +273,7 @@ void print_schema(SharedSnapshot* snapshot)
     .visit_timestamp = visit_timestamp,
     .visit_timestamp_ntz = visit_timestamp_ntz,
   };
-  uintptr_t schema_list_id = visit_schema(snapshot, &visitor);
+  uintptr_t schema_list_id = visit_snapshot_schema(snapshot, &visitor);
 #ifdef VERBOSE
   printf("Schema returned in list %" PRIxPTR "\n", schema_list_id);
 #endif

ffi/src/schema.rs

@@ -1,6 +1,6 @@
 use std::os::raw::c_void;
 
-use crate::scan::CStringMap;
+use crate::scan::{CStringMap, SharedSchema};
 use crate::{handle::Handle, kernel_string_slice, KernelStringSlice, SharedSnapshot};
 use delta_kernel::schema::{ArrayType, DataType, MapType, PrimitiveType, StructType};
 
@@ -201,11 +201,32 @@ pub struct EngineSchemaVisitor {
 ///
 /// Caller is responsible for passing a valid snapshot handle and schema visitor.
 #[no_mangle]
-pub unsafe extern "C" fn visit_schema(
+pub unsafe extern "C" fn visit_snapshot_schema(
     snapshot: Handle<SharedSnapshot>,
     visitor: &mut EngineSchemaVisitor,
 ) -> usize {
     let snapshot = unsafe { snapshot.as_ref() };
+    visit_schema_impl(snapshot.schema(), visitor)
+}
+
+/// Visit the given `schema` using the provided `visitor`. See the documentation of
+/// [`EngineSchemaVisitor`] for a description of how this visitor works.
+///
+/// This method returns the id of the list allocated to hold the top level schema columns.
+///
+/// # Safety
+///
+/// Caller is responsible for passing a valid schema handle and schema visitor.
+#[no_mangle]
+pub unsafe extern "C" fn visit_schema(
+    schema: Handle<SharedSchema>,
+    visitor: &mut EngineSchemaVisitor,
+) -> usize {
+    let schema = unsafe { schema.as_ref() };
+    visit_schema_impl(schema, visitor)
+}
+
+fn visit_schema_impl(schema: &StructType, visitor: &mut EngineSchemaVisitor) -> usize {
     // Visit all the fields of a struct and return the list of children
     fn visit_struct_fields(visitor: &EngineSchemaVisitor, s: &StructType) -> usize {
         let child_list_id = (visitor.make_field_list)(visitor.data, s.fields.len());
@@ -316,5 +337,5 @@ pub unsafe extern "C" fn visit_schema(
         }
     }
 
-    visit_struct_fields(visitor, snapshot.schema())
+    visit_struct_fields(visitor, schema)
 }