rust_rocksdb/
ffi_util.rs

1// Copyright 2016 Alex Regueiro
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
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
16use crate::{ffi, Error};
17use libc::{self, c_char, c_void, size_t};
18use std::ffi::{CStr, CString};
19use std::path::Path;
20use std::ptr;
21
22pub(crate) unsafe fn from_cstr(ptr: *const c_char) -> String {
23    unsafe {
24        let cstr = CStr::from_ptr(ptr as *const _);
25        String::from_utf8_lossy(cstr.to_bytes()).into_owned()
26    }
27}
28
29pub(crate) unsafe fn raw_data(ptr: *const c_char, size: usize) -> Option<Vec<u8>> {
30    unsafe {
31        if ptr.is_null() {
32            None
33        } else {
34            let mut dst = vec![0; size];
35            ptr::copy_nonoverlapping(ptr as *const u8, dst.as_mut_ptr(), size);
36
37            Some(dst)
38        }
39    }
40}
41
42pub fn error_message(ptr: *const c_char) -> String {
43    unsafe {
44        let s = from_cstr(ptr);
45        ffi::rocksdb_free(ptr as *mut c_void);
46        s
47    }
48}
49
50/// Returns a raw pointer to borrowed bytes, or null if None.
51///
52/// # Safety
53/// - The input must outlive the returned pointer.
54/// - Common types: `&str`, `&[u8]`, `&String`, `&Vec<u8>`
55pub fn opt_bytes_to_ptr<T: AsRef<[u8]> + ?Sized>(opt: Option<&T>) -> *const c_char {
56    match opt {
57        Some(v) => v.as_ref().as_ptr() as *const c_char,
58        None => ptr::null(),
59    }
60}
61
62pub(crate) fn to_cpath<P: AsRef<Path>>(path: P) -> Result<CString, Error> {
63    match CString::new(path.as_ref().to_string_lossy().as_bytes()) {
64        Ok(c) => Ok(c),
65        Err(e) => Err(Error::new(format!(
66            "Failed to convert path to CString: {e}"
67        ))),
68    }
69}
70
71macro_rules! ffi_try {
72    ( $($function:ident)::*() ) => {
73        ffi_try_impl!($($function)::*())
74    };
75
76    ( $($function:ident)::*( $arg1:expr $(, $arg:expr)* $(,)? ) ) => {
77        ffi_try_impl!($($function)::*($arg1 $(, $arg)* ,))
78    };
79}
80
81macro_rules! ffi_try_impl {
82    ( $($function:ident)::*( $($arg:expr,)*) ) => {{
83        let mut err: *mut ::libc::c_char = ::std::ptr::null_mut();
84        let result = $($function)::*($($arg,)* &mut err);
85        if !err.is_null() {
86            return Err(Error::new($crate::ffi_util::error_message(err)));
87        }
88        result
89    }};
90}
91
92/// Value which can be converted into a C string.
93///
94/// The trait is used as argument to functions which wish to accept either
95/// [`&str`] or [`&CStr`](CStr) arguments while internally need to interact with
96/// C APIs.  Accepting [`&str`] may be more convenient for users but requires
97/// conversion into [`CString`] internally which requires allocation.  With this
98/// trait, latency-conscious users may choose to prepare [`CStr`] in advance and
99/// then pass it directly without having to incur the conversion cost.
100///
101/// To use the trait, function should accept `impl CStrLike` and after baking
102/// the argument (with [`CStrLike::bake`] method) it can use it as a [`&CStr`](CStr)
103/// (since the baked result dereferences into [`CStr`]).
104///
105/// # Example
106///
107/// ```
108/// use std::ffi::{CStr, CString};
109/// use rust_rocksdb::CStrLike;
110///
111/// fn strlen(arg: impl CStrLike) -> std::result::Result<usize, String> {
112///     let baked = arg.bake().map_err(|err| err.to_string())?;
113///     Ok(unsafe { libc::strlen(baked.as_ptr()) })
114/// }
115///
116/// const FOO: &str = "foo";
117/// const BAR: &CStr = unsafe { CStr::from_bytes_with_nul_unchecked(b"bar\0") };
118///
119/// assert_eq!(Ok(3), strlen(FOO));
120/// assert_eq!(Ok(3), strlen(BAR));
121/// ```
122pub trait CStrLike {
123    type Baked: std::ops::Deref<Target = CStr>;
124    type Error: std::fmt::Debug + std::fmt::Display;
125
126    /// Bakes self into value which can be freely converted into [`&CStr`](CStr).
127    ///
128    /// This may require allocation and may fail if `self` has invalid value.
129    fn bake(self) -> Result<Self::Baked, Self::Error>;
130
131    /// Consumers and converts value into an owned [`CString`].
132    ///
133    /// If `Self` is already a `CString` simply returns it; if it’s a reference
134    /// to a `CString` then the value is cloned.  In other cases this may
135    /// require allocation and may fail if `self` has invalid value.
136    fn into_c_string(self) -> Result<CString, Self::Error>;
137}
138
139impl CStrLike for &str {
140    type Baked = CString;
141    type Error = std::ffi::NulError;
142
143    fn bake(self) -> Result<Self::Baked, Self::Error> {
144        CString::new(self)
145    }
146    fn into_c_string(self) -> Result<CString, Self::Error> {
147        CString::new(self)
148    }
149}
150
151// This is redundant for the most part and exists so that `foo(&string)` (where
152// `string: String` works just as if `foo` took `arg: &str` argument.
153impl CStrLike for &String {
154    type Baked = CString;
155    type Error = std::ffi::NulError;
156
157    fn bake(self) -> Result<Self::Baked, Self::Error> {
158        CString::new(self.as_bytes())
159    }
160    fn into_c_string(self) -> Result<CString, Self::Error> {
161        CString::new(self.as_bytes())
162    }
163}
164
165impl CStrLike for &CStr {
166    type Baked = Self;
167    type Error = std::convert::Infallible;
168
169    fn bake(self) -> Result<Self::Baked, Self::Error> {
170        Ok(self)
171    }
172    fn into_c_string(self) -> Result<CString, Self::Error> {
173        Ok(self.to_owned())
174    }
175}
176
177// This exists so that if caller constructs a `CString` they can pass it into
178// the function accepting `CStrLike` argument.  Some of such functions may take
179// the argument whereas otherwise they would need to allocated a new owned
180// object.
181impl CStrLike for CString {
182    type Baked = CString;
183    type Error = std::convert::Infallible;
184
185    fn bake(self) -> Result<Self::Baked, Self::Error> {
186        Ok(self)
187    }
188    fn into_c_string(self) -> Result<CString, Self::Error> {
189        Ok(self)
190    }
191}
192
193// This is redundant for the most part and exists so that `foo(&cstring)` (where
194// `string: CString` works just as if `foo` took `arg: &CStr` argument.
195impl<'a> CStrLike for &'a CString {
196    type Baked = &'a CStr;
197    type Error = std::convert::Infallible;
198
199    fn bake(self) -> Result<Self::Baked, Self::Error> {
200        Ok(self)
201    }
202    fn into_c_string(self) -> Result<CString, Self::Error> {
203        Ok(self.clone())
204    }
205}
206
207/// Owned malloc-allocated memory slice.
208/// Do not derive `Clone` for this because it will cause double-free.
209pub struct CSlice {
210    data: *const c_char,
211    len: size_t,
212}
213
214impl CSlice {
215    /// Constructing such a slice may be unsafe.
216    ///
217    /// # Safety
218    /// The caller must ensure that the pointer and length are valid.
219    /// Moreover, `CSlice` takes the ownership of the memory and will free it
220    /// using `rocksdb_free`. The caller must ensure that the memory is
221    /// allocated by `malloc` in RocksDB and will not be freed by any other
222    /// means.
223    pub(crate) unsafe fn from_raw_parts(data: *const c_char, len: size_t) -> Self {
224        Self { data, len }
225    }
226}
227
228impl AsRef<[u8]> for CSlice {
229    fn as_ref(&self) -> &[u8] {
230        unsafe { std::slice::from_raw_parts(self.data as *const u8, self.len) }
231    }
232}
233
234impl Drop for CSlice {
235    fn drop(&mut self) {
236        unsafe {
237            ffi::rocksdb_free(self.data as *mut c_void);
238        }
239    }
240}
241
242#[test]
243fn test_c_str_like_bake() {
244    fn test<S: CStrLike>(value: S) -> Result<usize, S::Error> {
245        value
246            .bake()
247            .map(|value| unsafe { libc::strlen(value.as_ptr()) })
248    }
249
250    assert_eq!(Ok(3), test("foo")); // &str
251    assert_eq!(Ok(3), test(&String::from("foo"))); // String
252    assert_eq!(Ok(3), test(CString::new("foo").unwrap().as_ref())); // &CStr
253    assert_eq!(Ok(3), test(&CString::new("foo").unwrap())); // &CString
254    assert_eq!(Ok(3), test(CString::new("foo").unwrap())); // CString
255
256    assert_eq!(3, test("foo\0bar").err().unwrap().nul_position());
257}
258
259#[test]
260fn test_c_str_like_into() {
261    fn test<S: CStrLike>(value: S) -> Result<CString, S::Error> {
262        value.into_c_string()
263    }
264
265    let want = CString::new("foo").unwrap();
266
267    assert_eq!(Ok(want.clone()), test("foo")); // &str
268    assert_eq!(Ok(want.clone()), test(&String::from("foo"))); // &String
269    assert_eq!(
270        Ok(want.clone()),
271        test(CString::new("foo").unwrap().as_ref())
272    ); // &CStr
273    assert_eq!(Ok(want.clone()), test(&CString::new("foo").unwrap())); // &CString
274    assert_eq!(Ok(want), test(CString::new("foo").unwrap())); // CString
275
276    assert_eq!(3, test("foo\0bar").err().unwrap().nul_position());
277}
rust_rocksdb/ffi_util.rs

rust_rocksdb/
ffi_util.rs
