Skip to main content

wgame_app_input/
lib.rs

1//! Input event multiplexer for window events.
2//!
3//! Provides event distribution to multiple consumers with configurable capacity.
4
5#![forbid(unsafe_code)]
6
7use std::{
8    cell::{Cell, RefCell},
9    collections::VecDeque,
10    num::NonZero,
11    pin::Pin,
12    rc::{Rc, Weak},
13    task::{Context, Poll, Waker},
14};
15
16use futures::Stream;
17pub use winit::{
18    event::{self, WindowEvent as Event},
19    keyboard,
20};
21
22/// Event multiplexer that distributes events to multiple input streams.
23#[derive(Default)]
24pub struct EventHandler {
25    states: Vec<Weak<State>>,
26    terminated: bool,
27}
28
29/// An independent buffered stream of window events.
30///
31/// [`Self::try_next`] drains queued events without waiting. With a direct `futures`
32/// dependency, `StreamExt::next()` waits asynchronously. Redraw events are excluded
33/// because the window loop handles them separately. Use
34/// [`Self::set_include_redraws`] for an event-driven drawing loop.
35///
36/// The default capacity is 1024 events; overflow discards the oldest event.
37/// [`Self::set_capacity`] with `None` makes the queue unbounded. Overflow can lose
38/// a key transition: select a suitable capacity or track focus/state explicitly
39/// when complete input history matters.
40///
41/// Handler termination or drop wakes consumers. They drain buffered events before
42/// receiving `None` from the stream.
43pub struct Input {
44    state: Rc<State>,
45}
46
47struct State {
48    capacity: Cell<Option<NonZero<usize>>>,
49    terminated: Cell<bool>,
50    include_redraws: Cell<bool>,
51    events: RefCell<VecDeque<Event>>,
52    waker: Cell<Waker>,
53}
54
55impl EventHandler {
56    /// Push an event to all registered input streams.
57    pub fn push(&mut self, event: Event) {
58        if self.terminated {
59            return;
60        }
61        self.states.retain_mut(|state| match state.upgrade() {
62            Some(state) => {
63                match &event {
64                    Event::RedrawRequested if !state.include_redraws.get() => (),
65                    _ => state.push_event(event.clone()),
66                }
67                true
68            }
69            None => false,
70        });
71    }
72
73    /// Wake all consumers; streams drain their buffered events before ending.
74    pub fn terminate(&mut self) {
75        self.terminated = true;
76        for state in self.states.drain(..).filter_map(|s| s.upgrade()) {
77            state.terminated.set(true);
78            state.waker.replace(Waker::noop().clone()).wake();
79        }
80    }
81
82    /// Create a new input stream from this handler.
83    pub fn input(&mut self) -> Input {
84        self.states.retain(|state| state.strong_count() > 0);
85        let state = Rc::new(State {
86            terminated: Cell::new(self.terminated),
87            ..Default::default()
88        });
89        self.states.push(Rc::downgrade(&state));
90        Input { state }
91    }
92}
93
94impl Input {
95    /// Include OS redraw notifications in this stream (disabled by default).
96    /// This also includes redraws requested by your own drawing loop; consume them
97    /// when rendering so they do not keep an otherwise idle loop awake.
98    pub fn set_include_redraws(&mut self, include: bool) {
99        self.state.include_redraws.set(include);
100    }
101
102    /// Get the current event capacity for this input stream.
103    pub fn capacity(&self) -> Option<NonZero<usize>> {
104        self.state.capacity.get()
105    }
106
107    /// Set the event capacity for this input stream.
108    pub fn set_capacity(&mut self, capacity: Option<NonZero<usize>>) {
109        self.state.capacity.set(capacity);
110    }
111
112    /// Try to get the next event from the buffer without waiting.
113    pub fn try_next(&mut self) -> Option<Event> {
114        self.state.pop_event()
115    }
116
117    /// Check if this input stream has been terminated.
118    pub fn is_terminated(&self) -> bool {
119        self.state.terminated.get() && self.state.len() == 0
120    }
121}
122
123impl Stream for Input {
124    type Item = Event;
125
126    fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
127        if let Some(event) = self.state.pop_event() {
128            Poll::Ready(Some(event))
129        } else if self.state.terminated.get() {
130            Poll::Ready(None)
131        } else {
132            self.state.waker.set(cx.waker().clone());
133            Poll::Pending
134        }
135    }
136
137    fn size_hint(&self) -> (usize, Option<usize>) {
138        (self.state.len(), None)
139    }
140}
141
142impl Default for State {
143    fn default() -> Self {
144        Self {
145            capacity: Cell::new(Self::DEFAULT_CAPACITY),
146            terminated: Cell::new(false),
147            include_redraws: Cell::new(false),
148            events: RefCell::new(VecDeque::new()),
149            waker: Cell::new(Waker::noop().clone()),
150        }
151    }
152}
153
154impl State {
155    /// Default event capacity.
156    pub const DEFAULT_CAPACITY: Option<NonZero<usize>> = Some(NonZero::new(1024).unwrap());
157
158    fn push_event(&self, event: Event) {
159        let mut events = self.events.borrow_mut();
160        while let Some(cap) = self.capacity.get()
161            && events.len() >= cap.get()
162        {
163            let old_event = events.pop_front().unwrap();
164            log::warn!("Event overwritten due to overflow: {old_event:?}");
165        }
166
167        events.push_back(event);
168        drop(events);
169        self.waker.replace(Waker::noop().clone()).wake();
170    }
171
172    fn pop_event(&self) -> Option<Event> {
173        self.events.borrow_mut().pop_front()
174    }
175
176    fn len(&self) -> usize {
177        self.events.borrow().len()
178    }
179}
180
181impl Drop for EventHandler {
182    fn drop(&mut self) {
183        self.terminate();
184    }
185}
186impl futures::stream::FusedStream for Input {
187    fn is_terminated(&self) -> bool {
188        Input::is_terminated(self)
189    }
190}
191
192#[cfg(test)]
193mod tests {
194    use super::*;
195    use std::{
196        sync::{
197            Arc,
198            atomic::{AtomicUsize, Ordering},
199        },
200        task::Wake,
201    };
202    struct Counter(AtomicUsize);
203    impl Wake for Counter {
204        fn wake(self: Arc<Self>) {
205            self.0.fetch_add(1, Ordering::SeqCst);
206        }
207    }
208    #[test]
209    fn termination_and_drop_wake_waiters() {
210        for explicit in [false, true] {
211            let mut handler = EventHandler::default();
212            let mut input = handler.input();
213            let counter = Arc::new(Counter(AtomicUsize::new(0)));
214            let waker = Waker::from(counter.clone());
215            let mut cx = Context::from_waker(&waker);
216            assert!(Pin::new(&mut input).poll_next(&mut cx).is_pending());
217            if explicit {
218                handler.terminate();
219            } else {
220                drop(handler);
221            }
222            assert_eq!(counter.0.load(Ordering::SeqCst), 1);
223            assert!(matches!(
224                Pin::new(&mut input).poll_next(&mut cx),
225                Poll::Ready(None)
226            ));
227        }
228    }
229    #[test]
230    fn overflow_keeps_latest_and_close_drains_buffer() {
231        let mut handler = EventHandler::default();
232        let mut input = handler.input();
233        input.set_capacity(NonZero::new(1));
234        handler.push(Event::Focused(false));
235        handler.push(Event::Focused(true));
236        handler.terminate();
237        assert!(!input.is_terminated());
238        assert_eq!(input.try_next(), Some(Event::Focused(true)));
239        assert!(input.is_terminated());
240        let mut closed = handler.input();
241        handler.push(Event::Focused(false));
242        assert!(closed.is_terminated());
243        assert_eq!(closed.try_next(), None);
244    }
245}
246
247#[cfg(test)]
248mod redraw_tests {
249    use super::*;
250    use futures::{FutureExt, StreamExt};
251    #[test]
252    fn redraw_notifications_are_opt_in_and_preserve_other_streams() {
253        let mut handler = EventHandler::default();
254        let mut ordinary = handler.input();
255        let mut redraws = handler.input();
256        redraws.set_include_redraws(true);
257        handler.push(Event::RedrawRequested);
258        assert_eq!(redraws.try_next(), Some(Event::RedrawRequested));
259        assert!(ordinary.next().now_or_never().is_none());
260        handler.push(Event::Focused(true));
261        assert_eq!(redraws.try_next(), Some(Event::Focused(true)));
262        assert_eq!(ordinary.try_next(), Some(Event::Focused(true)));
263        redraws.set_include_redraws(false);
264        handler.push(Event::RedrawRequested);
265        assert!(redraws.next().now_or_never().is_none());
266    }
267}