Skip to main content

sk_hotkeys/
lib.rs

1//! System-wide hotkeys: a low-level hook (Windows) or event tap (macOS) feeding a chord engine.
2//! Hooks do no VM work and run no user callbacks; a separate worker calls the handler.
3use std::{
4    collections::{BTreeMap, BTreeSet, VecDeque},
5    sync::{
6        Arc, Condvar, Mutex,
7        atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering},
8    },
9    thread::JoinHandle,
10    time::Instant,
11};
12mod engine;
13#[cfg(windows)]
14mod native;
15#[cfg(target_os = "macos")]
16#[path = "macos.rs"]
17mod native;
18
19/// Set in a keyboard [`Button::code`] that holds a scan code rather than a virtual-key code.
20pub const RAW: u32 = 0x10000;
21/// Device 0 is the keyboard (Windows virtual-key codes, or [`RAW`] scan codes), device 1 the mouse
22/// (1 left, 2 right, 3 middle, 4 and 5 the side buttons).
23#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
24pub struct Button {
25    pub device: u8,
26    pub code: u32,
27}
28impl Button {
29    pub fn keyboard(code: u32) -> Self {
30        Self { device: 0, code }
31    }
32    fn normalized(mut self) -> Self {
33        if self.device == 0 {
34            self.code = match self.code {
35                0x10 => 0xa0,
36                0x11 => 0xa2,
37                0x12 => 0xa4,
38                other => other,
39            };
40        }
41        self
42    }
43    fn modifier(&self) -> bool {
44        self.device == 0 && matches!(self.code, 0xa0..=0xa5 | 0x5b | 0x5c)
45    }
46}
47#[derive(Debug, Default, Clone, PartialEq, Eq)]
48pub struct Chord {
49    pub buttons: Vec<Button>,
50}
51#[derive(Debug, Clone, PartialEq, Eq)]
52pub struct Binding {
53    pub id: String,
54    pub chord: Chord,
55    /// Consume the key events that complete the chord, so the focused app does not see them.
56    pub suppress: Option<bool>,
57    /// Minimum time between two down edges of this binding.
58    pub trigger_cooldown_ms: Option<u64>,
59}
60/// `phase` is "down" or "up". `generation` is the service's [`Hotkeys::current_generation`] when
61/// the event was produced.
62#[derive(Debug, Clone, PartialEq, Eq)]
63pub struct Fired {
64    pub id: String,
65    pub phase: String,
66    pub generation: u64,
67}
68impl Fired {
69    fn down(id: &str) -> Self {
70        Self {
71            id: id.into(),
72            phase: "down".into(),
73            generation: 0,
74        }
75    }
76    fn up(id: &str) -> Self {
77        Self {
78            id: id.into(),
79            phase: "up".into(),
80            generation: 0,
81        }
82    }
83}
84#[derive(Debug, Clone)]
85pub struct Status {
86    pub running: bool,
87    pub platform: String,
88    pub accessibility_granted: bool,
89    pub error: Option<String>,
90    pub restarts: u64,
91}
92type Handler = Arc<dyn Fn(Fired) + Send + Sync>;
93type CaptureCallback = Box<dyn FnOnce(Result<Chord, String>) + Send>;
94struct CaptureJob {
95    callback: CaptureCallback,
96    result: Result<Chord, String>,
97}
98#[derive(Default)]
99struct Queue {
100    events: VecDeque<Fired>,
101    urgent_up: BTreeMap<String, Fired>,
102    delivered_down: BTreeSet<String>,
103    captures: VecDeque<CaptureJob>,
104    closed: bool,
105}
106struct Dispatch {
107    queue: Mutex<Queue>,
108    wake: Condvar,
109    captures_reserved: AtomicUsize,
110    handler: Arc<Mutex<Option<Handler>>>,
111    generation: AtomicU64,
112}
113impl Dispatch {
114    fn new(handler: Arc<Mutex<Option<Handler>>>, generation: u64) -> Arc<Self> {
115        Arc::new(Self {
116            queue: Mutex::new(Queue::default()),
117            wake: Condvar::new(),
118            captures_reserved: AtomicUsize::new(0),
119            handler,
120            generation: AtomicU64::new(generation),
121        })
122    }
123    fn invalidate(&self, generation: u64) {
124        let mut queue = self.queue.lock().unwrap_or_else(|p| p.into_inner());
125        queue.events.clear();
126        queue.urgent_up.clear();
127        let held: Vec<_> = queue.delivered_down.iter().cloned().collect();
128        for id in held {
129            let mut event = Fired::up(&id);
130            event.generation = generation;
131            queue.urgent_up.insert(id, event);
132        }
133        self.generation.store(generation, Ordering::Release);
134        self.wake.notify_one();
135    }
136    fn events(&self, events: Vec<Fired>) {
137        let mut queue = self.queue.lock().unwrap_or_else(|p| p.into_inner());
138        for event in events {
139            if event.generation != self.generation.load(Ordering::Acquire) {
140                continue;
141            }
142            if event.phase == "up" && queue.urgent_up.contains_key(&event.id) {
143                queue.events.retain(|old| old.id != event.id);
144                continue;
145            }
146            if queue.events.len() < 256 {
147                queue.events.push_back(event);
148            } else {
149                // Overloaded listeners may miss a press, but must never retain
150                // a hold. Remove queued presses for this ID before its urgent up.
151                queue.events.retain(|old| old.id != event.id);
152                if queue.delivered_down.contains(&event.id) {
153                    queue.urgent_up.insert(
154                        event.id.clone(),
155                        Fired {
156                            phase: "up".into(),
157                            ..event
158                        },
159                    );
160                }
161            }
162        }
163        self.wake.notify_one();
164    }
165    fn reserve_capture(&self) -> bool {
166        self.captures_reserved
167            .fetch_update(Ordering::AcqRel, Ordering::Acquire, |n| {
168                (n < 16).then_some(n + 1)
169            })
170            .is_ok()
171    }
172    fn capture(&self, callback: CaptureCallback, result: Result<Chord, String>) {
173        self.queue
174            .lock()
175            .unwrap_or_else(|p| p.into_inner())
176            .captures
177            .push_back(CaptureJob { callback, result });
178        self.wake.notify_one();
179    }
180    fn close(&self) {
181        self.queue.lock().unwrap_or_else(|p| p.into_inner()).closed = true;
182        self.wake.notify_all();
183    }
184    fn run(self: Arc<Self>) {
185        enum Job {
186            Event(Fired),
187            Capture(CaptureJob),
188        }
189        loop {
190            let job = {
191                let mut queue = self.queue.lock().unwrap_or_else(|p| p.into_inner());
192                loop {
193                    if let Some(job) = queue.captures.pop_front() {
194                        break Some(Job::Capture(job));
195                    }
196                    if let Some((_, event)) = queue.urgent_up.pop_first() {
197                        if queue.delivered_down.remove(&event.id) {
198                            break Some(Job::Event(event));
199                        }
200                        continue;
201                    }
202                    if let Some(event) = queue.events.pop_front() {
203                        if event.phase == "down" {
204                            // Bound the number of delivered holds even while
205                            // producers continually replace binding IDs.
206                            if queue.delivered_down.len() >= 128
207                                || !queue.delivered_down.insert(event.id.clone())
208                            {
209                                continue;
210                            }
211                        } else if !queue.delivered_down.remove(&event.id) {
212                            continue;
213                        }
214                        break Some(Job::Event(event));
215                    }
216                    if queue.closed {
217                        break None;
218                    }
219                    queue = self.wake.wait(queue).unwrap_or_else(|p| p.into_inner());
220                }
221            };
222            match job {
223                None => break,
224                Some(Job::Capture(job)) => {
225                    let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
226                        (job.callback)(job.result)
227                    }));
228                    self.captures_reserved.fetch_sub(1, Ordering::AcqRel);
229                }
230                Some(Job::Event(event)) => {
231                    if event.phase == "down"
232                        && event.generation != self.generation.load(Ordering::Acquire)
233                    {
234                        continue;
235                    }
236                    let handler = self
237                        .handler
238                        .lock()
239                        .unwrap_or_else(|p| p.into_inner())
240                        .clone();
241                    if let Some(handler) = handler {
242                        let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
243                            handler(event)
244                        }));
245                    }
246                }
247            }
248        }
249    }
250}
251#[derive(Default)]
252struct State {
253    engine: engine::Engine,
254    capture: Option<(CaptureCallback, Arc<Dispatch>)>,
255}
256struct Workers {
257    input: JoinHandle<()>,
258    notify: JoinHandle<()>,
259    dispatch: Arc<Dispatch>,
260}
261
262pub struct Hotkeys {
263    state: Mutex<State>,
264    handler: Arc<Mutex<Option<Handler>>>,
265    dispatch: Mutex<Option<Arc<Dispatch>>>,
266    workers: Mutex<Option<Workers>>,
267    running: AtomicBool,
268    stopping: AtomicBool,
269    thread_id: AtomicU32,
270    restarts: AtomicU64,
271    generation: AtomicU64,
272    error: Mutex<Option<String>>,
273}
274impl Hotkeys {
275    pub fn new() -> Arc<Self> {
276        Arc::new(Self {
277            state: Mutex::new(State::default()),
278            handler: Arc::new(Mutex::new(None)),
279            dispatch: Mutex::new(None),
280            workers: Mutex::new(None),
281            running: AtomicBool::new(false),
282            stopping: AtomicBool::new(false),
283            thread_id: AtomicU32::new(0),
284            restarts: AtomicU64::new(0),
285            generation: AtomicU64::new(1),
286            error: Mutex::new(None),
287        })
288    }
289    pub fn set_handler(&self, handler: Arc<dyn Fn(Fired) + Send + Sync>) {
290        *self.handler.lock().unwrap_or_else(|p| p.into_inner()) = Some(handler);
291    }
292    pub fn start(self: &Arc<Self>) -> Result<(), String> {
293        if self.stopping.load(Ordering::Acquire) {
294            return Err("hotkeys are stopping".into());
295        }
296        let mut workers = self.workers.lock().unwrap_or_else(|p| p.into_inner());
297        if self.running.load(Ordering::Acquire) {
298            return Ok(());
299        }
300        if workers.is_some() {
301            return Err("hotkey hook stopped unexpectedly; call restart".into());
302        }
303        #[cfg(not(any(windows, target_os = "macos")))]
304        {
305            self.fail("global hotkeys are unsupported on this platform".into());
306            return Err("global hotkeys are unsupported on this platform".into());
307        }
308        #[cfg(any(windows, target_os = "macos"))]
309        {
310            let dispatch = Dispatch::new(Arc::clone(&self.handler), self.current_generation());
311            let notifier = Arc::clone(&dispatch);
312            let notify = std::thread::Builder::new()
313                .name("sk-hotkeys-events".into())
314                .spawn(move || notifier.run())
315                .map_err(|e| e.to_string())?;
316            *self.dispatch.lock().unwrap_or_else(|p| p.into_inner()) = Some(Arc::clone(&dispatch));
317            // The Mac worker publishes running before ready and owns every
318            // subsequent failure. Clear a previous attempt before it can run.
319            #[cfg(target_os = "macos")]
320            {
321                *self.error.lock().unwrap_or_else(|p| p.into_inner()) = None;
322            }
323            let owner = Arc::downgrade(self);
324            let (ready, receive) = std::sync::mpsc::sync_channel(1);
325            let input = match std::thread::Builder::new()
326                .name("sk-hotkeys".into())
327                .spawn(move || native::run(owner, ready))
328            {
329                Ok(thread) => thread,
330                Err(error) => {
331                    dispatch.close();
332                    join(notify);
333                    self.dispatch
334                        .lock()
335                        .unwrap_or_else(|p| p.into_inner())
336                        .take();
337                    return Err(error.to_string());
338                }
339            };
340            let result = receive
341                .recv_timeout(std::time::Duration::from_secs(3))
342                .unwrap_or_else(|_| Err("timed out starting global hotkey hooks".into()));
343            // A late Mac startup must see its readiness receiver disappear and
344            // release the event tap instead of entering a loop nobody owns.
345            drop(receive);
346            if let Err(error) = result {
347                native::wake_stop(self.thread_id.load(Ordering::Acquire));
348                join(input);
349                dispatch.close();
350                join(notify);
351                self.dispatch
352                    .lock()
353                    .unwrap_or_else(|p| p.into_inner())
354                    .take();
355                self.fail(error.clone());
356                return Err(error);
357            }
358            self.accept_startup_ready();
359            *workers = Some(Workers {
360                input,
361                notify,
362                dispatch,
363            });
364            Ok(())
365        }
366    }
367    fn accept_startup_ready(&self) {
368        // The Windows worker relies on its parent's ready handshake. The Mac
369        // worker publishes before sending ready; it may already have failed or
370        // lost permission by the time this thread wakes, so never overwrite it.
371        #[cfg(windows)]
372        {
373            self.running.store(true, Ordering::Release);
374            *self.error.lock().unwrap_or_else(|p| p.into_inner()) = None;
375        }
376    }
377    pub fn set_bindings(&self, bindings: Vec<Binding>) -> Result<bool, String> {
378        let bindings = normalize_bindings(bindings)?;
379        let mut state = self.state.lock().unwrap_or_else(|p| p.into_inner());
380        let (changed, output) = state.engine.set_bindings(bindings);
381        if changed {
382            self.invalidate_notifications();
383        }
384        self.deliver(&mut state, output);
385        #[cfg(any(windows, target_os = "macos"))]
386        if changed {
387            state.engine.seed(native::held_modifiers());
388            native::wake_sync(self.thread_id.load(Ordering::Acquire));
389        }
390        Ok(changed)
391    }
392    pub fn would_change(&self, bindings: &[Binding]) -> Result<bool, String> {
393        let normalized = normalize_bindings(bindings.to_vec())?;
394        let state = self.state.lock().unwrap_or_else(|p| p.into_inner());
395        Ok(state.engine.bindings() != normalized.as_slice())
396    }
397    pub fn current_generation(&self) -> u64 {
398        self.generation.load(Ordering::Acquire)
399    }
400    pub fn is_current(&self, event: &Fired) -> bool {
401        event.phase == "up" || event.generation == self.current_generation()
402    }
403    // Called only while the engine lock is held: event creation and generation
404    // changes share one ordering even if the notification worker is stalled.
405    fn invalidate_notifications(&self) {
406        let generation = self.generation.fetch_add(1, Ordering::AcqRel) + 1;
407        if let Some(dispatch) = self
408            .dispatch
409            .lock()
410            .unwrap_or_else(|p| p.into_inner())
411            .as_ref()
412        {
413            dispatch.invalidate(generation);
414        }
415    }
416    pub fn is_running(&self) -> bool {
417        self.running.load(Ordering::Acquire)
418    }
419    pub fn status(&self) -> Status {
420        Status {
421            running: self.running.load(Ordering::Acquire),
422            platform: std::env::consts::OS.into(),
423            accessibility_granted: self.accessibility_granted(),
424            error: self.error.lock().unwrap_or_else(|p| p.into_inner()).clone(),
425            restarts: self.restarts.load(Ordering::Acquire),
426        }
427    }
428    pub fn accessibility_granted(&self) -> bool {
429        #[cfg(target_os = "macos")]
430        {
431            native::accessibility_granted()
432        }
433        #[cfg(not(target_os = "macos"))]
434        {
435            cfg!(windows)
436        }
437    }
438    /// Shows the macOS Accessibility prompt. Call it only from an explicit user action.
439    pub fn request_accessibility(&self) -> bool {
440        #[cfg(target_os = "macos")]
441        {
442            native::request_accessibility()
443        }
444        #[cfg(not(target_os = "macos"))]
445        {
446            cfg!(windows)
447        }
448    }
449    pub fn restart(self: &Arc<Self>) -> Result<bool, String> {
450        self.stop();
451        self.start()?;
452        self.restarts.fetch_add(1, Ordering::AcqRel);
453        Ok(true)
454    }
455    pub fn capture_once(
456        &self,
457        callback: impl FnOnce(Result<Chord, String>) + Send + 'static,
458    ) -> Result<(), String> {
459        if !self.running.load(Ordering::Acquire) {
460            return Err("hotkeys are not running".into());
461        }
462        let dispatch = self
463            .dispatch
464            .lock()
465            .unwrap_or_else(|p| p.into_inner())
466            .clone()
467            .ok_or("hotkeys are not running")?;
468        let mut state = self.state.lock().unwrap_or_else(|p| p.into_inner());
469        if !self.running.load(Ordering::Acquire) {
470            return Err("hotkeys are not running".into());
471        }
472        if !dispatch.reserve_capture() {
473            return Err("hotkey capture callback queue is busy".into());
474        }
475        #[cfg(any(windows, target_os = "macos"))]
476        let held = native::held_modifiers();
477        #[cfg(not(any(windows, target_os = "macos")))]
478        let held = Vec::new();
479        self.invalidate_notifications();
480        let output = state.engine.begin_capture(Instant::now(), held);
481        self.deliver(&mut state, output); // settles the previous capture before installing its successor
482        state.capture = Some((Box::new(callback), dispatch));
483        #[cfg(any(windows, target_os = "macos"))]
484        native::wake_sync(self.thread_id.load(Ordering::Acquire));
485        Ok(())
486    }
487    pub fn cancel_capture(&self) {
488        let mut state = self.state.lock().unwrap_or_else(|p| p.into_inner());
489        let output = state.engine.cancel_capture();
490        self.deliver(&mut state, output);
491    }
492    pub fn stop(&self) {
493        if self.stopping.swap(true, Ordering::AcqRel) {
494            return;
495        }
496        self.running.store(false, Ordering::Release);
497        let workers = self
498            .workers
499            .lock()
500            .unwrap_or_else(|p| p.into_inner())
501            .take();
502        self.reset();
503        if let Some(workers) = workers {
504            #[cfg(any(windows, target_os = "macos"))]
505            native::wake_stop(self.thread_id.load(Ordering::Acquire));
506            // No lifecycle/state lock is held while a callback or input thread exits.
507            join(workers.input);
508            workers.dispatch.close();
509            join(workers.notify);
510        }
511        self.dispatch
512            .lock()
513            .unwrap_or_else(|p| p.into_inner())
514            .take();
515        self.stopping.store(false, Ordering::Release);
516    }
517    fn deliver(&self, state: &mut State, mut output: engine::Output) {
518        let generation = self.current_generation();
519        for event in &mut output.events {
520            event.generation = generation;
521        }
522        if let Some(dispatch) = self
523            .dispatch
524            .lock()
525            .unwrap_or_else(|p| p.into_inner())
526            .as_ref()
527        {
528            dispatch.events(output.events);
529        }
530        if let Some(result) = output.capture {
531            if let Some((callback, dispatch)) = state.capture.take() {
532                dispatch.capture(callback, result);
533            }
534        }
535    }
536    fn input(&self, button: Button, down: bool) -> bool {
537        let mut state = self.state.lock().unwrap_or_else(|p| p.into_inner());
538        let output = state.engine.input(button, down, Instant::now());
539        let suppress = output.suppress;
540        self.deliver(&mut state, output);
541        suppress
542    }
543    fn tick(&self, now: Instant) {
544        let mut state = self.state.lock().unwrap_or_else(|p| p.into_inner());
545        let output = state.engine.tick(now);
546        self.deliver(&mut state, output);
547    }
548    fn reset(&self) {
549        let mut state = self.state.lock().unwrap_or_else(|p| p.into_inner());
550        self.invalidate_notifications();
551        let output = state.engine.reset();
552        self.deliver(&mut state, output);
553    }
554    fn fail(&self, error: String) {
555        self.running.store(false, Ordering::Release);
556        *self.error.lock().unwrap_or_else(|p| p.into_inner()) = Some(error);
557    }
558}
559impl Drop for Hotkeys {
560    fn drop(&mut self) {
561        self.stop();
562    }
563}
564fn join(thread: JoinHandle<()>) {
565    if thread.thread().id() != std::thread::current().id() {
566        let _ = thread.join();
567    }
568}
569fn normalize_bindings(mut bindings: Vec<Binding>) -> Result<Vec<Binding>, String> {
570    if bindings.len() > 128 {
571        return Err("at most 128 hotkey bindings are allowed".into());
572    }
573    let mut ids = BTreeSet::new();
574    for binding in &mut bindings {
575        if binding.id.is_empty()
576            || binding.id.len() > 128
577            || binding.id.contains('\0')
578            || !ids.insert(binding.id.clone())
579        {
580            return Err("hotkey IDs must be unique nonempty strings of at most 128 bytes".into());
581        }
582        if binding.chord.buttons.len() > 16 || binding.trigger_cooldown_ms.unwrap_or(0) > 60_000 {
583            return Err("hotkey chord or cooldown exceeds its limit".into());
584        }
585        for button in &mut binding.chord.buttons {
586            *button = button.normalized();
587            let valid = match button.device {
588                0 => {
589                    (1..=255).contains(&button.code)
590                        || (button.code & RAW != 0
591                            && button.code <= 0x1ffff
592                            && button.code & 0xffff != 0)
593                }
594                1 => (1..=5).contains(&button.code),
595                _ => false,
596            };
597            if !valid {
598                return Err("invalid hotkey device or Windows virtual-key/raw code".into());
599            }
600        }
601        binding.chord.buttons.sort();
602        binding.chord.buttons.dedup();
603    }
604    bindings.retain(|b| !b.chord.buttons.is_empty());
605    bindings.sort_by(|a, b| a.id.cmp(&b.id));
606    Ok(bindings)
607}
608
609#[cfg(test)]
610mod tests {
611    use super::*;
612    fn held_binding(code: u32) -> Binding {
613        Binding {
614            id: "ptt".into(),
615            chord: Chord {
616                buttons: vec![Button::keyboard(code)],
617            },
618            suppress: None,
619            trigger_cooldown_ms: None,
620        }
621    }
622    fn queued_service() -> (Arc<Hotkeys>, Arc<Dispatch>) {
623        let service = Hotkeys::new();
624        let dispatch = Dispatch::new(Arc::clone(&service.handler), service.current_generation());
625        *service.dispatch.lock().unwrap() = Some(dispatch.clone());
626        (service, dispatch)
627    }
628    #[cfg(target_os = "macos")]
629    #[test]
630    fn late_startup_ready_cannot_erase_a_mac_worker_failure() {
631        let service = Hotkeys::new();
632        // The worker sent ready, then the tap was disabled before the parent
633        // received it. Model that ordering without scheduling or OS permission.
634        service.running.store(true, Ordering::Release);
635        service.fail("the tap was disabled after ready".into());
636        service.accept_startup_ready();
637        assert!(!service.running.load(Ordering::Acquire));
638        assert_eq!(
639            service.error.lock().unwrap().as_deref(),
640            Some("the tap was disabled after ready")
641        );
642    }
643    #[test]
644    fn generic_modifiers_normalize_left_and_raw_keys_remain_distinct() {
645        let bindings = normalize_bindings(vec![Binding {
646            id: "x".into(),
647            chord: Chord {
648                buttons: vec![
649                    Button::keyboard(0x11),
650                    Button::keyboard(0xa2),
651                    Button::keyboard(RAW | 0x0e1c),
652                ],
653            },
654            suppress: None,
655            trigger_cooldown_ms: None,
656        }])
657        .unwrap();
658        assert_eq!(
659            bindings[0].chord.buttons,
660            [Button::keyboard(0xa2), Button::keyboard(RAW | 0x0e1c)]
661        );
662    }
663    #[test]
664    fn overflow_queue_cannot_deliver_a_stale_down_after_an_urgent_release() {
665        let dispatch = Dispatch::new(Arc::new(Mutex::new(None)), 0);
666        dispatch
667            .queue
668            .lock()
669            .unwrap()
670            .delivered_down
671            .insert("x".into());
672        dispatch.events((0..256).map(|_| Fired::down("x")).collect());
673        dispatch.events(vec![Fired::up("x")]);
674        let queue = dispatch.queue.lock().unwrap();
675        assert!(queue.events.is_empty());
676        assert_eq!(queue.urgent_up.get("x"), Some(&Fired::up("x")));
677    }
678    #[test]
679    fn stalled_listener_reconfiguration_does_not_accumulate_undelivered_releases() {
680        let dispatch = Dispatch::new(Arc::new(Mutex::new(None)), 0);
681        dispatch.events(
682            (0..256)
683                .map(|i| Fired::down(&format!("queued-{i}")))
684                .collect(),
685        );
686        for i in 0..10_000 {
687            dispatch.events(vec![
688                Fired::down(&format!("new-{i}")),
689                Fired::up(&format!("new-{i}")),
690            ]);
691        }
692        let queue = dispatch.queue.lock().unwrap();
693        assert_eq!(queue.events.len(), 256);
694        assert!(queue.urgent_up.is_empty());
695    }
696    #[test]
697    fn changed_bindings_invalidate_queued_down_and_stamp_balanced_release() {
698        let (service, dispatch) = queued_service();
699        service.set_bindings(vec![held_binding(0x70)]).unwrap();
700        service.input(Button::keyboard(0x70), true);
701        let in_flight = {
702            let mut queue = dispatch.queue.lock().unwrap();
703            let event = queue.events.pop_front().unwrap();
704            queue.delivered_down.insert(event.id.clone());
705            event
706        };
707        assert!(service.is_current(&in_flight));
708        assert!(service.set_bindings(vec![held_binding(0x71)]).unwrap());
709        assert!(
710            !service.is_current(&in_flight),
711            "popped events keep their original generation"
712        );
713        let queue = dispatch.queue.lock().unwrap();
714        assert!(queue.events.iter().all(|event| event.phase != "down"));
715        let release = queue.urgent_up.get("ptt").unwrap();
716        assert_eq!(release.generation, service.current_generation());
717        assert!(service.is_current(release));
718        assert_eq!((release.id.as_str(), release.phase.as_str()), ("ptt", "up"));
719    }
720    #[test]
721    fn capture_and_reset_discard_backlogged_downs() {
722        let (service, dispatch) = queued_service();
723        service.set_bindings(vec![held_binding(0x70)]).unwrap();
724        service.input(Button::keyboard(0x70), true);
725        let old = dispatch
726            .queue
727            .lock()
728            .unwrap()
729            .events
730            .front()
731            .unwrap()
732            .clone();
733        service.running.store(true, Ordering::Release);
734        service.capture_once(|_| {}).unwrap();
735        assert!(!service.is_current(&old));
736        assert!(
737            dispatch
738                .queue
739                .lock()
740                .unwrap()
741                .events
742                .iter()
743                .all(|event| event.phase != "down")
744        );
745        service.cancel_capture();
746        service.input(Button::keyboard(0x70), false);
747        service.input(Button::keyboard(0x70), true);
748        let old = dispatch
749            .queue
750            .lock()
751            .unwrap()
752            .events
753            .back()
754            .unwrap()
755            .clone();
756        assert_eq!(old.phase, "down");
757        service.reset();
758        assert!(!service.is_current(&old));
759        assert!(
760            dispatch
761                .queue
762                .lock()
763                .unwrap()
764                .events
765                .iter()
766                .all(|event| event.phase != "down")
767        );
768        let old_up = Fired {
769            phase: "up".into(),
770            ..old
771        };
772        assert!(
773            service.is_current(&old_up),
774            "an already posted release must remain deliverable"
775        );
776    }
777    #[test]
778    fn unchanged_binding_does_not_release_a_hold_or_advance_generation() {
779        let (service, dispatch) = queued_service();
780        let binding = held_binding(0x70);
781        service.set_bindings(vec![binding.clone()]).unwrap();
782        service.input(Button::keyboard(0x70), true);
783        let before = service.current_generation();
784        assert!(
785            !service
786                .would_change(std::slice::from_ref(&binding))
787                .unwrap()
788        );
789        assert!(!service.set_bindings(vec![binding]).unwrap());
790        assert_eq!(service.current_generation(), before);
791        assert_eq!(dispatch.queue.lock().unwrap().events.len(), 1);
792        assert_eq!(dispatch.queue.lock().unwrap().events[0].phase, "down");
793        service.input(Button::keyboard(0x70), false);
794        let queue = dispatch.queue.lock().unwrap();
795        assert_eq!(
796            queue
797                .events
798                .iter()
799                .map(|event| event.phase.as_str())
800                .collect::<Vec<_>>(),
801            ["down", "up"]
802        );
803    }
804}