Struct diplomat_runtime::DiplomatWriteable

#[repr(C)]
pub struct DiplomatWriteable {
    context: *mut c_void,
    buf: *mut u8,
    len: usize,
    cap: usize,
    flush: extern "C" fn(_: *mut DiplomatWriteable),
    grow: extern "C" fn(_: *mut DiplomatWriteable, _: 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 DiplomatWriteable to a function.

diplomat_simple_writeable() can be used to write to a fixed-size char buffer.

May be extended in the future to support further invariants

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

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 cap bytes long
• grow() must either return false or update buf and cap for a valid buffer of at least the requested buffer size
• DiplomatWriteable::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

flush: extern "C" fn(_: *mut DiplomatWriteable)

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

May be called multiple times.

Arguments:

• self (*mut DiplomatWriteable): This DiplomatWriteable

grow: extern "C" fn(_: *mut DiplomatWriteable, _: 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 DiplomatWriteable): This DiplomatWriteable
• capacity (usize): The requested capacity.

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

Implementations

impl DiplomatWriteable

pub fn flush(&mut self)

Call this function before releasing the buffer to C

Trait Implementations

impl Write for DiplomatWriteable

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.