Struct CloseRequest 

pub struct CloseRequest { /* private fields */ }

An owned, marshalable request to close one handle.

The request owns the handle it will close, so the handle cannot be closed by anyone else in the meantime, and cannot outlive the request unclosed.

Example

use std::fs;

use windows_namespace_request_sys::close::CloseRequest;

let path = std::env::temp_dir().join(format!("wnrs-close-{}.tmp", std::process::id()));
fs::write(&path, b"example")?;
let file = fs::File::open(&path)?;

// The close is a value now, so it can be performed wherever blocking is
// acceptable rather than wherever the handle happens to be dropped.
let request = CloseRequest::for_handle(file.into());
request.perform()?;

Example: the routine travels with the handle

A change notification is closed with FindCloseChangeNotification, and CloseHandle is silently wrong for it. A caller never has to know that, because the constructor pairs them:

use std::fs;

use windows_namespace_request_sys::close::CloseRequest;
use windows_namespace_request_sys::prepare;
use windows_namespace_request_sys::watch::{NotifyFilter, WatchDirectory};
use wtf_string::Wtf16String;

let directory = std::env::temp_dir().join(format!("wnrs-cr-{}", std::process::id()));
let _ = fs::remove_dir_all(&directory);
fs::create_dir_all(&directory)?;
let text = directory.to_str().expect("a temporary path is valid UTF-8");

let notification = WatchDirectory::new(prepare(&Wtf16String::from(text))?)
    .with_filter(NotifyFilter::FILE_NAME)
    .perform()?;

let request = CloseRequest::for_change_notification(notification);
assert!(format!("{request:?}").contains("FindCloseChangeNotification"));
request.perform()?;

Example: performing consumes the request

This is what makes closing twice through this type impossible – the second call does not compile:

use std::fs;

use windows_namespace_request_sys::close::CloseRequest;

let path = std::env::temp_dir().join("wnrs-doc-double-close.tmp");
fs::write(&path, b"x").unwrap();
let request = CloseRequest::for_handle(fs::File::open(&path).unwrap().into());

request.perform().unwrap();
request.perform().unwrap(); // error: use of moved value

Implementations

impl CloseRequest

pub fn for_handle(handle: OwnedHandle) -> Self

A request to close an ordinary handle with CloseHandle.

pub fn for_change_notification(notification: ChangeNotification) -> Self

A request to close a change notification with FindCloseChangeNotification.

Provided by name so a caller never has to know which routine is right: this is precisely the pairing the audit found a close entry cannot assume.

pub unsafe fn from_raw(handle: HANDLE, close: CloseFn) -> Self

A request to close handle with a caller-supplied routine.

The escape hatch for a handle whose close routine this crate does not know about, so an unanticipated variant needs no change here.

Safety

handle must be a live handle that the caller owns and gives up, and close must be the correct routine for it.

pub fn handle(&self) -> HANDLE

The handle this request will close.

pub fn perform(self) -> Outcome<()>

Performs the close on the calling thread.

Consumes the request, so a handle cannot be closed twice through this type.

Errors

Returns the raw Win32 code, unaltered. The handle is closed either way: a failed close is not a close that can be retried.

Trait Implementations

impl ConsumingRequest for CloseRequest

type Error = Win32Error

How performing it can fail.

type Output = ()

What performing the request produces.

fn perform(self) -> Outcome<()>

Performs the request on the calling thread, consuming it.

impl Debug for CloseRequest

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for CloseRequest

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Send for CloseRequest

impl Sync for CloseRequest