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

rocksdb/
ffi_util.rs
