wip: OwnedUPtr and Refnum

Had to extend the UPtr with ownership semantics and finalised the API
for the cookie jar without drop behaviour.

The API looks good but the tests in LabVIEW fail at this stage. Not sure
why.

Author: JamesWiresmith

justfile

@@ -1,6 +1,6 @@
 set windows-shell := ["powershell.exe", "-NoLogo", "-Command"]
 
-lv_ver := "2020"
+lv_ver := "2024"
 
 unit-tests:
   cargo test --no-default-features --features chrono,ndarray

labview-interop/src/labview.rs

@@ -7,12 +7,13 @@ use std::sync::LazyLock;
 
 use dlopen2::wrapper::{Container, WrapperApi};
 
-use crate::errors::LVInteropError;
+use crate::errors::{LVInteropError, MgError};
 use crate::{
     errors::{InternalError, Result},
     memory::MagicCookie,
     types::LVStatusCode,
 };
+use crate::memory::UPtr;
 
 /// The path to the LabVIEW runtime library.
 /// Set as const, so we can swap this for different platforms if required.
@@ -44,7 +45,7 @@ pub(crate) type UHandleValue = usize;
 /// Represents as UPtr passed by value. Can't use the generic
 /// version from the memory module else since the functions
 /// aren't generic.
-pub(crate) type UPtrValue = usize;
+pub(crate) type UPtrValue = *mut c_void;
 
 static SYNC_API: LazyLock<Result<Container<SyncApi>>> = LazyLock::new(load_container);
 
@@ -68,6 +69,19 @@ pub fn memory_api() -> Result<&'static Container<MemoryApi>> {
     MEMORY_API.as_ref().map_err(|e| e.clone())
 }
 
+static COOKIE_API: LazyLock<Result<Container<CookieApi>>> = LazyLock::new(|| {
+    let result = load_container::<CookieApi>();
+
+    if let Err(e) = &result {
+        eprintln!("Failed to load LabVIEW Cookie API: {e}");
+    }
+    result
+});
+
+pub fn cookie_api() -> Result<&'static Container<CookieApi>> {
+    COOKIE_API.as_ref().map_err(|e| e.clone())
+}
+
 /// The LabVIEW synchronisation features are part of the Support Manager API.
 ///
 /// The [official documentation](https://www.ni.com/docs/en-US/bundle/labview-api-ref/page/properties-and-methods/lv-manager/support-manager-functions.html) for the Support Manager can be found (last verified 2024-jul-09) on the webpage of National Instruments.
@@ -140,6 +154,34 @@ pub struct MemoryApi {
     /// `DSNewHClr` is an alternative that also initialized the memory to zero.
     #[dlopen2_name = "DSNewHandle"]
     new_handle: unsafe extern "C" fn(size: usize) -> *mut *mut std::ffi::c_void,
+    
+    /// UPtr DSNewPtr(size);
+    /// 
+    /// Creates a new pointer to a non-relocatable block of memory of the specified size.
+    /// 
+    /// ```C
+    /// UPtr DSNewPtr(size_t size);
+    /// ```
+    /// 
+    /// - `size`: `size_t`, Size, in bytes, of the pointer you want to create.
+    /// 
+    /// Return Value
+    /// 
+    /// A pointer to a block of size bytes. If an error occurs, this function returns NULL.
+    #[dlopen2_name = "DSNewPtr"]
+    new_ptr: unsafe extern "C" fn(size: usize) -> UPtrValue,
+
+    /// Release the memory referenced by the specified pointer.
+    ///
+    /// ```C
+    /// MgErr DsDisposePtr(p)
+    /// ```
+    ///
+    /// - `p`: `UPtr` Pointer you wish to dispose of.
+    ///
+    /// Returns `MgErr`:  Either `noErr` or `mZoneErr`.
+    #[dlopen2_name = "DSDisposePtr"]
+    dispose_ptr: unsafe extern "C" fn(p: UPtrValue) -> LVStatusCode,
 
     /// Copies the data referenced by the handle hsrc into the handle pointed to by ph or a new handle if ph points to NULL.
     ///
@@ -244,3 +286,38 @@ pub struct MemoryApi {
         total_new_size: usize,
     ) -> LVStatusCode,
 }
+
+pub type CookieJar = *mut *mut std::ffi::c_void;
+pub struct CookieInfo;
+pub type Bool32 = i32;
+// Cleanup modes enum
+#[repr(i32)]
+enum CleanupMode {
+    CleanRemove = 0,
+    CleanExit = 1,
+    CleanOnIdle = 2,
+    CleanAfterReset = 3,
+    CleanOnIdleIfNotTop = 4,
+    CleanAfterResetIfNotTop = 5,
+}
+type CleanupProcPtr = extern "C" fn(usize) -> i32;
+
+#[derive(WrapperApi)]
+pub struct CookieApi {
+    #[dlopen2_name = "MCNewBigJar"]
+    new_big_jar: unsafe extern "C" fn(item_size: i32) -> CookieJar,
+    #[dlopen2_name = "MCDisposeJar"]
+    dispose_jar: unsafe extern "C" fn(jar: CookieJar) -> MgError,
+    #[dlopen2_name = "MCNewCookie"]
+    new_cookie: unsafe extern "C" fn(jar: CookieJar, info: UPtrValue) -> MagicCookie,
+    #[dlopen2_name = "MCDisposeCookie"]
+    dispose_cookie: unsafe extern "C" fn(jar: CookieJar, cookie: MagicCookie, info: UPtrValue) -> LVStatusCode,
+    #[dlopen2_name = "MCGetCookieInfo"]
+    get_cookie_info: unsafe extern "C" fn(jar: CookieJar, cookie: MagicCookie, info: UPtrValue) -> LVStatusCode,
+    #[dlopen2_name = "MCGetCookieInfoPtr"]
+    get_cookie_info_ptr: unsafe extern "C" fn(jar: CookieJar, cookie: MagicCookie, info: *mut UPtrValue) -> LVStatusCode,
+    #[dlopen2_name = "MCIsACookie"]
+    is_a_cookie: unsafe extern "C" fn(jar: CookieJar, cookie: MagicCookie) -> Bool32,
+    #[dlopen2_name = "RTSetCleanupProc"]
+    rt_set_cleanup_proc: unsafe extern "C" fn(proc: CleanupProcPtr, data_uptr: UPtrValue, cleanup_mode: CleanupMode) -> LVStatusCode,
+}

labview-interop/src/memory/mod.rs

@@ -6,6 +6,10 @@
 mod owned_handle;
 mod uhandle;
 mod uptr;
+#[cfg(feature = "link")]
+mod refnum;
+#[cfg(feature = "link")]
+mod owned_uptr;
 
 use std::fmt::Debug;
 
@@ -25,8 +29,18 @@ impl<T: Copy> LVCopy for T {}
 #[doc(hidden)]
 pub struct MagicCookie(u32);
 
+impl MagicCookie {
+    pub const fn null() -> Self {
+        Self(0)
+    }
+}
+
 #[cfg(feature = "link")]
 pub use owned_handle::OwnedUHandle;
+#[cfg(feature = "link")]
+pub use owned_uptr::OwnedUPtr;
+#[cfg(feature = "link")]
+pub use refnum::{RefNum, CookieJar};
 pub use uhandle::UHandle;
 pub use uptr::UPtr;
 

labview-interop/src/memory/owned_uptr.rs

@@ -0,0 +1,82 @@
+use std::mem::MaybeUninit;
+use std::ops::{Deref, DerefMut};
+use crate::errors::LVInteropError;
+use crate::labview::memory_api;
+use crate::memory::UPtr;
+
+/// An owned UPtr which means we implement drop to free the memory.
+///
+/// This should be used with caution to avoid double free.
+///
+/// Functionally this is equivalent to a Box<T>
+#[derive(Debug)]
+pub struct OwnedUPtr<T: 'static>(UPtr<'static, T>);
+
+impl<T> OwnedUPtr<T> {
+    pub fn new_uninit() -> Result<MaybeUninit<Self>, LVInteropError> {
+        unsafe {
+            let allocated = memory_api()?.new_ptr(size_of::<T>()) as *mut T;
+            Ok(MaybeUninit::new(Self(UPtr::from_raw(allocated))))
+        }
+    }
+    /// Allocate a new UPtr with the provided data. This then operates
+    /// like the `Box` type.
+    ///
+    /// You can then use this like a UPtr type but it will be freed on drop.
+    ///
+    /// ## Errors
+    ///
+    /// This can error if the memory API is unavailable.
+    pub fn new(data: T) -> Result<Self, LVInteropError> {
+        let pointer = unsafe {
+            let allocated = memory_api()?.new_ptr(size_of::<T>()) as *mut T;
+            *allocated = data;
+            UPtr::from_raw(allocated)
+        };
+        Ok(Self(pointer))
+    }
+
+    /// Get back to an owned type for a UPtr that you know
+    /// you need to free when you are finished with it.
+    ///
+    /// This is analogous to `Box::from_raw` and requires
+    /// management across FFI boundaries.
+    ///
+    /// ## Safety
+    ///
+    /// This will be freed when dropped. Ensure you are
+    /// responsible for the drop to avoid double frees.
+    pub unsafe fn from_raw(ptr: UPtr<'static, T>) -> Self {
+        Self(ptr)
+    }
+    
+    /// Get the value as a UPtr
+    pub fn as_inner(&self) -> UPtr<'_, T> {
+        unsafe {
+            UPtr::from_raw(self.0.as_uptr_value() as *mut T)
+        }
+    }
+}
+
+impl<T: Sized> Drop for OwnedUPtr<T> {
+    fn drop(&mut self) {
+        if let Some(memory_api) = memory_api().ok() {
+            unsafe {
+                memory_api.dispose_ptr(self.0.as_uptr_value());
+            }
+        }
+    }
+}
+
+impl<T> Deref for OwnedUPtr<T> {
+    type Target = UPtr<'static, T>;
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+impl<T> DerefMut for OwnedUPtr<T> {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.0
+    }
+}

labview-interop/src/memory/refnum.rs

@@ -0,0 +1,84 @@
+//! This module wraps the "Cookie Jar" functionality of LabVIEW to allow
+//! you to create your own unique references in LabVIEW.
+
+use std::marker::PhantomData;
+use crate::labview::{cookie_api};
+use crate::memory::{MagicCookie, UPtr, OwnedUPtr};
+
+pub type Result<T> = crate::errors::Result<T>;
+
+pub struct CookieJar<T: Sync> {
+    jar: crate::labview::CookieJar,
+    phantom_data: PhantomData<T>
+}
+//todo: Need to think about these.
+unsafe impl<T: Sync> Send for CookieJar<T> {}
+unsafe impl<T: Sync> Sync for CookieJar<T> {}
+
+impl<T: Sync + 'static> CookieJar<T> {
+    pub fn new() -> Result<Self> {
+        let jar = unsafe {
+            cookie_api()?.new_big_jar(size_of::<T>() as i32)
+        };
+        Ok(Self {
+            jar,
+            phantom_data: PhantomData
+        })
+    }
+
+    pub fn new_refnum(&mut self, cookie_info: UPtr<T>) -> Result<RefNum<T>> {
+        let cookie = unsafe {
+            cookie_api()?.new_cookie(self.jar, cookie_info.as_uptr_value())
+        };
+        Ok(RefNum {
+            cookie,
+            phantom_data: PhantomData
+        })
+
+    }
+
+    pub fn cookie_info(&self, ref_num: RefNum<T>) -> Result<OwnedUPtr<T>> {
+        unsafe {
+            let ptr = OwnedUPtr::<T>::new_uninit()?;
+            let uptr_raw = ptr.as_ptr().as_ref().unwrap().as_uptr_value();
+            cookie_api()?.get_cookie_info(self.jar, ref_num.cookie, uptr_raw).to_specific_result(())?;
+            Ok(ptr.assume_init())
+        }
+
+    }
+
+    pub fn dispose_refnum(&mut self, ref_num: RefNum<T>) -> Result<()>{
+        let info = self.cookie_info(ref_num)?;
+        unsafe {
+            cookie_api()?.dispose_cookie(self.jar, ref_num.cookie, info.as_uptr_value()).to_specific_result(())?;
+        }
+        todo!("Cleanup Routine")
+    }
+}
+
+#[derive(Debug)]
+#[repr(transparent)]
+pub struct RefNum<T> {
+    cookie: MagicCookie,
+    phantom_data: PhantomData<T>
+}
+
+impl<T> RefNum<T> {
+    pub fn null() -> Self {
+        Self {
+            cookie: MagicCookie::null(),
+            phantom_data: PhantomData
+        }
+    }
+}
+
+impl<T> Clone for RefNum<T> {
+    fn clone(&self) -> Self {
+        Self {
+            cookie: self.cookie,
+            phantom_data: PhantomData
+        }
+    }
+}
+
+impl<T> Copy for RefNum<T> {}