Node.js Service

https://docs.rs/pidlock
Admin
This project is a Node.js service that likely provides API endpoints and business logic, potentially...
Tokens:88,437
Snippets:832
Trust Score:9.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Pidlock Acquisition and Owner Check Example

Source: https://docs.rs/pidlock/0.2.2/pidlock/struct.Pidlock.html?search=std%3A%3Avec

Demonstrates how to create, acquire, check ownership, and release a Pidlock. This example shows the typical workflow for using a lock file.

```rust
use pidlock::Pidlock;
use std::env;

let temp_dir = env::temp_dir();
let lock_path = temp_dir.join("owner_example.pid");

let mut lock = Pidlock::new_validated(&lock_path)?;

// No owner initially
assert_eq!(lock.get_owner()?, None);

// After acquiring, we should be the owner
lock.acquire()?;
if let Some(owner_pid) = lock.get_owner()? {
    println!("Lock is owned by PID: {}", owner_pid);
    assert_eq!(owner_pid, std::process::id() as i32);
}

lock.release()?;
```

--------------------------------

### Example: Getting Lock Owner

Source: https://docs.rs/pidlock/latest/src/pidlock/lib.rs.html?search=u32+-%3E+bool

Demonstrates how to use `get_owner` to retrieve the PID of the process holding the lock. Shows initial state, acquiring the lock, and then checking the owner.

```rust
use pidlock::Pidlock;
use std::env;

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let temp_dir = env::temp_dir();
let lock_path = temp_dir.join("owner_example.pid");

let mut lock = Pidlock::new_validated(&lock_path)?;

// No owner initially
assert_eq!(lock.get_owner()?,
 None);

// After acquiring, we should be the owner
lock.acquire()?;
if let Some(owner_pid) = lock.get_owner()? {
    println!("Lock is owned by PID: {}", owner_pid);
}
# Ok(())
# }
```

--------------------------------

### Example: Getting Lock Owner

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=u32+-%3E+bool

Demonstrates how to use `get_owner` to find the PID of the process holding the lock. It shows checking for an owner when no lock is present, acquiring a lock, and then verifying that the current process is identified as the owner.

```rust
use pidlock::Pidlock;
use std::env;

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let temp_dir = env::temp_dir();
let lock_path = temp_dir.join("owner_example.pid");

let mut lock = Pidlock::new_validated(&lock_path)?;

// No owner initially
assert_eq!(lock.get_owner()?, None);

// After acquiring, we should be the owner
lock.acquire()?;
if let Some(owner_pid) = lock.get_owner()? {
    println!("Lock is owned by PID: {}", owner_pid);
}
# Ok(())
# }
```

--------------------------------

### Quick Start: Acquire and Release Lock

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=std%3A%3Avec

Demonstrates how to create a validated lock, acquire it, perform work, and optionally release it. Handles cases where the lock is already held.

```rust
use pidlock::Pidlock;
use std::path::Path;

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let temp_dir = std::env::temp_dir();
let lock_path = temp_dir.join("my_app.pid");
let mut lock = Pidlock::new_validated(&lock_path)?;

// Try to acquire the lock
match lock.acquire() {
    Ok(())=> {
        println!("Lock acquired successfully!");
        
        // Do your work here...
        
        // Explicitly release the lock (optional - it's auto-released on drop)
        lock.release()?;
        println!("Lock released successfully!");
    }
    Err(pidlock::PidlockError::LockExists) => {
        println!("Another instance is already running");
    }
    Err(e) => {
        eprintln!("Failed to acquire lock: {}", e);
    }
}
# Ok(())
# }
```

--------------------------------

### Quick Start: Acquire and Release Lock

Source: https://docs.rs/pidlock/0.2.2/index.html

Demonstrates how to create a lock file, acquire the lock, perform operations, and release the lock. The lock is automatically released when the Pidlock is dropped.

```rust
use pidlock::Pidlock;
use std::path::Path;

let temp_dir = std::env::temp_dir();
let lock_path = temp_dir.join("my_app.pid");
let mut lock = Pidlock::new_validated(&lock_path)?;

// Try to acquire the lock
match lock.acquire() {
    Ok(())
 => {
        println!("Lock acquired successfully!");
         
        // Do your work here...
         
        // Explicitly release the lock (optional - it's auto-released on drop)
        lock.release()?;
        println!("Lock released successfully!");
    }
    Err(pidlock::PidlockError::LockExists) => {
        println!("Another instance is already running");
    }
    Err(e) => {
        eprintln!("Failed to acquire lock: {}", e);
    }
}

```

--------------------------------

### Example: Using Pidlock's locked() method

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html

Demonstrates how to use the `locked()` method to check the lock status before, during, and after acquiring and releasing a lock.

```rust
use pidlock::Pidlock;
use std::env;

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let temp_dir = env::temp_dir();
let lock_path = temp_dir.join("locked_example.pid");

let mut lock = Pidlock::new_validated(&lock_path)?;

// Initially not locked
assert!(!lock.locked());

// After acquiring
lock.acquire()?;
assert!(lock.locked());

// After releasing
lock.release()?;
assert!(!lock.locked());
# Ok(())
# }
```

--------------------------------

### Example: Using Pidlock's exists() method

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html

Demonstrates how to use the `exists()` method to check for the presence of a lock file on disk, including creating a file manually to test the function.

```rust
use pidlock::Pidlock;
use std::env;

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let temp_dir = env::temp_dir();
let lock_path = temp_dir.join("exists_example.pid");

let lock = Pidlock::new_validated(&lock_path)?;

// Initially, no lock file exists
assert!(!lock.exists());

// Create a lock file manually to test
std::fs::write(&lock_path, "12345")?;
assert!(lock.exists());

// Clean up
std::fs::remove_file(&lock_path)?;
# Ok(())
# }
```

--------------------------------

### Example: Using is_active

Source: https://docs.rs/pidlock/latest/src/pidlock/lib.rs.html?search=u32+-%3E+bool

Demonstrates how to use the `is_active` method to check the status of a lock file. Includes creating a lock, checking its status, and testing with the current process ID.

```rust
use pidlock::Pidlock;
use std::env;

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let temp_dir = env::temp_dir();
let lock_path = temp_dir.join("is_active_example.pid");

let lock = Pidlock::new_validated(&lock_path)?;

match lock.is_active()? {
    true => println!("Lock is held by an active process"),
    false => println!("No active lock found"),
}

// Test with our own process
std::fs::write(&lock_path, std::process::id().to_string())?;
assert!(lock.is_active()?); // Our process is definitely active

// Clean up
std::fs::remove_file(&lock_path)?;
# Ok(())
# }
```

--------------------------------

### Example: Using Pidlock's exists() method

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=std%3A%3Avec

Illustrates how to use the `exists()` method to check for the presence of a lock file on disk. It shows the initial state, after manually creating a file, and after cleaning up.

```rust
use pidlock::Pidlock;
use std::env;

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let temp_dir = env::temp_dir();
let lock_path = temp_dir.join("exists_example.pid");

let lock = Pidlock::new_validated(&lock_path)?;

// Initially, no lock file exists
assert!(!lock.exists());

// Create a lock file manually to test
std::fs::write(&lock_path, "12345")?;
assert!(lock.exists());

// Clean up
std::fs::remove_file(&lock_path)?;
# Ok(())
# }

```

--------------------------------

### Quick Start: Acquire and Release Lock

Source: https://docs.rs/pidlock/0.2.2/pidlock/index.html

Demonstrates how to create a validated lock path, acquire a lock, perform work, and optionally release the lock. The lock is automatically released when the Pidlock is dropped.

```rust
use pidlock::Pidlock;
use std::path::Path;

let temp_dir = std::env::temp_dir();
let lock_path = temp_dir.join("my_app.pid");
let mut lock = Pidlock::new_validated(&lock_path)?;

// Try to acquire the lock
match lock.acquire() {
    Ok(())=> {
        println!("Lock acquired successfully!");
         
        // Do your work here...
         
        // Explicitly release the lock (optional - it's auto-released on drop)
        lock.release()?;
        println!("Lock released successfully!");
    }
    Err(pidlock::PidlockError::LockExists) => {
        println!("Another instance is already running");
    }
    Err(e) => {
        eprintln!("Failed to acquire lock: {}", e);
    }
}
```

--------------------------------

### Pidlock Error Handling Example

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=

Demonstrates how to acquire and release a lock, handling potential PidlockError variants like LockExists, InvalidState, and general IO errors.

```rust
use pidlock::{Pidlock, PidlockError};

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let temp_dir = std::env::temp_dir();
let lock_path = temp_dir.join("error_example.pid");
let mut lock = Pidlock::new_validated(&lock_path)?;

match lock.acquire() {
    Ok(())=> {
        println!("Lock acquired successfully");
        lock.release()?;
    }
    Err(PidlockError::LockExists) => {
        println!("Another process is holding the lock");
    }
    Err(PidlockError::InvalidState) => {
        println!("Lock is in wrong state for this operation");
    }
    Err(e) => {
        println!("Other error: {}", e);
    }
}
# Ok(())
# }
```

--------------------------------

### Example: Using Pidlock's locked() method

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=std%3A%3Avec

Demonstrates how to use the `locked()` method to check the acquisition state of a Pidlock instance through its lifecycle: before acquiring, after acquiring, and after releasing.

```rust
use pidlock::Pidlock;
use std::env;

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let temp_dir = env::temp_dir();
let lock_path = temp_dir.join("locked_example.pid");

let mut lock = Pidlock::new_validated(&lock_path)?;

// Initially not locked
assert!(!lock.locked());

// After acquiring
lock.acquire()?;
assert!(lock.locked());

// After releasing
lock.release()?;
assert!(!lock.locked());
# Ok(())
# }

```

--------------------------------

### Quick Start: Acquiring and Releasing a Lock

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=

Demonstrates how to create a validated lock path, attempt to acquire a lock, and handle success or failure. The lock is automatically released when the `Pidlock` is dropped.

```rust
use pidlock::Pidlock;
use std::path::Path;

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let temp_dir = std::env::temp_dir();
let lock_path = temp_dir.join("my_app.pid");
let mut lock = Pidlock::new_validated(&lock_path)?;

// Try to acquire the lock
match lock.acquire() {
    Ok(()) => {
        println!("Lock acquired successfully!");
        
        // Do your work here...
        
        // Explicitly release the lock (optional - it's auto-released on drop)
        lock.release()?;
        println!("Lock released successfully!");
    }
    Err(pidlock::PidlockError::LockExists) => {
        println!("Another instance is already running");
    }
    Err(e) => {
        eprintln!("Failed to acquire lock: {}", e);
    }
}
# Ok(())
# }

```

--------------------------------

### Quick Start: Acquiring a PID Lock

Source: https://docs.rs/pidlock/0.2.2/pidlock/index.html?search=

Demonstrates the basic usage of Pidlock to create a lock file, acquire the lock, perform operations, and release the lock. The lock is automatically released when the Pidlock is dropped.

```rust
use pidlock::Pidlock;
use std::path::Path;

let temp_dir = std::env::temp_dir();
let lock_path = temp_dir.join("my_app.pid");
let mut lock = Pidlock::new_validated(&lock_path)?;

// Try to acquire the lock
match lock.acquire() {
    Ok(())=> {
        println!("Lock acquired successfully!");
         
        // Do your work here...
         
        // Explicitly release the lock (optional - it's auto-released on drop)
        lock.release()?;
        println!("Lock released successfully!");
    }
    Err(pidlock::PidlockError::LockExists) => {
        println!("Another instance is already running");
    }
    Err(e) => {
        eprintln!("Failed to acquire lock: {}", e);
    }
}

```

--------------------------------

### Example: Checking Lock Activity

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=u32+-%3E+bool

Demonstrates how to use the `is_active` method to check the status of a lock file. It covers creating a lock, checking its status, and simulating lock ownership by writing the current process ID to the file.

```rust
use pidlock::Pidlock;
use std::env;

# fn main() -> Result<(), Box<dyn std::error::Error>> {
temp_dir = env::temp_dir();
lock_path = temp_dir.join("is_active_example.pid");

lock = Pidlock::new_validated(&lock_path)?;

match lock.is_active()? {
    true => println!("Lock is held by an active process"),
    false => println!("No active lock found"),
}

// Test with our own process
std::fs::write(&lock_path, std::process::id().to_string())?;
assert!(lock.is_active()?); // Our process is definitely active

// Clean up
std::fs::remove_file(&lock_path)?;
# Ok(())
# }
```

--------------------------------

### Example: Releasing a Lock

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=u32+-%3E+bool

Demonstrates the explicit release of a lock file. It shows acquiring a lock, then calling the `release` method, and finally asserting that the lock file no longer exists and the lock is not considered held.

```rust
use pidlock::Pidlock;
use std::env;

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let temp_dir = env::temp_dir();
let lock_path = temp_dir.join("release_example.pid");

let mut lock = Pidlock::new_validated(&lock_path)?;
lock.acquire()?;

// Explicitly release the lock
lock.release()?;

// Lock file should be gone
assert!(!lock.exists());
assert!(!lock.locked());
# Ok(())
# }
```

--------------------------------

### Acquiring a Pidlock with Error Handling

Source: https://docs.rs/pidlock/0.2.2/pidlock/struct.Pidlock.html?search=std%3A%3Avec

Illustrates the `acquire` method, showing how to handle successful acquisition and potential errors like `LockExists` or other I/O issues.

```rust
use pidlock::{Pidlock, PidlockError};
use std::env;

let temp_dir = env::temp_dir();
let lock_path = temp_dir.join("acquire_example.pid");

let mut lock = Pidlock::new_validated(&lock_path)?;

match lock.acquire() {
    Ok(()) => {
        println!("Lock acquired successfully!");
        // Do your work here...
        lock.release()?;
    }
    Err(PidlockError::LockExists) => {
        println!("Another instance is already running");
    }
    Err(e) => {
        eprintln!("Unexpected error: {}", e);
    }
}
```

--------------------------------

### Get Lock Owner PID

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves the Process ID (PID) of the owner of a lock file. If the lock file is invalid, corrupted, or the owning process does not exist, the lock file is automatically cleaned up. The example demonstrates checking for an owner before and after acquiring the lock.

```rust
use pidlock::Pidlock;
use std::env;

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let temp_dir = env::temp_dir();
let lock_path = temp_dir.join("owner_example.pid");

let mut lock = Pidlock::new_validated(&lock_path)?;

// No owner initially
assert_eq!(lock.get_owner()?,
 None);

// After acquiring, we should be the owner
lock.acquire()?;
if let Some(owner_pid) = lock.get_owner()? {
    println!("Lock is owned by PID: {}", owner_pid);
}

```

--------------------------------

### Test Get Owner - No File

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=std%3A%3Avec

Checks the behavior of `get_owner` when the lock file does not exist. It should return `None`.

```rust
        let pidfile = Pidlock::new_validated(&path).unwrap();
        let result = pidfile.get_owner().unwrap();
        assert_eq!(result, None);
    }

```

--------------------------------

### Catching Empty Path Error

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=

Example of catching the specific `InvalidPathError::EmptyPath` when attempting to create a lock with an empty path.

```rust
use pidlock::{Pidlock, PidlockError, InvalidPathError};

// Example of catching specific path validation errors
match Pidlock::new_validated("") {
    Err(PidlockError::InvalidPath(InvalidPathError::EmptyPath)) => {
        println!("Path cannot be empty");
    }
    _ => {}
}

```

--------------------------------

### Test Get Owner - Whitespace Only

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=std%3A%3Avec

Checks `get_owner` behavior with a lock file containing only whitespace. It should clean up the file and return `None`.

```rust
        // Write whitespace-only content
        temp_file.write_all(b"   \n  \t  \r\n  ").unwrap();
        temp_file.flush().unwrap();

        let pidfile = Pidlock::new_validated(&path).unwrap();
        let result = pidfile.get_owner().unwrap();
        // Whitespace-only file should be cleaned up and return None
        assert_eq!(result, None);
        assert!(!std::path::Path::new(&path).exists());
    }

```

--------------------------------

### Test Get Owner - Empty File

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=std%3A%3Avec

Tests `get_owner` with an empty lock file. The function should clean up the empty file and return `None`.

```rust
        // Write empty content
        temp_file.write_all(b"").unwrap();
        temp_file.flush().unwrap();

        let pidfile = Pidlock::new_validated(&path).unwrap();
        let result = pidfile.get_owner().unwrap();
        // Empty file should be cleaned up and return None
        assert_eq!(result, None);
        assert!(!std::path::Path::new(&path).exists());
    }

```

--------------------------------

### Basic Pidlock Usage

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=

Demonstrates creating, acquiring, checking existence, and releasing a Pidlock. Ensures the lock file is created and removed correctly.

```rust
use pidlock::Pidlock;
use std::fs;

# fn main() -> Result<(), Box<dyn std::error::Error>> {
// Create a lock in a temporary location
let temp_dir = std::env::temp_dir();
let lock_path = temp_dir.join("example.pid");

let mut lock = Pidlock::new_validated(&lock_path)?;

// Acquire the lock
lock.acquire()?;
assert!(lock.locked());

// The lock file now exists and contains our PID
assert!(lock.exists());

// Release the lock
lock.release()?;
assert!(!lock.locked());
assert!(!lock.exists()); // File is removed
# Ok(())
# }

```

--------------------------------

### Test Get Owner - Negative PID

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=std%3A%3Avec

Tests `get_owner` with a lock file containing a negative PID. The function should clean up the file and return `None`.

```rust
        // Write a negative PID (which shouldn't exist)
        temp_file.write_all(b"-12345").unwrap();
        temp_file.flush().unwrap();

        let pidfile = Pidlock::new_validated(&path).unwrap();
        let result = pidfile.get_owner().unwrap();
        // Negative PID should be cleaned up and return None
        assert_eq!(result, None);
        assert!(!std::path::Path::new(&path).exists());
    }

```

--------------------------------

### Test Get Owner - Valid PID

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=std%3A%3Avec

Verifies that `get_owner` correctly returns the PID of the current process when the lock file contains a valid PID.

```rust
        // First create a lock with our own PID
        let mut pidfile = Pidlock::new_validated(&path).unwrap();
        pidfile.acquire().unwrap();

        // Now test get_owner returns our PID
        let result = pidfile.get_owner().unwrap();
        assert_eq!(result, Some(std::process::id() as i32));

        pidfile.release().unwrap();
    }

```

--------------------------------

### Test Get Owner - Large PID

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=std%3A%3Avec

Verifies `get_owner` behavior with a large, potentially non-existent PID in the lock file. It should clean up the file and return `None`.

```rust
        // Write a very large PID (likely doesn't exist but valid i32)
        let large_pid = i32::MAX;
        temp_file
            .write_all(large_pid.to_string().as_bytes())
            .unwrap();
        temp_file.flush().unwrap();

        let pidfile = Pidlock::new_validated(&path).unwrap();
        let result = pidfile.get_owner().unwrap();
        // Large PID should be cleaned up since it likely doesn't exist
        assert_eq!(result, None);
    }

```

--------------------------------

### Initialize and Validate New Pidlock

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=

Creates a new `Pidlock` instance, validating the provided path and setting the initial state. Asserts that the PID in the file matches the current process ID.

```rust
fn test_new() {
        let temp_file = make_temp_file();
        let pid_path = temp_file.path().to_str().unwrap();
        let pidfile = Pidlock::new_validated(pid_path).unwrap();

        assert_eq!(pidfile.pid, std::process::id());
        assert_eq!(pidfile.path, PathBuf::from(pid_path));
        assert_eq!(pidfile.state, PidlockState::New);
    }
```

--------------------------------

### Test Get Owner With an Empty Lock File

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html

Tests the `get_owner` method when the lock file is empty. It asserts that an empty file is cleaned up and `get_owner` returns `None`.

```rust
    #[test]
    fn test_get_owner_empty_file() {
        let mut temp_file = make_temp_file();
        let path = temp_file.path().to_string_lossy().to_string();

        // Write empty content
        temp_file.write_all(b"" ).unwrap();
        temp_file.flush().unwrap();

        let pidfile = Pidlock::new_validated(&path).unwrap();
        let result = pidfile.get_owner().unwrap();
        // Empty file should be cleaned up and return None
        assert_eq!(result, None);
        assert!(!std::path::Path::new(&path).exists());
    }
```

--------------------------------

### get_owner

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html

Gets the owner of this lockfile, returning the PID if it exists and is valid. Reads the lock file, attempts to parse the PID, and cleans up invalid or stale lock files.

```APIDOC
## get_owner

### Description
Retrieves the Process ID (PID) of the owner of the lock file. If the lock file is invalid, the owning process does not exist, or the file is corrupted, it will be automatically cleaned up. Returns `Ok(Some(pid))` if a valid owner is found, `Ok(None)` if no lock file exists or it was cleaned up, and `Err(_)` on I/O errors.

### Method
`get_owner()`

### Returns
- `Ok(Some(pid))`: The lock file exists and contains a valid PID for an active process.
- `Ok(None)`: No lock file exists, or the lock file was invalid and cleaned up.
- `Err(_)`: An I/O error occurred while reading or cleaning up the file.
```

--------------------------------

### Initialize and Validate Pidlock

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html

Creates a new `Pidlock` instance with the specified path and validates its initial state. This is typically used for setting up a lock before acquiring it.

```rust
let temp_file = make_temp_file();
        let pid_path = temp_file.path().to_str().unwrap();
        let pidfile = Pidlock::new_validated(pid_path).unwrap();

        assert_eq!(pidfile.pid, std::process::id());
        assert_eq!(pidfile.path, PathBuf::from(pid_path));
        assert_eq!(pidfile.state, PidlockState::New);
```

--------------------------------

### Check Process Status on Windows

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Checks if a process is still active on Windows by attempting to open it and get its exit code. Returns false if the process does not exist or if permissions are insufficient.

```rust
        // The PID has already been validated by validate_pid() to be positive and within range
        use windows::Win32::Foundation::{CloseHandle, HANDLE, NTSTATUS, STILL_ACTIVE};
        use windows::Win32::System::Threading::{
            GetExitCodeProcess, OpenProcess, PROCESS_QUERY_INFORMATION,
        };

        let handle = unsafe {
            match OpenProcess(PROCESS_QUERY_INFORMATION, false, pid as u32) {
                Ok(h) => h,
                Err(_) => {
                    // OpenProcess failed, likely due to invalid PID or insufficient permissions
                    return false;
                }
            }
        };

        // Check if OpenProcess failed (returns 0 or INVALID_HANDLE_VALUE)
        if handle.is_invalid() {
            // Process doesn't exist or we don't have permission to query it
            return false;
        }

        // Use RAII-style cleanup to ensure handle is always closed, even on panic
        struct HandleGuard(HANDLE);
        impl Drop for HandleGuard {
            fn drop(&mut self) {
                let _ = unsafe { CloseHandle(self.0) };
            }
        }
        let _guard = HandleGuard(handle);

        let mut exit_code: u32 = 0;
        unsafe {
            match GetExitCodeProcess(handle, &mut exit_code) {
                Ok(_) => {
                    // Return true only if GetExitCodeProcess succeeded AND process is still active
                    // Note: STILL_ACTIVE (259) could theoretically be a real exit code, but it's
                    // extremely unlikely in practice. This is the documented Windows API pattern
                    // for checking if a process is still running. The risk of false positives
                    // (a process that actually exited with code 259) is negligible.
                    NTSTATUS(exit_code as i32) == STILL_ACTIVE
                }
                Err(_) => false, // GetExitCodeProcess failed
            }
        }
```

--------------------------------

### Initialize New Pidlock Instance

Source: https://docs.rs/pidlock/latest/src/pidlock/lib.rs.html?search=

Creates a new `Pidlock` instance with the specified file path. It initializes the lock state to `New` and stores the current process ID and the path to the lock file.

```rust
let pidfile = Pidlock::new_validated(pid_path).unwrap();

assert_eq!(pidfile.pid, std::process::id());
assert_eq!(pidfile.path, PathBuf::from(pid_path));
assert_eq!(pidfile.state, PidlockState::New);
```

--------------------------------

### Create Parent Directory if it Doesn't Exist

Source: https://docs.rs/pidlock/latest/src/pidlock/lib.rs.html?search=std%3A%3Avec

Attempts to create the parent directory for a given path if it does not already exist. Returns an error if creation fails.

```rust
if let Some(parent) = path.parent()
        && !parent.exists() {
            // Check if we can potentially create the directory
            if let Err(e) = fs::create_dir_all(parent) {
                return Err(PidlockError::InvalidPath(
                    InvalidPathError::ParentDirectoryCreationFailed {
                        path: parent.display().to_string(),
                        source: e,
                    },
                ));
            }
        }
```

--------------------------------

### Creating a Validated Pidlock

Source: https://docs.rs/pidlock/0.2.2/pidlock/struct.Pidlock.html?search=std%3A%3Avec

Shows how to create a new `Pidlock` instance using `new_validated`, which includes path validation for better cross-platform compatibility.

```rust
use pidlock::Pidlock;
use std::env;

// Valid path
let temp_dir = env::temp_dir();
let lock_path = temp_dir.join("valid.pid");
let lock = Pidlock::new_validated(&lock_path)?;
```

--------------------------------

### Handling Pidlock Conflicts

Source: https://docs.rs/pidlock/0.2.2/pidlock/struct.Pidlock.html?search=std%3A%3Avec

Illustrates how to manage situations where another process already holds the lock. It shows how to detect and react to the `LockExists` error.

```rust
use pidlock::{Pidlock, PidlockError};
use std::fs;

let temp_dir = std::env::temp_dir();
let lock_path = temp_dir.join("conflict_example.pid");

// First lock
let mut lock1 = Pidlock::new_validated(&lock_path)?;
lock1.acquire()?;

// Try to acquire the same lock from another instance
let mut lock2 = Pidlock::new_validated(&lock_path)?;
match lock2.acquire() {
    Err(PidlockError::LockExists) => {
        println!("Lock is already held by another process");
        // This is expected behavior
    }
    _ => panic!("Should have failed with LockExists"),
}

// Clean up
lock1.release()?;
```

--------------------------------

### Test Acquiring and Releasing a Lock

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html

Demonstrates the basic workflow of acquiring a lock, verifying its state, releasing it, and verifying the released state.

```rust
    #[test]
    fn test_acquire_release() {
        let temp_file = make_temp_file();
        let pid_path = temp_file.path().to_str().unwrap();
        let mut pidfile = Pidlock::new_validated(pid_path).unwrap();
        assert_eq!(pidfile.state, PidlockState::Released);

        pidfile.acquire().unwrap();
        assert_eq!(pidfile.state, PidlockState::Acquired);

        pidfile.release().unwrap();

        assert_eq!(pidfile.state, PidlockState::Released);
    }
```

--------------------------------

### Test File Permissions on Unix

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html

Verifies that a newly created and acquired pidlock file on Unix systems has the correct file permissions set to 600 (owner read/write only). This is crucial for security.

```rust
    #[test]
    #[cfg(unix)]
    fn test_file_permissions_unix() {
        use std::os::unix::fs::PermissionsExt;

        let temp_file = make_temp_file();
        let path = temp_file.path().to_string_lossy().to_string();

        let mut pidfile = Pidlock::new_validated(&path).unwrap();
        pidfile.acquire().unwrap();

        // Check that file has correct permissions (600 - owner read/write only)
        let metadata = std::fs::metadata(&path).unwrap();
        let mode = metadata.permissions().mode();
        assert_eq!(mode & 0o777, 0o600);

        pidfile.release().unwrap();
    }
```

--------------------------------

### Check Process Status on Non-Windows

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=

Uses the nix crate to send a null signal (effectively just checking existence) to a process to determine if it is running.

```rust
#[cfg(not(target_os = "windows"))]
{
    // We specify None as the signal, which equates to using 0 in `kill(2)`.
    // This means no signal is sent, but error checking is still performed.
    nix::sys::signal::kill(nix::unistd::Pid::from_raw(pid), None).is_ok()
}
```

--------------------------------

### Get Owner PID from Lock File

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=

Retrieves the PID of the process that owns the lock file. It handles cases where the file is missing, corrupted, empty, or contains an invalid/non-existent PID, automatically cleaning up stale files.

```rust
pub fn get_owner(&self) -> Result<Option<i32>, PidlockError> {
        let mut file = match fs::OpenOptions::new().read(true).open(&self.path) {
            Ok(file) => file,
            Err(_) => {
                return Ok(None);
            }
        };

        let mut contents = String::new();
        if file.read_to_string(&mut contents).is_err() {
            #[cfg(feature = "log")]
            warn!(
                "Removing corrupted/invalid pid file at {}",
                self.path.to_str().unwrap_or("<invalid>")
            );
            fs::remove_file(&self.path).map_err(PidlockError::from)?;
            return Ok(None);
        }

        match contents.trim().parse::<i32>() {
            Ok(pid) if validate_pid(pid) && process_exists(pid) => Ok(Some(pid)),
            Ok(_) => {
                #[cfg(feature = "log")]
                warn!(
                    "Removing stale pid file at {}",
                    self.path.to_str().unwrap_or("<invalid>")
                );
                fs::remove_file(&self.path).map_err(PidlockError::from)?;
                Ok(None)
            }
            Err(_) => {
                #[cfg(feature = "log")]
                warn!(
                    "Removing corrupted/invalid pid file at {}",
                    self.path.to_str().unwrap_or("<invalid>")
                );
                fs::remove_file(&self.path).map_err(PidlockError::from)?;
                Ok(None)
            }
        }
    }
```

--------------------------------

### Create Parent Directory if Missing

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=

Checks if the parent directory of a given path exists. If it does not exist, it attempts to create the directory and any necessary parent directories. Returns an error if creation fails.

```rust
    // Try to validate parent directory exists or can be created
    if let Some(parent) = path.parent()
        && !parent.exists()
    {
        // Check if we can potentially create the directory
        if let Err(e) = fs::create_dir_all(parent) {
            return Err(PidlockError::InvalidPath(
                InvalidPathError::ParentDirectoryCreationFailed {
                    path: parent.display().to_string(),
                    source: e,
                },
            ));
        }
    }
```

--------------------------------

### Test Get Owner with Invalid PID Range

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=std%3A%3Avec

Verifies that `get_owner` correctly handles cases where the PID file contains an invalid (negative) PID. The function should clean up the invalid PID file and return `None`.

```rust
let mut temp_file = make_temp_file();
let path = temp_file.path().to_string_lossy().to_string();

// Write a PID that's outside valid range (negative)
temp_file.write_all(b"-500").unwrap();
temp_file.flush().unwrap();

let pidfile = Pidlock::new_validated(&path).unwrap();
let result = pidfile.get_owner().unwrap();
// Invalid PID should be cleaned up
assert_eq!(result, None);
assert!(!std::path::Path::new(&path).exists());
```

--------------------------------

### Test Get Owner with Invalid PID Range

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html

Ensures that `get_owner` correctly handles cases where the PID file contains an invalid (negative) PID. The function should clean up the invalid PID file and return `None`.

```rust
    #[test]
    fn test_get_owner_with_invalid_pid_range() {
        let mut temp_file = make_temp_file();
        let path = temp_file.path().to_string_lossy().to_string();

        // Write a PID that's outside valid range (negative)
        temp_file.write_all(b"-500").unwrap();
        temp_file.flush().unwrap();

        let pidfile = Pidlock::new_validated(&path).unwrap();
        let result = pidfile.get_owner().unwrap();
        // Invalid PID should be cleaned up
        assert_eq!(result, None);
        assert!(!std::path::Path::new(&path).exists());
    }
```

--------------------------------

### Handling Pidlock Errors

Source: https://docs.rs/pidlock/0.2.2/pidlock/enum.PidlockError.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates how to acquire a lock and handle potential PidlockError variants, including LockExists, InvalidState, and other I/O or path-related errors.

```rust
use pidlock::{Pidlock, PidlockError};

let temp_dir = std::env::temp_dir();
let lock_path = temp_dir.join("error_example.pid");
let mut lock = Pidlock::new_validated(&lock_path)?;

match lock.acquire() {
    Ok(()) => {
        println!("Lock acquired successfully");
        lock.release()?;
    }
    Err(PidlockError::LockExists) => {
        println!("Another process is holding the lock");
    }
    Err(PidlockError::InvalidState) => {
        println!("Lock is in wrong state for this operation");
    }
    Err(e) => {
        println!("Other error: {}", e);
    }
}
```

--------------------------------

### Test Get Owner with Mixed Content

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html

Verifies that get_owner correctly parses only the PID from a file containing the PID followed by extra content. It asserts that the PID is correctly identified and the file is cleaned up if the PID does not exist.

```Rust
    #[test]
    fn test_get_owner_mixed_content() {
        let mut temp_file = make_temp_file();
        let path = temp_file.path().to_string_lossy().to_string();

        // Write PID with trailing content that should be ignored
        temp_file.write_all(b"12345 extra content").unwrap();
        temp_file.flush().unwrap();

        let pidfile = Pidlock::new_validated(&path).unwrap();
        let result = pidfile.get_owner().unwrap();
        // Should parse the PID part and clean up since 12345 likely doesn't exist
        assert_eq!(result, None);
        assert!(!std::path::Path::new(&path).exists());
    }
```

--------------------------------

### Pidlock::new

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=std%3A%3Avec

Creates a new Pidlock at the provided path. This method is deprecated and does not validate the path. Use `new_validated` for path validation and better cross-platform compatibility.

```APIDOC
## Pidlock::new

### Description
Creates a new Pidlock at the provided path. This method is deprecated and does not validate the path. Use `new_validated` for path validation and better cross-platform compatibility.

### Signature
`pub fn new(path: impl AsRef<Path>) -> Self`

### Parameters
* `path` - The path where the lock file will be created.
```

--------------------------------

### Pidlock::new

Source: https://docs.rs/pidlock/0.2.2/src/pidlock/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new Pidlock at the provided path. This method is deprecated and does not validate the path. Use `new_validated` for path validation and better cross-platform compatibility.

```APIDOC
## Pidlock::new

### Description
Creates a new Pidlock at the provided path. This method is deprecated and does not validate the path. Use `new_validated` for path validation and better cross-platform compatibility.

### Method
`pub fn new(path: impl AsRef<Path>) -> Self`

### Parameters
* `path` - (impl AsRef<Path>) - The path where the lock file will be created.

### Returns
* `Self` - A new Pidlock instance.
```
Tokens:
Raw