Struct uniffi::ffi::rustbuffer::RustBuffer

#[repr(C)]
pub struct RustBuffer { /* fields omitted */ }

Support for passing an allocated-by-Rust buffer of bytes over the FFI.

We can pass a Vec<u8> to foreign language code by decomposing it into its raw parts (buffer pointer, length, and capacity) and passing those around as a struct. Naturally, this can be tremendously unsafe! So here are the details:

• RustBuffer structs must only ever be constructed from a Vec<u8>, either explicitly via RustBuffer::from_vec or indirectly by calling one of the RustBuffer::new* constructors.

• RustBuffer structs do not implement Drop, since they are intended to be passed to foreign-language code outside of the control of Rust’s ownership system. To avoid memory leaks they must passed back into Rust and either explicitly destroyed using RustBuffer::destroy, or converted back to a Vec<u8> using RustBuffer::destroy_into_vec (which will then be dropped via Rust’s usual ownership-tracking system).

Foreign-language code should not construct RustBuffer structs other than by receiving them from a call into the Rust code, and should not modify them apart from the following safe operations:

• Writing bytes into the buffer pointed to by data, without writing beyond the indicated capacity.

• Adjusting the len property to indicate the amount of data written, while ensuring that 0 <= len <= capacity.

• As a special case, constructing a RustBuffer with zero capacity, zero length, and a null data pointer to indicate an empty buffer.

In particular, it is not safe for foreign-language code to construct a RustBuffer that points to its own allocated memory; use the ForeignBytes struct to pass a view of foreign-owned memory in to Rust code.

Implementation note: all the fields of this struct are private, so you can’t manually construct instances that don’t come from a Vec<u8>. If you’ve got a RustBuffer then it either came from a public constructor (all of which are safe) or it came from foreign-language code (which should have in turn received it by calling some Rust function, and should be respecting the invariants listed above).

This struct is based on ByteBuffer from the ffi-support crate, but modified to retain unallocated capacity rather than truncating to the occupied length.

Implementations

impl RustBuffer

pub fn new() -> Self

Creates an empty RustBuffer.

The resulting vector will not be automatically dropped; you must arrange to call destroy or destroy_into_vec when finished with it.

pub unsafe fn from_raw_parts(data: *mut u8, len: i32, capacity: i32) -> Self

Creates a RustBuffer from its constituent fields.

This is intended mainly as an internal convenience function and should not be used outside of this module.

Safety

You must ensure that the raw parts uphold the documented invariants of this class.

pub fn len(&self) -> usize

Get the current length of the buffer, as a usize.

This is mostly a helper function to convert the i32 length field into a usize, which is what Rust code usually expects.

Panics

Panics if called on an invalid struct obtained from foreign-language code, in which the len field is negative.

pub fn is_empty(&self) -> bool

Returns true if the length of the buffer is 0.

pub fn new_with_size(size: usize) -> Self

Creates a RustBuffer zero-filed to the requested size.

The resulting vector will not be automatically dropped; you must arrange to call destroy or destroy_into_vec when finished with it.

Panics

Panics if the requested size is too large to fit in an i32, and hence would risk incompatibility with some foreign-language code.

pub fn from_vec(v: Vec<u8>) -> Self

Consumes a Vec<u8> and returns its raw parts as a RustBuffer.

The resulting vector will not be automatically dropped; you must arrange to call destroy or destroy_into_vec when finished with it.

Panics

Panics if the vector’s length or capacity are too large to fit in an i32, and hence would risk incompatibility with some foreign-language code.

pub fn destroy_into_vec(self) -> Vec<u8>

Converts this RustBuffer back into an owned Vec<u8>.

This restores ownership of the underlying buffer to Rust, meaning it will be dropped when the Vec<u8> is dropped. The RustBuffer must have been previously obtained from a valid Vec<u8> owned by this Rust code.

Panics

Panics if called on an invalid struct obtained from foreign-language code, which does not respect the invairiants on len and capacity.

pub fn destroy(self)

Reclaim memory stored in this RustBuffer.

Panics

Panics if called on an invalid struct obtained from foreign-language code, which does not respect the invairiants on len and capacity.

Trait Implementations

impl Default for RustBuffer

fn default() -> Self

Returns the “default value” for a type.

impl IntoFfi for RustBuffer

type Value = Self

This type must be:

fn ffi_default() -> Self

Return an ‘empty’ value. This is what’s passed back to C in the case of an error, so it doesn’t actually need to be “empty”, so much as “ignorable”. Note that this is also used when an empty Option<T> is returned.

fn into_ffi_value(self) -> Self::Value

Convert ourselves into a value we can pass back to C with confidence.