pub unsafe trait UninitRead { }Expand description
A marker trait for readers that are safe to use with uninitialized buffers.
The standard I/O traits, std::io::Read and [futures::io::AsyncRead],
pass a &mut [u8] buffer to their read methods. Rust’s safety rules require
that any &mut [u8] be fully initialized. This forces users to zero-out
buffers before passing them to a read function, which can be a performance
penalty in hot code paths or high-performance workloads.
This trait provides a formal contract to address this. By implementing
UninitRead, a type guarantees that its I/O methods will not read from the
provided buffer before writing to it, making it safe for callers to pass a
buffer that contains uninitialized memory.
§Safety
This trait is unsafe because the compiler cannot verify the guarantee it
provides. The implementor of this trait must guarantee that their
implementation of Read::read() and/or AsyncRead::poll_read() will not
read from any part of the provided buffer that has not been written to
by the implementation itself.
The implementation must treat the buffer as if it were completely uninitialized at the start of the call. It is permissible to read from portions of the buffer that have been written to within the same call to a read method (e.g., for an in-place decryption routine).
Violating this contract by reading from a part of the buffer that has not yet been written to will result in undefined behavior when a consumer of this trait passes an uninitialized buffer.