#![allow(unsafe_code)]
use std::io;
use std::os::windows::io::{AsHandle, AsRawHandle, BorrowedHandle, OwnedHandle};
use std::time::Duration;
use windows_sys::Win32::System::Threading::{CreateMutexW, ReleaseMutex};
use crate::handle::{owned_from_creation, wait, WaitOutcome};
use crate::security::SecurityDescriptor;
use crate::wide::wide_null;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum MutexAcquisition {
Acquired,
Abandoned,
TimedOut,
}
#[derive(Debug)]
pub struct NamedMutex(OwnedHandle);
impl NamedMutex {
pub fn create(name: &str, descriptor: &SecurityDescriptor) -> io::Result<Self> {
let name = wide_null(name)?;
let attributes = descriptor.attributes(false);
let handle = unsafe { CreateMutexW(attributes.as_ptr(), 0, name.as_ptr()) };
Ok(Self(owned_from_creation(handle)?))
}
pub fn acquire(&self, timeout: Duration) -> io::Result<MutexAcquisition> {
Ok(match wait(&self.0, Some(timeout))? {
WaitOutcome::Signaled => MutexAcquisition::Acquired,
WaitOutcome::Abandoned => MutexAcquisition::Abandoned,
WaitOutcome::TimedOut => MutexAcquisition::TimedOut,
})
}
}
impl AsHandle for NamedMutex {
fn as_handle(&self) -> BorrowedHandle<'_> {
self.0.as_handle()
}
}
impl Drop for NamedMutex {
fn drop(&mut self) {
unsafe { ReleaseMutex(self.0.as_raw_handle()) };
}
}
#[cfg(test)]
mod tests {
use std::time::Duration;
use super::{MutexAcquisition, NamedMutex};
use crate::security::{ObjectSecurityDescriptor, OwnedSid, SecurityDescriptor};
fn descriptor() -> SecurityDescriptor {
SecurityDescriptor::from_sddl("D:P(A;;GA;;;SY)(A;;GA;;;BA)(A;;GA;;;OW)").unwrap()
}
#[test]
fn a_held_mutex_times_out_for_another_thread_and_frees_on_drop() {
let name = format!(r"Local\win-custody-mutex-{}", std::process::id());
let first = NamedMutex::create(&name, &descriptor()).unwrap();
assert_eq!(
first.acquire(Duration::from_millis(50)).unwrap(),
MutexAcquisition::Acquired
);
let second = NamedMutex::create(&name, &descriptor()).unwrap();
let waiter = std::thread::spawn(move || second.acquire(Duration::from_millis(50)).unwrap());
assert_eq!(waiter.join().unwrap(), MutexAcquisition::TimedOut);
drop(first);
let third = NamedMutex::create(&name, &descriptor()).unwrap();
let waiter = std::thread::spawn(move || third.acquire(Duration::from_millis(500)).unwrap());
assert_eq!(waiter.join().unwrap(), MutexAcquisition::Acquired);
}
#[test]
fn the_created_mutex_carries_the_requested_dacl() {
let name = format!(r"Local\win-custody-dacl-{}", std::process::id());
let mutex = NamedMutex::create(&name, &descriptor()).unwrap();
let queried = ObjectSecurityDescriptor::query_kernel_object(&mutex).unwrap();
let dacl = queried.dacl().unwrap();
let system = OwnedSid::from_string("SY").unwrap();
assert!(dacl.allowed_aces().any(|ace| ace.trustee_matches(&system)));
}
}