argconv: Define new traits for a bit safer FFI

The reasons behind the API (and this PR) are following:

- reduce the lifetime of reference obtained from the pointer
Current pointer-to-ref conversion API (ptr_to_ref_[mut]) returns a
reference with a static lifetime. New API is parameterized by a lifetime,
which is not 'static.

- Ensure that IF the memory associated with the pointer was allocated a certain way,
  the raw pointer will be converted to the corresponding Rust pointer primitive i.e. Box or Arc
  (or reference if the pointer was not obtained from an explicit allocation).
However, this does not give us any guarantees about the origin of the pointer.
Consider following example:

// Rust
impl ArcFFI for Foo {}

fn extern "C" f1() -> *const Foo {
    // a pointer to stack variable
    // Also applies to some valid pointer obtained from the reference
    // to the field of some already heap-allocated object.
    // Decided to go with a stack variable to keep the example simple.
    let foo = Foo;
    &foo
}

fn extern "C" f2(foo: *const Foo) {
    let foo = ArcFFI::cloned_from_ptr(foo);
}

// C
Foo *foo = f1();
f2(foo);

// Segfault.
// Even if f1() returned a valid pointer, that points to some
// heap-allocated memory. The pointer was not obtained from an Arc allocation.
// I.e., it was not obtained via Arc::into_raw().

To guarantee this, we need to introduce a special type for pointer that
would represent the pointer's properties. This will be done in a follow-up PR.

Author: Lorak-mmk

scylla-rust-wrapper/src/argconv.rs

@@ -97,3 +97,77 @@ macro_rules! make_c_str {
 
 #[cfg(test)]
 pub(crate) use make_c_str;
+
+/// Defines a pointer manipulation API for non-shared heap-allocated data.
+///
+/// Implement this trait for types that are allocated by the driver via [`Box::new`],
+/// and then returned to the user as a pointer. The user is responsible for freeing
+/// the memory associated with the pointer using corresponding driver's API function.
+pub trait BoxFFI {
+    fn into_ptr(self: Box<Self>) -> *mut Self {
+        Box::into_raw(self)
+    }
+    unsafe fn from_ptr(ptr: *mut Self) -> Box<Self> {
+        Box::from_raw(ptr)
+    }
+    unsafe fn as_maybe_ref<'a>(ptr: *const Self) -> Option<&'a Self> {
+        ptr.as_ref()
+    }
+    unsafe fn as_ref<'a>(ptr: *const Self) -> &'a Self {
+        ptr.as_ref().unwrap()
+    }
+    unsafe fn as_mut_ref<'a>(ptr: *mut Self) -> &'a mut Self {
+        ptr.as_mut().unwrap()
+    }
+    unsafe fn free(ptr: *mut Self) {
+        std::mem::drop(BoxFFI::from_ptr(ptr));
+    }
+}
+
+/// Defines a pointer manipulation API for shared heap-allocated data.
+///
+/// Implement this trait for types that require a shared ownership of data.
+/// The data should be allocated via [`Arc::new`], and then returned to the user as a pointer.
+/// The user is responsible for freeing the memory associated
+/// with the pointer using corresponding driver's API function.
+pub trait ArcFFI {
+    fn as_ptr(self: &Arc<Self>) -> *const Self {
+        Arc::as_ptr(self)
+    }
+    fn into_ptr(self: Arc<Self>) -> *const Self {
+        Arc::into_raw(self)
+    }
+    unsafe fn from_ptr(ptr: *const Self) -> Arc<Self> {
+        Arc::from_raw(ptr)
+    }
+    unsafe fn cloned_from_ptr(ptr: *const Self) -> Arc<Self> {
+        Arc::increment_strong_count(ptr);
+        Arc::from_raw(ptr)
+    }
+    unsafe fn as_maybe_ref<'a>(ptr: *const Self) -> Option<&'a Self> {
+        ptr.as_ref()
+    }
+    unsafe fn as_ref<'a>(ptr: *const Self) -> &'a Self {
+        ptr.as_ref().unwrap()
+    }
+    unsafe fn free(ptr: *const Self) {
+        std::mem::drop(ArcFFI::from_ptr(ptr));
+    }
+}
+
+/// Defines a pointer manipulation API for data owned by some other object.
+///
+/// Implement this trait for the types that do not need to be freed (directly) by the user.
+/// The lifetime of the data is bound to some other object owning it.
+///
+/// For example: lifetime of CassRow is bound by the lifetime of CassResult.
+/// There is no API function that frees the CassRow. It should be automatically
+/// freed when user calls cass_result_free.
+pub trait RefFFI {
+    fn as_ptr(&self) -> *const Self {
+        self as *const Self
+    }
+    unsafe fn as_ref<'a>(ptr: *const Self) -> &'a Self {
+        ptr.as_ref().unwrap()
+    }
+}