#fd #lock-files #locking #async #task

async-fd-lock

Advisory cross-platform file locks using file descriptors with async support by spawning blocking tasks

2 unstable releases

0.2.0 Jun 23, 2024
0.1.1 Jun 23, 2024
0.1.0 Jun 23, 2024

#957 in Filesystem

Download history 961/week @ 2024-12-19 597/week @ 2024-12-26 891/week @ 2025-01-02 1484/week @ 2025-01-09 1565/week @ 2025-01-16 1509/week @ 2025-01-23 783/week @ 2025-01-30 986/week @ 2025-02-06 1158/week @ 2025-02-13 1079/week @ 2025-02-20 1472/week @ 2025-02-27 1403/week @ 2025-03-06 2308/week @ 2025-03-13 2313/week @ 2025-03-20 1557/week @ 2025-03-27 1382/week @ 2025-04-03

7,873 downloads per month
Used in 23 crates (2 directly)

MIT/Apache

33KB
671 lines

async-fd-lock

crates.io version downloads docs.rs docs

Advisory cross-platform file locks using file descriptors, with async support by off-loading blocking operations to newly spawned blocking tasks. Adapted from yoshuawuyts/fd-lock, which was adapted from mafintosh/fd-lock.

Note that advisory lock compliance is opt-in, and can freely be ignored by other parties. This means this crate should never be used for security purposes, but solely to coordinate file access.

Examples

Basic usage

use std::path::PathBuf;
use tokio::fs::File;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use async_fd_lock::{LockRead, LockWrite};

let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("foo.txt");

// Lock it for writing.
{
    let mut write_guard = File::options()
        .create_new(true)
        .write(true)
        .truncate(true)
        .open(&path).await?
        .lock_write().await
        .map_err(|(_, err)| err)?;
    write_guard.write(b"bongo cat").await?;
}

// Lock it for reading.
{
    let mut read_guard_1 = File::open(&path).await?.lock_read().await.map_err(|(_, err)| err)?;
    let mut read_guard_2 = File::open(&path).await?.lock_read().await.map_err(|(_, err)| err)?;
    let byte_1 = read_guard_1.read_u8().await?;
    let byte_2 = read_guard_2.read_u8().await?;
}

Installation

$ cargo add async-fd-lock

Safety

This crate uses unsafe on Windows to interface with windows-sys. All invariants have been carefully checked, and are manually enforced.

References

License

MIT OR Apache-2.0

Dependencies

~2–14MB
~198K SLoC