Struct DiplomatWrite 

#[repr(C)]
pub struct DiplomatWrite {
    context: *mut c_void,
    buf: *mut u8,
    len: usize,
    cap: usize,
    grow_failed: bool,
    flush: extern "C" fn(*mut DiplomatWrite),
    grow: extern "C" fn(*mut DiplomatWrite, usize) -> bool,
}

An object that can one can write UTF-8 strings to

This allows the C API to write to arbitrary kinds of objects, for example a C++ std::string or a char buffer.

The way to use this object is to fill out the buf, len, cap fields with appropriate values for the buffer, its current length, and its current capacity, and flush and grow with appropriate callbacks (using context to reference any state they need). This object will be passed by mutable reference to the Rust side, and Rust will write to it, calling grow() as necessary. Once done, it will call flush() to update any state on context (e.g. adding a null terminator, updating the length). The object on the foreign side will be directly usable after this, the foreign side need not perform additional state updates after passing an DiplomatWrite to a function.

May be extended in the future to support further invariants

DiplomatWrite will not perform any cleanup on context or buf, these are logically “borrows” from the FFI side.

DiplomatWrite is Polymorphic

Instances of DiplomatWrite can be created from multiple different sources. There are two constructors available in diplomat_runtime:

1. diplomat_simple_write() to write to a fixed-size buffer.
2. diplomat_buffer_write_create() to write to a Vec allocated by Rust. A wrapper is provided: RustWriteVec.

Backends may have additional constructors for writing to various shapes of buffer.

⚠️ Because DiplomatWrite is polymorphic, the destructor must know how the instance was constructed. It is therefore unsound to use functions such as core::mem::swap on instances of DiplomatWrite with potentially different sources. For example, the following code is not safe:

use diplomat_runtime::DiplomatWrite;
fn bad(write: &mut DiplomatWrite) {
  let mut some_other_write: DiplomatWrite = unimplemented!();
  // Not safe! The two `DiplomatWrite`s have different invariants
  core::mem::swap(write, &mut some_other_write);
}

As a result, any function that returns an owned DiplomatWrite or a &mut DiplomatWrite must be unsafe. For an example, see [RustWriteVec::borrow_mut].

Diplomat backends guarantee they will only ever hand the same type of DiplomatWrite object to Rust code; this is only something you need to worry about if using RustWriteVec, or DiplomatWrite objects manually created in Rust via APIs like diplomat_simple_write.

Safety invariants:

• flush() and grow() will be passed self including context and it should always be safe to do so. context may be null, however flush() and grow() must then be ready to receive it as such.
• buf must be a valid pointer to cap bytes of memory
• buf must point to len consecutive properly initialized bytes
• cap must be less than or equal to isize::MAX
• grow() must either return false or update buf and cap for a valid buffer of at least the requested buffer size.
• If grow_failed is true all safety invariants on buf/cap/len MUST still hold.
• DiplomatWrite::flush() will be automatically called by Diplomat. flush() might also be called (erroneously) on the Rust side (it’s a public method), so it must be idempotent.

Fields

context: *mut c_void

Context pointer for additional data needed by grow() and flush(). May be null.

The pointer may reference structured data on the foreign side, such as C++ std::string, used to reallocate buf.

buf: *mut u8

The raw string buffer, which will be mutated on the Rust side.

len: usize

The current filled size of the buffer

cap: usize

The current capacity of the buffer

grow_failed: bool

Set to true if grow ever fails.

flush: extern "C" fn(*mut DiplomatWrite)

Called by Rust to indicate that there is no more data to write.

May be called multiple times.

Arguments:

• self (*mut DiplomatWrite): This DiplomatWrite

grow: extern "C" fn(*mut DiplomatWrite, usize) -> bool

Called by Rust to request more capacity in the buffer. The implementation should allocate a new buffer and copy the contents of the old buffer into the new buffer, updating self.buf and self.cap

Arguments:

• self (*mut DiplomatWrite): This DiplomatWrite
• capacity (usize): The requested capacity.

Returns: true if the allocation succeeded. Should not update any state if it failed.

Implementations

impl DiplomatWrite

pub fn flush(&mut self)

Call this function before releasing the buffer to C

pub fn as_bytes(&self) -> &[u8]

Returns a pointer to the buffer’s bytes.

If growth has failed, this returns what has been written so far.

Trait Implementations

impl Borrow<DiplomatWrite> for RustWriteVec

fn borrow(&self) -> &DiplomatWrite

Immutably borrows from an owned value.

impl Write for DiplomatWrite

fn write_str(&mut self, s: &str) -> Result<(), Error>

Writes a string slice into this writer, returning whether the write succeeded.

fn write_char(&mut self, c: char) -> Result<(), Error>

Writes a char into this writer, returning whether the write succeeded.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Glue for usage of the write! macro with implementors of this trait.