| 1 |
use alloc::boxed::Box; |
| 2 |
use alloc::vec::Vec; |
| 3 |
use core::ffi::c_void; |
| 4 |
use core::{fmt, ptr}; |
| 5 |
|
| 6 |
/// An object that can one can write UTF-8 strings to |
| 7 |
/// |
| 8 |
/// This allows the C API to write to arbitrary kinds of objects, for example a |
| 9 |
/// C++ std::string or a char buffer. |
| 10 |
/// |
| 11 |
/// The way to use this object is to fill out the `buf`, `len`, `cap` fields with |
| 12 |
/// appropriate values for the buffer, its current length, and its current capacity, |
| 13 |
/// and `flush` and `grow` with appropriate callbacks (using `context` to reference any |
| 14 |
/// state they need). This object will be passed by mutable reference to the Rust side, |
| 15 |
/// and Rust will write to it, calling `grow()` as necessary. Once done, it will call `flush()` |
| 16 |
/// to update any state on `context` (e.g. adding a null terminator, updating the length). |
| 17 |
/// The object on the foreign side will be directly usable after this, the foreign side |
| 18 |
/// need not perform additional state updates after passing an [`DiplomatWriteable`] to |
| 19 |
/// a function. |
| 20 |
/// |
| 21 |
/// [`diplomat_simple_writeable()`] can be used to write to a fixed-size char buffer. |
| 22 |
/// |
| 23 |
/// May be extended in the future to support further invariants |
| 24 |
/// |
| 25 |
/// DiplomatWriteable will not perform any cleanup on `context` or `buf`, these are logically |
| 26 |
/// "borrows" from the FFI side. |
| 27 |
/// |
| 28 |
/// # Safety invariants: |
| 29 |
/// - `flush()` and `grow()` will be passed `self` including `context` and it should always be safe to do so. |
| 30 |
/// `context` may be null, however `flush()` and `grow()` must then be ready to receive it as such. |
| 31 |
/// - `buf` must be `cap` bytes long |
| 32 |
/// - `grow()` must either return false or update `buf` and `cap` for a valid buffer |
| 33 |
/// of at least the requested buffer size |
| 34 |
/// - `DiplomatWriteable::flush()` will be automatically called by Diplomat. `flush()` might also be called |
| 35 |
/// (erroneously) on the Rust side (it's a public method), so it must be idempotent. |
| 36 |
#[repr(C)] |
| 37 |
pub struct DiplomatWriteable { |
| 38 |
/// Context pointer for additional data needed by `grow()` and `flush()`. May be `null`. |
| 39 |
/// |
| 40 |
/// The pointer may reference structured data on the foreign side, |
| 41 |
/// such as C++ std::string, used to reallocate buf. |
| 42 |
context: *mut c_void, |
| 43 |
/// The raw string buffer, which will be mutated on the Rust side. |
| 44 |
buf: *mut u8, |
| 45 |
/// The current filled size of the buffer |
| 46 |
len: usize, |
| 47 |
/// The current capacity of the buffer |
| 48 |
cap: usize, |
| 49 |
/// Called by Rust to indicate that there is no more data to write. |
| 50 |
/// |
| 51 |
/// May be called multiple times. |
| 52 |
/// |
| 53 |
/// Arguments: |
| 54 |
/// - `self` (`*mut DiplomatWriteable`): This `DiplomatWriteable` |
| 55 |
flush: extern "C" fn(*mut DiplomatWriteable), |
| 56 |
/// Called by Rust to request more capacity in the buffer. The implementation should allocate a new |
| 57 |
/// buffer and copy the contents of the old buffer into the new buffer, updating `self.buf` and `self.cap` |
| 58 |
/// |
| 59 |
/// Arguments: |
| 60 |
/// - `self` (`*mut DiplomatWriteable`): This `DiplomatWriteable` |
| 61 |
/// - `capacity` (`usize`): The requested capacity. |
| 62 |
/// |
| 63 |
/// Returns: `true` if the allocation succeeded. Should not update any state if it failed. |
| 64 |
grow: extern "C" fn(*mut DiplomatWriteable, usize) -> bool, |
| 65 |
} |
| 66 |
|
| 67 |
impl DiplomatWriteable { |
| 68 |
/// Call this function before releasing the buffer to C |
| 69 |
pub fn flush(&mut self) { |
| 70 |
(self.flush)(self); |
| 71 |
} |
| 72 |
} |
| 73 |
impl fmt::Write for DiplomatWriteable { |
| 74 |
fn write_str(&mut self, s: &str) -> Result<(), fmt::Error> { |
| 75 |
let needed_len = self.len + s.len(); |
| 76 |
if needed_len > self.cap { |
| 77 |
let success = (self.grow)(self, needed_len); |
| 78 |
if !success { |
| 79 |
return Err(fmt::Error); |
| 80 |
} |
| 81 |
} |
| 82 |
debug_assert!(needed_len <= self.cap); |
| 83 |
unsafe { |
| 84 |
ptr::copy_nonoverlapping(s.as_bytes().as_ptr(), self.buf.add(self.len), s.len()); |
| 85 |
} |
| 86 |
self.len = needed_len; |
| 87 |
Ok(()) |
| 88 |
} |
| 89 |
} |
| 90 |
|
| 91 |
/// Create an `DiplomatWriteable` that can write to a fixed-length stack allocated `u8` buffer. |
| 92 |
/// |
| 93 |
/// Once done, this will append a null terminator to the written string. |
| 94 |
/// |
| 95 |
/// # Safety |
| 96 |
/// |
| 97 |
/// - `buf` must be a valid pointer to a region of memory that can hold at `buf_size` bytes |
| 98 |
#[no_mangle] |
| 99 |
pub unsafe extern "C" fn diplomat_simple_writeable( |
| 100 |
buf: *mut u8, |
| 101 |
buf_size: usize, |
| 102 |
) -> DiplomatWriteable { |
| 103 |
extern "C" fn grow(_this: *mut DiplomatWriteable, _cap: usize) -> bool { |
| 104 |
false |
| 105 |
} |
| 106 |
extern "C" fn flush(this: *mut DiplomatWriteable) { |
| 107 |
unsafe { |
| 108 |
debug_assert!((*this).len <= (*this).cap); |
| 109 |
let buf = (*this).buf; |
| 110 |
ptr::write(buf.add((*this).len), 0) |
| 111 |
} |
| 112 |
} |
| 113 |
DiplomatWriteable { |
| 114 |
context: ptr::null_mut(), |
| 115 |
buf, |
| 116 |
len: 0, |
| 117 |
// keep an extra byte in our pocket for the null terminator |
| 118 |
cap: buf_size - 1, |
| 119 |
flush, |
| 120 |
grow, |
| 121 |
} |
| 122 |
} |
| 123 |
|
| 124 |
/// Create an [`DiplomatWriteable`] that can write to a dynamically allocated buffer managed by Rust. |
| 125 |
/// |
| 126 |
/// Use [`diplomat_buffer_writeable_destroy()`] to free the writable and its underlying buffer. |
| 127 |
#[no_mangle] |
| 128 |
pub extern "C" fn diplomat_buffer_writeable_create(cap: usize) -> *mut DiplomatWriteable { |
| 129 |
extern "C" fn grow(this: *mut DiplomatWriteable, new_cap: usize) -> bool { |
| 130 |
unsafe { |
| 131 |
let this = this.as_mut().unwrap(); |
| 132 |
let mut vec = Vec::from_raw_parts(this.buf, 0, this.cap); |
| 133 |
vec.reserve(new_cap); |
| 134 |
this.cap = vec.capacity(); |
| 135 |
this.buf = vec.as_mut_ptr(); |
| 136 |
core::mem::forget(vec); |
| 137 |
} |
| 138 |
true |
| 139 |
} |
| 140 |
|
| 141 |
extern "C" fn flush(_: *mut DiplomatWriteable) {} |
| 142 |
|
| 143 |
let mut vec = Vec::<u8>::with_capacity(cap); |
| 144 |
let ret = DiplomatWriteable { |
| 145 |
context: ptr::null_mut(), |
| 146 |
buf: vec.as_mut_ptr(), |
| 147 |
len: 0, |
| 148 |
cap, |
| 149 |
flush, |
| 150 |
grow, |
| 151 |
}; |
| 152 |
|
| 153 |
core::mem::forget(vec); |
| 154 |
Box::into_raw(Box::new(ret)) |
| 155 |
} |
| 156 |
|
| 157 |
/// Grabs a pointer to the underlying buffer of a writable. |
| 158 |
/// |
| 159 |
/// # Safety |
| 160 |
/// - The returned pointer is valid until the passed writable is destroyed. |
| 161 |
/// - `this` must be a pointer to a valid [`DiplomatWriteable`] constructed by |
| 162 |
/// [`diplomat_buffer_writeable_create()`]. |
| 163 |
#[no_mangle] |
| 164 |
pub extern "C" fn diplomat_buffer_writeable_get_bytes(this: &DiplomatWriteable) -> *mut u8 { |
| 165 |
this.buf |
| 166 |
} |
| 167 |
|
| 168 |
/// Gets the length in bytes of the content written to the writable. |
| 169 |
/// |
| 170 |
/// # Safety |
| 171 |
/// - `this` must be a pointer to a valid [`DiplomatWriteable`] constructed by |
| 172 |
/// [`diplomat_buffer_writeable_create()`]. |
| 173 |
#[no_mangle] |
| 174 |
pub extern "C" fn diplomat_buffer_writeable_len(this: &DiplomatWriteable) -> usize { |
| 175 |
this.len |
| 176 |
} |
| 177 |
|
| 178 |
/// Destructor for Rust-memory backed writables. |
| 179 |
/// |
| 180 |
/// # Safety |
| 181 |
/// - `this` must be a pointer to a valid [`DiplomatWriteable`] constructed by |
| 182 |
/// [`diplomat_buffer_writeable_create()`]. |
| 183 |
#[no_mangle] |
| 184 |
pub unsafe extern "C" fn diplomat_buffer_writeable_destroy(this: *mut DiplomatWriteable) { |
| 185 |
let this = Box::from_raw(this); |
| 186 |
let vec = Vec::from_raw_parts(this.buf, 0, this.cap); |
| 187 |
drop(vec); |
| 188 |
drop(this); |
| 189 |
} |