Rust bindings for the 3FS USRBIO API. The crate provides registered files, shared-memory I/O rings, batched reads and writes, and background read workers.
- Linux with a mounted 3FS filesystem for I/O.
- A Rust toolchain and
libclangfor generating bindings at build time. - A compatible
libhf3fs_api_shared.so, available to both the linker and the runtime loader. The library must provide the APIs ininclude/hf3fs_usrbio.h, includinghf3fs_iorcreate4andhf3fs_iovunlink.
The 3FS library is installed separately. For a nonstandard installation directory,
add it to LIBRARY_PATH when building and LD_LIBRARY_PATH when running.
Add the crate to your project:
[dependencies]
usrbio = "0.1"Read up to 4 KiB from an existing file on your 3FS mount:
use usrbio::{File, Ring, RingConfig};
fn main() -> usrbio::Result<()> {
let file = File::open("/mnt/3fs/example.txt")?;
let mut ring = Ring::create(&RingConfig::default(), file.mount_point())?;
let data = ring.read(&file, 0, 4096)?;
println!("{}", String::from_utf8_lossy(data));
Ok(())
}Ring performs blocking I/O. Read slices borrow the ring's buffer;
copy them if they must outlive that borrow. Each ring serves files on one mount,
and each batch must fit its configured entry count and buffer size. Batch results
contain a byte count or a negative error code for each job, so check each result
even when the batch call returns Ok.
For writes, open the file with std::fs::OpenOptions and the Open3fsFile
extension trait. Use ReadWorker or ReadWorkers for reads on background threads.
See the API documentation for details.
cargo install usrbio --features binOr build from source:
cargo build --release --features binRun a read benchmark against existing, nonempty files on the same 3FS mount:
usrbio --action bench --threads 4 --bs 512k --iodepth 16 --duration 10s /mnt/3fs/data
usrbio --helpWhen building from source, use ./target/release/usrbio. Other actions are
check (read files and print CRC32C checksums), gen-files (create or overwrite
test files), and write-file (write a file or stdin at an offset).
cargo check --all-targets --all-features
cargo test --doc
cargo doc --no-depsThe integration tests require a writable 3FS directory and create or overwrite
test files there. Set USRBIO_3FS_TEST_DIR at compile time to run them:
USRBIO_3FS_TEST_DIR=/mnt/3fs/usrbio-tests cargo test --test test_fileWithout that variable, the integration tests return early without exercising I/O.
Licensed under MIT or Apache-2.0, at your option. The bundled 3FS header is covered by LICENSE-3FS.