file_locking.rs

//! # Simple, Lightweight File Locking
//!
//! This crate provides an extremely lean implementation of file locking for POSIX
//! and Windows systems.
//!
//! The locking primitives used are `flock()` on POSIX (called through the
//! [`libc`](https://crates.io/crates/libc) crate), and `LockFileEx()` /
//! `UnlockFile()` on Windows (called through the
//! [`windows-sys`](https://crates.io/crates/windows-sys) crate).
//!
//! The API is exposed as a single extension trait for [`std::fs::File`] called
//! [`FileExt`]. Simply bring the trait into scope, and you can lock files to
//! your heart's content:
//!
//! ```
//! # use std::fs::{ self };
//! use std::fs::{ File };
//! use file_locking::{ FileExt };
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let f = File::options()
//!   .create(true)
//!   .write(true)
//!   .open("database.lock")?;
//!
//! {
//!   let _guard = f.lock_exclusive()?;
//!
//!   // ... do some stuff with the knowledge that nobody else can lock the file ...
//! }
//!
//! // the lock is now released and can be taken again by somebody else c:
//! # fs::remove_file("database.lock")?;
//! # Ok(())
//! # }
//! ```
//!
//! Some unavoidable behavior differences exist between platforms. To summarize:
//!
//! - Don't count on file locks to prevent read or write access to a file, but
//!   be prepared for them to.
//! - Don't lock the same on-disk file through the same [`File`](std::fs::File)
//!   object more than once.
//! - Don't count on file locks working through network shares (NFS, SMB, etc.)
//!
//! Detailed differences are documented on the [`FileExt`] trait.

pub mod errors;
pub mod file_ext;

#[cfg(unix)]
mod unix;

#[cfg(windows)]
mod windows;

pub use errors::{ Error, Result };
pub use file_ext::{ FileExt };

#[cfg(test)]
mod tests {
	use super::*;

	use std::fs::{ File, self };
	use std::path::{ Path, PathBuf };

	struct TestFile {
		path: PathBuf,
		file: File,
	}

	impl TestFile {
		fn new<P: AsRef<Path>>(path: P) -> Result<TestFile> {
			let path = path.as_ref();

			let file = File::options()
				.create_new(true)
				.write(true)
				.open(path)
				.expect("Should be able to create test file");

			Ok(TestFile {
				path: path.to_path_buf(),
				file,
			})
		}
	}

	impl Drop for TestFile {
		fn drop(&mut self) {
			let _ = fs::remove_file(&self.path);
		}
	}

	#[test]
	fn lock_shared_works() {
		const TEST_FILE_PATH: &str = "test_lock_shared.txt";
		let f = TestFile::new(TEST_FILE_PATH).expect("File should be created and opened");
		let _guard = f.file.lock_shared().expect("Shared file lock should be obtained");
	}

	#[test]
	fn lock_exclusive_works() {
		const TEST_FILE_PATH: &str = "test_lock_exclusive.txt";
		let f = TestFile::new(TEST_FILE_PATH).expect("File should be created and opened");
		let _guard = f.file.lock_exclusive().expect("Exclusive file lock should be obtained");
	}

	#[test]
	fn try_lock_shared_works() {
		const TEST_FILE_PATH: &str = "test_try_lock_shared.txt";
		let f = TestFile::new(TEST_FILE_PATH).expect("File should be created and opened");
		let _guard = f.file.try_lock_shared().expect("Shared file lock should be obtained");
	}

	#[test]
	fn try_lock_exclusive_works() {
		const TEST_FILE_PATH: &str = "test_try_lock_exclusive.txt";
		let f = TestFile::new(TEST_FILE_PATH).expect("File should be created and opened");
		let _guard = f.file.try_lock_shared().expect("Shared file lock should be obtained");
	}

	#[test]
	fn try_lock_shared_does_not_block() {
		const TEST_FILE_PATH: &str = "test_try_lock_shared_does_not_block.txt";
		let f = TestFile::new(TEST_FILE_PATH).expect("File should be created and opened");
		let _guard = f.file.lock_exclusive().expect("Exclusive file lock should be obtained");
		assert_shared_lock_fails(TEST_FILE_PATH);
	}

	#[test]
	fn try_lock_exclusive_does_not_block() {
		const TEST_FILE_PATH: &str = "test_try_lock_exclusive_does_not_block.txt";
		let f = TestFile::new(TEST_FILE_PATH).expect("File should be created and opened");
		let _guard = f.file.lock_exclusive().expect("Exclusive file lock should be obtained");
		assert_exclusive_lock_fails(TEST_FILE_PATH);
	}

	#[test]
	fn lock_guard_going_out_of_scope_releases_lock() {
		const TEST_FILE_PATH: &str = "test_lock_guard_going_out_of_scope_releases_lock.txt";
		let f = TestFile::new(TEST_FILE_PATH).expect("File should be created and opened");

		{
			let _guard = f.file.lock_exclusive().expect("Exclusive file lock should be obtained");
			assert_shared_lock_fails(TEST_FILE_PATH);
		}

		{
			let f2 = File::options()
				.read(true)
				.open(TEST_FILE_PATH)
				.expect("Second handle to the same file should be opened");

			let result = f2.try_lock_shared();
			let _ = result.expect("Shared lock should succeed");
		}

		{
			let f2 = File::options()
				.read(true)
				.open(TEST_FILE_PATH)
				.expect("Second handle to the same file should be opened");

			let result = f2.try_lock_exclusive();
			let _ = result.expect("Exclusive lock should succeed");
		}
	}

	fn assert_shared_lock_fails<P: AsRef<Path>>(path: P) {
		let f2 = File::options()
			.read(true)
			.open(path)
			.expect("Second handle to the same file should be opened");

		let result = f2.try_lock_shared();

		if result.expect_err("Second file lock should not be obtained") != Error::AlreadyLocked {
			panic!("Result of trying to obtain a second file lock should be Error::AlreadyLocked");
		}
	}

	fn assert_exclusive_lock_fails<P: AsRef<Path>>(path: P) {
		let f2 = File::options()
			.read(true)
			.open(path)
			.expect("Second handle to the same file should be opened");

		let result = f2.try_lock_exclusive();

		if result.expect_err("Second file lock should not be obtained") != Error::AlreadyLocked {
			panic!("Result of trying to obtain a second file lock should be Error::AlreadyLocked");
		}
	}
}