Crate uninit_read 

A marker trait and utilities for safe, high-performance reads into uninitialized buffers.

The Problem

The standard I/O traits, std::io::Read and futures::io::AsyncRead, require a &mut [u8] buffer. By Rust’s safety rules, this slice must be fully initialized. In performance-critical applications, the cost of zeroing a large buffer before a read can be significant.

The common workaround is to create an uninitialized buffer and unsafely cast it to &mut [u8]:

use std::mem::MaybeUninit;

let mut uninit_buf = MaybeUninit::<[u8; 8192] >::uninit();

// This is potentially UNDEFINED BEHAVIOR!
let buf_slice = unsafe { uninit_buf.assume_init_mut() };
// reader.read(buf_slice)?;

This is dangerous because the Read contract does not forbid the implementation from reading from the buffer before writing to it. While most readers don’t, the caller is relying on an unverified implementation detail.

A Solution: UninitRead

This crate provides a single, unsafe marker trait that formalizes this contract:

pub unsafe trait UninitRead {}

By implementing UninitRead for a reader type, an author makes a guarantee:

The reader implementation will not read from any part of the provided buffer that has not been written to by the implementation itself within the same call. It must treat the buffer as if it were completely uninitialized on entry.

This contract makes it sound for callers to use an uninitialized buffer with any reader that implements UninitRead.

Modules

impls

This module provides UninitRead implementations for common Read and AsyncRead types.

Structs

AssumeUninitRead

A wrapper that asserts a reader upholds the UninitRead contract.

Traits

UninitAsyncReadExt

An extension trait that provides convenience methods for asynchronous readers that implement UninitRead.

UninitRead

A marker trait for readers that are safe to use with uninitialized buffers.

UninitSyncReadExt

An extension trait that provides convenience methods for synchronous readers that implement UninitRead.

Functions

is_uninit_read

Checks at runtime if a type implements the UninitRead trait.