Struct diplomat_runtime::writeable::DiplomatWriteable
source · #[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,
}
Expand description
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()
andgrow()
will be passedself
includingcontext
and it should always be safe to do so.context
may be null, howeverflush()
andgrow()
must then be ready to receive it as such.buf
must becap
bytes longgrow()
must either return false or updatebuf
andcap
for a valid buffer of at least the requested buffer sizeDiplomatWriteable::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
): ThisDiplomatWriteable
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
): ThisDiplomatWriteable
capacity
(usize
): The requested capacity.
Returns: true
if the allocation succeeded. Should not update any state if it failed.