0.13.0 (#36)

- Make `try_lock_*` returns `std::io::Result<bool>`, which is compatible with the incoming `std::fs::File::try_lock*` in std liberary.

Author: al8n

.github/workflows/ci.yml

@@ -21,6 +21,7 @@ on:
       - '**.md'
       - '**.txt'
   workflow_dispatch:
+  schedule: [cron: "0 1 */7 * *"]
 
 env:
   CARGO_TERM_COLOR: always

CHANGELOG.md

@@ -0,0 +1,7 @@
+# Releases
+
+## 0.13.0
+
+### Breakage
+
+- Make `try_lock_*` returns `std::io::Result<bool>`, which is compatible with the incoming `std::fs::File::try_lock*` in std liberary.

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "fs4"
 # NB: When modifying, also modify html_root_url in lib.rs
-version = "0.12.0"
+version = "0.13.0"
 rust-version = "1.75.0"
 authors = ["Dan Burkert <[email protected]>", "Al Liu <[email protected]>"]
 license = "MIT OR Apache-2.0"
@@ -28,7 +28,7 @@ fs-err3-tokio = ["fs-err3", "fs-err3/tokio"]
 rustix = { version = "0.38", features = ["fs"] }
 
 [target.'cfg(windows)'.dependencies.windows-sys]
-version = "0.52"
+version = "0.59"
 features = ["Win32_Foundation", "Win32_Storage_FileSystem", "Win32_System_IO"]
 
 [dependencies]

README.md

@@ -20,52 +20,61 @@ This is a fork of the [fs2-rs](https://github.com/danburkert/fs2-rs) crate, the
 </div>
 
 ## Installation
+
 - std
+
     ```toml
     [dependencies]
-    fs4 = { version = "0.12", features = ["sync"] }
+    fs4 = { version = "0.13", features = ["sync"] }
     ```
 
 - [async-std runtime](https://crates.io/crates/async-std)
+
     ```toml
     [dependencies]
-    fs4 = { version = "0.12", features = ["async-std"] }
+    fs4 = { version = "0.13", features = ["async-std"] }
     ```
 
 - [fs-err v2](https://crates.io/crates/fs-err)
+
     ```toml
     [dependencies]
-    fs4 = { version = "0.12", features = ["fs-err2"] }
+    fs4 = { version = "0.13", features = ["fs-err2"] }
     ```
 
 - [fs-err-tokio v2](https://crates.io/crates/fs-err)
+
     ```toml
     [dependencies]
-    fs4 = { version = "0.12", features = ["fs-err2-tokio"] }
+    fs4 = { version = "0.13", features = ["fs-err2-tokio"] }
     ```
 
 - [fs-err v3](https://crates.io/crates/fs-err)
+
     ```toml
     [dependencies]
-    fs4 = { version = "0.12", features = ["fs-err3"] }
+    fs4 = { version = "0.13", features = ["fs-err3"] }
     ```
 
 - [fs-err-tokio v3](https://crates.io/crates/fs-err)
+
     ```toml
     [dependencies]
-    fs4 = { version = "0.12", features = ["fs-err3-tokio"] }
+    fs4 = { version = "0.13", features = ["fs-err3-tokio"] }
     ```
 
 - [smol runtime](https://crates.io/crates/smol)
+
     ```toml
     [dependencies]
-    fs4 = { version = "0.12", features = ["smol"] }
+    fs4 = { version = "0.13", features = ["smol"] }
     ```
 
 - [tokio runtime](https://crates.io/crates/tokio)
+
     ```toml
     [dependencies]
-    fs4 = { version = "0.12", features = ["tokio"] }
+    fs4 = { version = "0.13", features = ["tokio"] }
     ```
 
 ## Features
@@ -86,7 +95,7 @@ Apache License (Version 2.0).
 
 See [LICENSE-APACHE](LICENSE-APACHE), [LICENSE-MIT](LICENSE-MIT) for details.
 
-Copyright (c) 2021 Al Liu.
+Copyright (c) 2025 Al Liu.
 
 Copyright (c) 2015 Dan Burkert.
 

src/file_ext/async_impl.rs

@@ -48,11 +48,11 @@ macro_rules! async_file_ext {
 
             /// Locks the file for shared usage, or returns an error if the file is
             /// currently locked (see `lock_contended_error`).
-            fn try_lock_shared(&self) -> Result<()>;
+            fn try_lock_shared(&self) -> Result<bool>;
 
             /// Locks the file for exclusive usage, or returns an error if the file is
             /// currently locked (see `lock_contended_error`).
-            fn try_lock_exclusive(&self) -> Result<()>;
+            fn try_lock_exclusive(&self) -> Result<bool>;
 
             /// Unlocks the file.
             fn unlock(&self) -> Result<()>;
@@ -79,11 +79,11 @@ macro_rules! async_file_ext {
                 sys::lock_exclusive(self)
             }
 
-            fn try_lock_shared(&self) -> Result<()> {
+            fn try_lock_shared(&self) -> Result<bool> {
                 sys::try_lock_shared(self)
             }
 
-            fn try_lock_exclusive(&self) -> Result<()> {
+            fn try_lock_exclusive(&self) -> Result<bool> {
                 sys::try_lock_exclusive(self)
             }
 
@@ -106,7 +106,7 @@ macro_rules! test_mod {
             extern crate test;
             use crate::{
                 allocation_granularity, available_space, free_space,
-                lock_contended_error, total_space,
+                total_space,
             };
 
             $(
@@ -144,13 +144,13 @@ macro_rules! test_mod {
                 file1.lock_shared().unwrap();
                 file2.lock_shared().unwrap();
                 assert_eq!(
-                    file3.try_lock_exclusive().unwrap_err().kind(),
-                    lock_contended_error().kind()
+                    file3.try_lock_exclusive().unwrap(),
+                    false,
                 );
                 file1.unlock().unwrap();
                 assert_eq!(
-                    file3.try_lock_exclusive().unwrap_err().kind(),
-                    lock_contended_error().kind()
+                    file3.try_lock_exclusive().unwrap(),
+                    false,
                 );
 
                 // Once all shared file locks are dropped, an exclusive lock may be created;
@@ -181,12 +181,12 @@ macro_rules! test_mod {
                 // No other access is possible once an exclusive lock is created.
                 file1.lock_exclusive().unwrap();
                 assert_eq!(
-                    file2.try_lock_exclusive().unwrap_err().kind(),
-                    lock_contended_error().kind()
+                    file2.try_lock_exclusive().unwrap(),
+                    false,
                 );
                 assert_eq!(
-                    file2.try_lock_shared().unwrap_err().kind(),
-                    lock_contended_error().kind()
+                    file2.try_lock_shared().unwrap(),
+                    false,
                 );
 
                 // Once the exclusive lock is dropped, the second file is able to create a lock.
@@ -216,8 +216,8 @@ macro_rules! test_mod {
 
                 file1.lock_exclusive().unwrap();
                 assert_eq!(
-                    file2.try_lock_shared().unwrap_err().kind(),
-                    lock_contended_error().kind()
+                    file2.try_lock_shared().unwrap(),
+                    false,
                 );
 
                 // Drop file1; the lock should be released.

src/file_ext/sync_impl.rs

@@ -48,11 +48,11 @@ macro_rules! file_ext {
 
             /// Locks the file for shared usage, or returns an error if the file is
             /// currently locked (see `lock_contended_error`).
-            fn try_lock_shared(&self) -> Result<()>;
+            fn try_lock_shared(&self) -> Result<bool>;
 
             /// Locks the file for exclusive usage, or returns an error if the file is
             /// currently locked (see `lock_contended_error`).
-            fn try_lock_exclusive(&self) -> Result<()>;
+            fn try_lock_exclusive(&self) -> Result<bool>;
 
             /// Unlocks the file.
             fn unlock(&self) -> Result<()>;
@@ -71,10 +71,10 @@ macro_rules! file_ext {
             fn lock_exclusive(&self) -> Result<()> {
                 sys::lock_exclusive(self)
             }
-            fn try_lock_shared(&self) -> Result<()> {
+            fn try_lock_shared(&self) -> Result<bool> {
                 sys::try_lock_shared(self)
             }
-            fn try_lock_exclusive(&self) -> Result<()> {
+            fn try_lock_exclusive(&self) -> Result<bool> {
                 sys::try_lock_exclusive(self)
             }
             fn unlock(&self) -> Result<()> {
@@ -93,7 +93,7 @@ macro_rules! test_mod {
 
             use super::*;
             use crate::{
-                allocation_granularity, available_space, free_space, lock_contended_error, statvfs,
+                allocation_granularity, available_space, free_space, statvfs,
                 total_space, FsStats,
             };
 
@@ -132,13 +132,13 @@ macro_rules! test_mod {
                 file1.lock_shared().unwrap();
                 file2.lock_shared().unwrap();
                 assert_eq!(
-                    file3.try_lock_exclusive().unwrap_err().kind(),
-                    lock_contended_error().kind()
+                    file3.try_lock_exclusive().unwrap(),
+                    false,
                 );
                 file1.unlock().unwrap();
                 assert_eq!(
-                    file3.try_lock_exclusive().unwrap_err().kind(),
-                    lock_contended_error().kind()
+                    file3.try_lock_exclusive().unwrap(),
+                    false,
                 );
 
                 // Once all shared file locks are dropped, an exclusive lock may be created;
@@ -169,12 +169,12 @@ macro_rules! test_mod {
                 // No other access is possible once an exclusive lock is created.
                 file1.lock_exclusive().unwrap();
                 assert_eq!(
-                    file2.try_lock_exclusive().unwrap_err().kind(),
-                    lock_contended_error().kind()
+                    file2.try_lock_exclusive().unwrap(),
+                    false,
                 );
                 assert_eq!(
-                    file2.try_lock_shared().unwrap_err().kind(),
-                    lock_contended_error().kind()
+                    file2.try_lock_shared().unwrap(),
+                    false,
                 );
 
                 // Once the exclusive lock is dropped, the second file is able to create a lock.
@@ -204,8 +204,8 @@ macro_rules! test_mod {
 
                 file1.lock_exclusive().unwrap();
                 assert_eq!(
-                    file2.try_lock_shared().unwrap_err().kind(),
-                    lock_contended_error().kind()
+                    file2.try_lock_shared().unwrap(),
+                    false,
                 );
 
                 // Drop file1; the lock should be released.

src/lib.rs

@@ -1,5 +1,5 @@
 //! Extended utilities for working with files and filesystems in Rust.
-#![doc(html_root_url = "https://docs.rs/fs4/0.12.0")]
+#![doc(html_root_url = "https://docs.rs/fs4/0.13.0")]
 #![cfg_attr(test, feature(test))]
 #![cfg_attr(docsrs, feature(doc_cfg))]
 #![cfg_attr(docsrs, allow(unused_attributes))]

src/unix.rs

@@ -11,13 +11,13 @@ macro_rules! lock_impl {
         }
 
         #[cfg(not(target_os = "wasi"))]
-        pub fn try_lock_shared(file: &$file) -> std::io::Result<()> {
-            flock(file, rustix::fs::FlockOperation::NonBlockingLockShared)
+        pub fn try_lock_shared(file: &$file) -> std::io::Result<bool> {
+            try_flock(file, rustix::fs::FlockOperation::NonBlockingLockShared)
         }
 
         #[cfg(not(target_os = "wasi"))]
-        pub fn try_lock_exclusive(file: &$file) -> std::io::Result<()> {
-            flock(file, rustix::fs::FlockOperation::NonBlockingLockExclusive)
+        pub fn try_lock_exclusive(file: &$file) -> std::io::Result<bool> {
+            try_flock(file, rustix::fs::FlockOperation::NonBlockingLockExclusive)
         }
 
         #[cfg(not(target_os = "wasi"))]
@@ -34,6 +34,22 @@ macro_rules! lock_impl {
                 Err(e) => Err(std::io::Error::from_raw_os_error(e.raw_os_error())),
             }
         }
+
+        #[cfg(not(target_os = "wasi"))]
+        fn try_flock(file: &$file, flag: rustix::fs::FlockOperation) -> std::io::Result<bool> {
+            let borrowed_fd = unsafe { rustix::fd::BorrowedFd::borrow_raw(file.as_raw_fd()) };
+
+            match rustix::fs::flock(borrowed_fd, flag) {
+                Ok(_) => Ok(true),
+                Err(e) => {
+                    let err = std::io::Error::from_raw_os_error(e.raw_os_error());
+                    if let std::io::ErrorKind::WouldBlock = err.kind() {
+                        return Ok(false);
+                    }
+                    Err(err)
+                }
+            }
+        }
     };
 }
 

src/unix/async_impl.rs

@@ -60,8 +60,6 @@ macro_rules! test_mod {
         mod test {
           extern crate tempfile;
 
-          use crate::lock_contended_error;
-
           $(
               $use_stmt
           )*
@@ -95,8 +93,8 @@ macro_rules! test_mod {
               // Attempting to replace a shared lock with an exclusive lock will fail
               // with multiple lock holders, and remove the original shared lock.
               assert_eq!(
-                  file2.try_lock_exclusive().unwrap_err().raw_os_error(),
-                  lock_contended_error().raw_os_error()
+                  file2.try_lock_exclusive().unwrap(),
+                  false,
               );
               file1.lock_shared().unwrap();
           }

src/unix/sync_impl.rs

@@ -60,8 +60,6 @@ macro_rules! test_mod {
         mod test {
           extern crate tempfile;
 
-          use crate::lock_contended_error;
-
           $(
               $use_stmt
           )*
@@ -86,17 +84,17 @@ macro_rules! test_mod {
                   .unwrap();
 
               // Creating a shared lock will drop an exclusive lock.
-              file1.lock_exclusive().unwrap();
-              file1.lock_shared().unwrap();
-              file2.lock_shared().unwrap();
+              FileExt::lock_exclusive(&file1).unwrap();
+              FileExt::lock_shared(&file1).unwrap();
+              FileExt::lock_shared(&file2).unwrap();
 
               // Attempting to replace a shared lock with an exclusive lock will fail
               // with multiple lock holders, and remove the original shared lock.
               assert_eq!(
-                  file2.try_lock_exclusive().unwrap_err().raw_os_error(),
-                  lock_contended_error().raw_os_error()
+                  FileExt::try_lock_exclusive(&file2).unwrap(),
+                  false,
               );
-              file1.lock_shared().unwrap();
+              FileExt::lock_shared(&file1).unwrap();
           }
         }
     };