ZacharyZhang-NY
a02b555e66
Sweep every first-party crate source (1956 .rs files) to the project comment guidelines: delete redundant restatements, decorative banners, change narration, and end-of-line comments; keep and tighten the crucial ones (invariants, bug rationale, SAFETY blocks, ported-source attribution). No functional code changed. Every edit is proven comment-only against the prior tree by a comment-stripping lexer (string/char/raw-string aware) plus a separate doctest-fence check. Where removing a comment made rustfmt or clippy want to re-lay-out adjacent code, the minimal triggering comment is restored so code tokens stay byte-identical. Gates green: cargo fmt --all --check (0 diffs), cargo check and cargo clippy --workspace --all-targets (0 warnings). Adds scripts/check_codegen_comment_guidelines.py — the enforcement gate for these guidelines (flags banners, end-of-line comments, change narration, and commented-out code).
102 lines
3.4 KiB
Rust
102 lines
3.4 KiB
Rust
//! Windows system sleep/wake via `PowerRegisterSuspendResumeNotification`
|
|
//! with a `DEVICE_NOTIFY_CALLBACK` recipient — no hidden window or message
|
|
//! loop required (Windows 8+).
|
|
|
|
use std::os::raw::c_void;
|
|
|
|
use windows_sys::Win32::Foundation::HANDLE;
|
|
use windows_sys::Win32::System::Power::{
|
|
DEVICE_NOTIFY_SUBSCRIBE_PARAMETERS, HPOWERNOTIFY, PowerRegisterSuspendResumeNotification,
|
|
PowerUnregisterSuspendResumeNotification,
|
|
};
|
|
use windows_sys::Win32::UI::WindowsAndMessaging::DEVICE_NOTIFY_CALLBACK;
|
|
|
|
use super::{PowerCallback, PowerEvent};
|
|
|
|
// Power-broadcast event types (WM_POWERBROADCAST `wParam`).
|
|
const PBT_APMSUSPEND: u32 = 0x0004;
|
|
const PBT_APMRESUMESUSPEND: u32 = 0x0007;
|
|
const PBT_APMRESUMEAUTOMATIC: u32 = 0x0012;
|
|
|
|
const ERROR_SUCCESS: u32 = 0;
|
|
|
|
/// Heap-pinned so its address stays stable for the registration lifetime; the
|
|
/// raw pointer is handed to the OS as the callback context.
|
|
struct Context {
|
|
callback: PowerCallback,
|
|
}
|
|
|
|
pub(crate) struct Listener {
|
|
handle: *mut c_void,
|
|
// Kept alive (and freed in `Drop`) because the OS holds a raw pointer to it.
|
|
ctx: *mut Context,
|
|
}
|
|
|
|
// The OS invokes the callback on an arbitrary thread; the handle is only used
|
|
// to unregister. `PowerCallback` is `Send + Sync`.
|
|
unsafe impl Send for Listener {}
|
|
unsafe impl Sync for Listener {}
|
|
|
|
impl Listener {
|
|
pub(crate) fn start(callback: PowerCallback) -> Option<Self> {
|
|
let ctx = Box::into_raw(Box::new(Context { callback }));
|
|
|
|
let mut params = DEVICE_NOTIFY_SUBSCRIBE_PARAMETERS {
|
|
Callback: Some(power_callback),
|
|
Context: ctx as *mut c_void,
|
|
};
|
|
|
|
let mut handle: *mut c_void = std::ptr::null_mut();
|
|
let status = unsafe {
|
|
PowerRegisterSuspendResumeNotification(
|
|
DEVICE_NOTIFY_CALLBACK,
|
|
&mut params as *mut DEVICE_NOTIFY_SUBSCRIBE_PARAMETERS as HANDLE,
|
|
&mut handle,
|
|
)
|
|
};
|
|
|
|
if status != ERROR_SUCCESS || handle.is_null() {
|
|
unsafe { drop(Box::from_raw(ctx)) };
|
|
return None;
|
|
}
|
|
|
|
Some(Self { handle, ctx })
|
|
}
|
|
}
|
|
|
|
impl Drop for Listener {
|
|
fn drop(&mut self) {
|
|
// SAFETY: unregistering first guarantees the OS can no longer invoke
|
|
// the callback, so freeing `ctx` afterwards cannot race a live call.
|
|
unsafe {
|
|
PowerUnregisterSuspendResumeNotification(self.handle as HPOWERNOTIFY);
|
|
drop(Box::from_raw(self.ctx));
|
|
}
|
|
}
|
|
}
|
|
|
|
unsafe extern "system" fn power_callback(
|
|
context: *const c_void,
|
|
event_type: u32,
|
|
_setting: *const c_void,
|
|
) -> u32 {
|
|
// SAFETY: `context` is the `Context` pointer we registered with, and the
|
|
// registration is unregistered before that box is freed.
|
|
let ctx = unsafe { &*(context as *const Context) };
|
|
match event_type {
|
|
PBT_APMSUSPEND => (ctx.callback)(PowerEvent::WillSleep),
|
|
// A single resume can deliver both PBT_APMRESUMEAUTOMATIC and
|
|
// PBT_APMRESUMESUSPEND, so `DidWake` fires twice per wake. Intentional:
|
|
// lowering the sleep gate is idempotent, so do not "dedupe" this.
|
|
PBT_APMRESUMEAUTOMATIC | PBT_APMRESUMESUSPEND => (ctx.callback)(PowerEvent::DidWake),
|
|
_ => {}
|
|
}
|
|
ERROR_SUCCESS
|
|
}
|
|
|
|
pub(crate) fn current_power_state() -> crate::PowerState {
|
|
// No synchronous dark-wake query wired up on Windows; report Unknown so
|
|
// callers fall back to the suspend/resume notification path.
|
|
crate::PowerState::Unknown
|
|
}
|