nautilus_core/ffi/
cvec.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Utilities for transferring heap-allocated Rust `Vec<T>` values across an FFI boundary.
17//!
18//! The primary abstraction offered by this module is `CVec`, a C-compatible struct that stores
19//! a raw pointer (`ptr`) together with the vector’s logical `len` and `cap`.  By moving the
20//! allocation metadata into a plain `repr(C)` type we allow the memory created by Rust to be
21//! owned, inspected, and ultimately freed by foreign code (or vice-versa) without introducing
22//! undefined behaviour.
23//!
24//! Only a very small API surface is exposed to C:
25//!
26//! * `cvec_new` – create an empty `CVec` sentinel that can be returned to foreign code.
27//!
28//! De-allocation is intentionally **not** provided via a generic helper. Instead each FFI module
29//! must expose its own *type-specific* `vec_*_drop` function which reconstructs the original
30//! `Vec<T>` with [`Vec::from_raw_parts`] and allows it to drop. This avoids the size-mismatch risk
31//! that a one-size-fits-all `cvec_drop` had in the past.
32//!
33//! All other manipulation happens on the Rust side before relinquishing ownership.  This keeps the
34//! rules for memory safety straightforward: foreign callers must treat the memory region pointed
35//! to by `ptr` as **opaque** and interact with it solely through the functions provided here.
36
37use std::{ffi::c_void, fmt::Display, ptr::NonNull};
38
39use crate::ffi::abort_on_panic;
40
41/// `CVec` is a C compatible struct that stores an opaque pointer to a block of
42/// memory, its length and the capacity of the vector it was allocated from.
43///
44/// # Safety
45///
46/// Changing the values here may lead to undefined behavior when the memory is dropped.
47#[repr(C)]
48#[derive(Clone, Copy, Debug)]
49pub struct CVec {
50    /// Opaque pointer to block of memory storing elements to access the
51    /// elements cast it to the underlying type.
52    pub ptr: *mut c_void,
53    /// The number of elements in the block.
54    pub len: usize,
55    /// The capacity of vector from which it was allocated.
56    /// Used when deallocating the memory
57    pub cap: usize,
58}
59
60// SAFETY: CVec is marked as Send to satisfy PyO3's PyCapsule requirements, which need
61// to transfer ownership across the Python/Rust boundary. However, CVec contains raw
62// pointers and is only safe to use in single-threaded contexts or with external
63// synchronization guarantees.
64//
65// The Send impl is required for:
66// 1. PyO3's PyCapsule::new_with_destructor which has a Send bound
67// 2. Transferring CVec ownership to Python (which runs on a single GIL-protected thread)
68//
69// IMPORTANT: Do not send CVec instances across threads without ensuring:
70// - The underlying data type T is itself Send + Sync
71// - Proper external synchronization (e.g., mutex) protects concurrent access
72// - The CVec is consumed on the same thread where it will be reconstructed
73//
74// In practice, CVec usage in this codebase is confined to the Python FFI boundary
75// where the Python GIL provides the necessary synchronization.
76unsafe impl Send for CVec {}
77
78impl CVec {
79    /// Returns an empty [`CVec`].
80    ///
81    /// This is primarily useful for constructing a sentinel value that represents the
82    /// absence of data when crossing the FFI boundary.
83    ///
84    /// Uses a dangling pointer (like `Vec::new()`) rather than null to satisfy
85    /// `Vec::from_raw_parts` preconditions when the CVec is later dropped.
86    #[must_use]
87    pub fn empty() -> Self {
88        Self {
89            ptr: NonNull::<u8>::dangling().as_ptr().cast::<c_void>(),
90            len: 0,
91            cap: 0,
92        }
93    }
94}
95
96/// Consumes and leaks the Vec, returning a mutable pointer to the contents as
97/// a [`CVec`]. The memory has been leaked and now exists for the lifetime of the
98/// program unless dropped manually.
99/// Note: drop the memory by reconstructing the vec using `from_raw_parts` method
100/// as shown in the test below.
101impl<T> From<Vec<T>> for CVec {
102    fn from(mut data: Vec<T>) -> Self {
103        if data.is_empty() {
104            Self::empty()
105        } else {
106            let len = data.len();
107            let cap = data.capacity();
108            let ptr = data.as_mut_ptr();
109            std::mem::forget(data);
110            Self {
111                ptr: ptr.cast::<std::ffi::c_void>(),
112                len,
113                cap,
114            }
115        }
116    }
117}
118
119impl Display for CVec {
120    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
121        write!(
122            f,
123            "CVec {{ ptr: {:?}, len: {}, cap: {} }}",
124            self.ptr, self.len, self.cap,
125        )
126    }
127}
128
129////////////////////////////////////////////////////////////////////////////////
130// C API
131////////////////////////////////////////////////////////////////////////////////
132
133/// Construct a new *empty* [`CVec`] value for use as initialiser/sentinel in foreign code.
134#[cfg(feature = "ffi")]
135#[unsafe(no_mangle)]
136pub extern "C" fn cvec_new() -> CVec {
137    abort_on_panic(CVec::empty)
138}
139
140#[cfg(test)]
141mod tests {
142    use rstest::*;
143
144    use super::CVec;
145
146    /// Access values from a vector converted into a [`CVec`].
147    #[rstest]
148    #[allow(unused_assignments)]
149    fn access_values_test() {
150        let test_data = vec![1_u64, 2, 3];
151        let mut vec_len = 0;
152        let mut vec_cap = 0;
153        let cvec: CVec = {
154            let data = test_data.clone();
155            vec_len = data.len();
156            vec_cap = data.capacity();
157            data.into()
158        };
159
160        let CVec { ptr, len, cap } = cvec;
161        assert_eq!(len, vec_len);
162        assert_eq!(cap, vec_cap);
163
164        let data = ptr.cast::<u64>();
165        unsafe {
166            assert_eq!(*data, test_data[0]);
167            assert_eq!(*data.add(1), test_data[1]);
168            assert_eq!(*data.add(2), test_data[2]);
169        }
170
171        unsafe {
172            // reconstruct the struct and drop the memory to deallocate
173            let _ = Vec::from_raw_parts(ptr.cast::<u64>(), len, cap);
174        }
175    }
176
177    /// An empty vector gets converted to a dangling (non-null) pointer in a [`CVec`].
178    #[rstest]
179    fn empty_vec_should_give_dangling_ptr() {
180        let data: Vec<u64> = vec![];
181        let cvec: CVec = data.into();
182        assert!(!cvec.ptr.is_null());
183        assert_eq!(cvec.len, 0);
184        assert_eq!(cvec.cap, 0);
185    }
186}
nautilus_core/ffi/cvec.rs

nautilus_core/ffi/
cvec.rs
