io_arrays/
lib.rs

1//! Random-access I/O
2//!
3//! This crate defines [`ReadAt`], [`WriteAt`], and [`EditAt`] traits which
4//! define interfaces to random-access or seekable devices, such as normal
5//! files, block devices, disk partitions, and memory buffers.
6//!
7//! It also defines [`ArrayReader`], [`ArrayWriter`], and [`ArrayEditor`] types
8//! which implement the above traits and and can be constructed from any
9//! file-like type.  On Posix-ish platforms, including limited support for
10//! WASI, these types just contain a single file descriptor (and implement
11//! [`AsRawFd`]), plus any resources needed to safely hold the file descriptor
12//! live. On Windows, they contain a single file handle (and implement
13//! [`AsRawHandle`]).
14//!
15//! [`AsRawFd`]: https://doc.rust-lang.org/std/os/unix/io/trait.AsRawFd.html
16//! [`AsRawHandle`]: https://doc.rust-lang.org/std/os/windows/io/trait.AsRawHandle.html
17
18#![deny(missing_docs)]
19#![cfg_attr(can_vector, feature(can_vector))]
20#![cfg_attr(write_all_vectored, feature(write_all_vectored))]
21
22mod arrays;
23mod borrow_streamer;
24mod files;
25#[cfg(feature = "io-streams")]
26mod owned_streamer;
27#[cfg(not(windows))]
28mod rustix;
29mod slice;
30#[cfg(windows)]
31mod windows;
32
33pub use arrays::{Array, ArrayEditor, ArrayReader, ArrayWriter, EditAt, Metadata, ReadAt, WriteAt};
34
35/// Advice to pass to [`Array::advise`] to describe an expected access pattern.
36///
37/// This is a re-export of [`system_interface::fs::Advice`].
38pub use system_interface::fs::Advice;
39
40/// Functions for custom implementations of [`ReadAt`] and [`WriteAt`] for
41/// file-like types.
42pub mod filelike {
43    // We can't use Windows' `read_at` or `write_at` here because it isn't able to
44    // extend the length of a file we can't `reopen` (such as temporary files).
45    // However, while `FileIoExt` can't use `seek_write` because it mutates the
46    // current position, here we *can* use plain `seek_write` because `ArrayEditor`
47    // doesn't expose the current position.
48    pub use crate::files::{advise, copy_from, set_len};
49    #[cfg(all(not(windows), feature = "io-streams"))]
50    pub use crate::rustix::read_via_stream_at;
51    #[cfg(not(windows))]
52    pub use crate::rustix::{
53        is_read_vectored_at, is_write_vectored_at, metadata, read_at, read_exact_at,
54        read_exact_vectored_at, read_vectored_at, write_all_at, write_all_vectored_at, write_at,
55        write_vectored_at,
56    };
57    #[cfg(all(windows, feature = "io-streams"))]
58    pub use crate::windows::read_via_stream_at;
59    #[cfg(windows)]
60    pub use crate::windows::{
61        is_read_vectored_at, is_write_vectored_at, metadata, read_at, read_exact_at,
62        read_exact_vectored_at, read_vectored_at, write_all_at, write_all_vectored_at, write_at,
63        write_vectored_at,
64    };
65}