Skip to main content

winping/
async_pinger.rs

1// Why a dedicated thread driving APCs, rather than simple event-based async
2// (see the doc on AsyncPinger::new):
3//  1. A future may be polled once and is only checked again after being woken.
4//     Waiting on an event gives no callback with which to wake it.
5//  2. Running the callback on the calling thread only works if the executor uses
6//     wait functions in a particular way, which cannot be relied on.
7//  3. Using events on the worker thread instead of callbacks would cap how many
8//     requests could be waited on at once.
9//
10// State is mutated by both the calling and worker threads, so it lives in an
11// Arc<Mutex>: the Mutex rules out data races, and the Arc means either thread
12// dropping its handle leaves the other's intact.
13
14use core::ffi::c_void;
15use core::mem::replace;
16use core::net::{IpAddr, Ipv4Addr, Ipv6Addr};
17use core::pin::Pin;
18use core::ptr;
19use core::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
20use core::task::{Context, Poll, Waker};
21use std::sync::mpsc::{self, Receiver, SyncSender};
22use std::sync::{Arc, LazyLock, Mutex};
23use std::thread;
24
25use windows_sys::Win32::Foundation::{
26    ERROR_IO_PENDING, GetLastError, HANDLE, WAIT_FAILED, WAIT_IO_COMPLETION, WAIT_OBJECT_0,
27};
28use windows_sys::Win32::NetworkManagement::IpHelper::{
29    IP_BUF_TOO_SMALL, IP_FLAG_DF, IP_OPTION_INFORMATION, IP_SUCCESS, Icmp6CreateFile, Icmp6ParseReplies,
30    Icmp6SendEcho2, IcmpCreateFile, IcmpParseReplies, IcmpSendEcho2, IcmpSendEcho2Ex,
31};
32use windows_sys::Win32::Networking::WinSock::{AF_INET6, SOCKADDR_IN6};
33use windows_sys::Win32::Storage::FileSystem::{DELETE, SYNCHRONIZE};
34use windows_sys::Win32::System::IO::IO_STATUS_BLOCK;
35use windows_sys::Win32::System::Threading::{
36    CreateEventExW, EVENT_MODIFY_STATE, INFINITE, SetEvent, WaitForSingleObjectEx,
37};
38
39use crate::util::{windows_ipv4, windows_ipv6};
40use crate::{Buffer, Error, IpPair};
41
42/// A pinger that does not block when sending.
43#[derive(Clone)]
44pub struct AsyncPinger {
45    worker: Worker,
46    ttl: u8,
47    df: bool,
48    timeout: u32,
49}
50
51/// The result of an async ping, together with the buffer that was passed in.
52#[must_use]
53pub struct AsyncResult {
54    /// The round trip time in milliseconds, or why the request failed.
55    pub result: Result<u32, Error>,
56    /// The buffer that was passed into the pinger, returned for reuse.
57    pub buffer: Buffer,
58}
59
60/// The immediate return value of an AsyncPinger. You should probably just use
61/// async/await syntax instead.
62pub struct PingFuture {
63    state: Arc<Mutex<State>>,
64    kind: IpKind,
65}
66
67const _: () = {
68    const fn assert_send_unpin<T: Send + Unpin>() {}
69    assert_send_unpin::<PingFuture>();
70};
71
72enum State {
73    Unpolled(Buffer),
74    Polled(Buffer, Waker),
75    Ready(Buffer),
76    Failed(Buffer, u32),
77    FailedAsyncSend(Buffer, u32),
78    Invalid,
79}
80
81// Expected State Transitions
82// Initial state: Unpolled
83// Unpolled -> FailedAsyncSend if IcmpSend* returns unexpected value
84// Unpolled -> Failed if IcmpSend* returns error (other than IO_PENDING)
85// Unpolled -> Ready if not yet polled and callback_fn completes
86// Polled -> Ready if already polled and callback_fn completes
87impl AsyncPinger {
88    /// Creates a new AsyncPinger.
89    /// Creating one or more AsyncPingers will spawn
90    /// a single dedicated thread which handles all async IO for all AsyncPingers.
91    /// If ICMP handle initialization fails, all ping requests will return
92    /// an error.
93    ///
94    /// # Panics
95    ///
96    /// This may panic if the compile-time environment variable `WINPING_ASYNC_BUFFER_SIZE`
97    /// is set but cannot be parsed to a valid [`usize`]
98    #[expect(
99        clippy::new_without_default,
100        reason = "new() starts a worker thread, so Default would be misleading"
101    )]
102    pub fn new() -> Self {
103        Self {
104            worker: Worker::new(),
105            ttl: 255,
106            df: false,
107            timeout: 2000,
108        }
109    }
110
111    /// Sets the IP TTL for future requets.
112    pub fn set_ttl(&mut self, ttl: u8) {
113        self.ttl = ttl
114    }
115
116    /// Gets the current IP TTL value.
117    pub fn ttl(&self) -> u8 {
118        self.ttl
119    }
120
121    /// Sets the IP Don't Fragment bit for future requests.
122    pub fn set_df(&mut self, df: bool) {
123        self.df = df;
124    }
125
126    /// Gets the current IP Don't Fragment bit.
127    pub fn df(&self) -> bool {
128        self.df
129    }
130
131    /// Sets the timeout, in milliseconds, for future requests.
132    pub fn set_timeout(&mut self, timeout: u32) {
133        self.timeout = timeout;
134    }
135
136    /// Gets the current timeout in milliseconds.
137    pub fn timeout(&self) -> u32 {
138        self.timeout
139    }
140
141    /// Send an ICMPv4 request to the destination address. On success, returns the round trip time in milliseconds.
142    pub fn send4(&self, dst: Ipv4Addr, mut buf: Buffer) -> PingFuture {
143        buf.init_for_send();
144        self.worker.begin_v4(None, dst, buf, self.ttl, self.timeout, self.df)
145    }
146
147    /// Sends an ICMPv4 request from the source address to the destination address. On success, returns the round trip time in milliseconds.
148    pub fn send4_from(&self, src: Ipv4Addr, dst: Ipv4Addr, mut buf: Buffer) -> PingFuture {
149        buf.init_for_send();
150        self.worker
151            .begin_v4(Some(src), dst, buf, self.ttl, self.timeout, self.df)
152    }
153
154    /// Sends an ICMPv6 request to the destination address. On success, returns the round trip time in milliseconds.
155    pub fn send6(&self, dst: Ipv6Addr, mut buf: Buffer) -> PingFuture {
156        buf.init_for_send();
157        self.worker.begin_v6(None, dst, buf, self.ttl, self.timeout, self.df)
158    }
159
160    /// Sends an ICMPv6 request from the source address to the destination address. On success, returns the round trip time in milliseconds.
161    pub fn send6_from(&self, src: Ipv6Addr, dst: Ipv6Addr, mut buf: Buffer) -> PingFuture {
162        buf.init_for_send();
163        self.worker
164            .begin_v6(Some(src), dst, buf, self.ttl, self.timeout, self.df)
165    }
166
167    /// Sends an ICMP request to the destination address. Supports both v4 and v6. On success, returns the round trip time in milliseconds.
168    pub fn send(&self, dst: IpAddr, buf: Buffer) -> PingFuture {
169        match dst {
170            IpAddr::V4(dst) => self.send4(dst, buf),
171            IpAddr::V6(dst) => self.send6(dst, buf),
172        }
173    }
174
175    /// Sends an ICMP request from the source address to the destination address. Supports both v4 and v6. On success, returns the round trip time in milliseconds.
176    pub fn send_from(&self, src_dst_pair: IpPair, buf: Buffer) -> PingFuture {
177        match src_dst_pair {
178            IpPair::V4 { src, dst } => self.send4_from(src, dst, buf),
179            IpPair::V6 { src, dst } => self.send6_from(src, dst, buf),
180        }
181    }
182}
183
184#[derive(Copy, Clone)]
185enum IpOptionalPair {
186    V4 { src: Option<Ipv4Addr>, dst: Ipv4Addr },
187    V6 { src: Option<Ipv6Addr>, dst: Ipv6Addr },
188}
189
190#[derive(Copy, Clone, Eq, PartialEq, Debug)]
191enum IpKind {
192    V4,
193    V6,
194}
195
196#[derive(Clone)]
197struct Worker {
198    inner: SyncSender<Job>,
199}
200
201struct Job {
202    pair: IpOptionalPair,
203    data_ptr: *mut c_void,
204    data_len: u16,
205    reply_ptr: *mut c_void,
206    reply_len: u32,
207    ttl: u8,
208    timeout: u32,
209    df: bool,
210    cx: Arc<Mutex<State>>,
211}
212
213// SAFETY: the raw pointers in Job address the request and reply buffers owned
214// by the Buffer inside cx, which is kept alive by the Arc for as long as the
215// request is in flight. Ownership moves to the worker thread with the Job, so
216// only one thread accesses them at a time.
217unsafe impl Send for Job {}
218
219impl Worker {
220    fn new() -> Self {
221        Self {
222            inner: ASYNC.tx.clone(),
223        }
224    }
225
226    fn begin_v4(
227        &self,
228        src: Option<Ipv4Addr>,
229        dst: Ipv4Addr,
230        mut buf: Buffer,
231        ttl: u8,
232        timeout: u32,
233        df: bool,
234    ) -> PingFuture {
235        let data_ptr = buf.request_data_ptr();
236        let data_len = buf.request_data_len();
237        let reply_ptr = buf.reply_data_ptr();
238        let reply_len = buf.reply_data_len();
239        let state = Arc::new(Mutex::new(State::Unpolled(buf)));
240        let cx = Arc::clone(&state);
241        let job = Job {
242            pair: IpOptionalPair::V4 { src, dst },
243            data_ptr,
244            data_len,
245            reply_ptr,
246            reply_len,
247            ttl,
248            timeout,
249            df,
250            cx,
251        };
252        self.inner
253            .send(job)
254            .expect("the async worker thread never drops the receiver");
255        // SAFETY: input_event is a live event handle created with EVENT_MODIFY_STATE.
256        unsafe { SetEvent(ASYNC.handles.input_event) };
257        PingFuture {
258            state,
259            kind: IpKind::V4,
260        }
261    }
262
263    fn begin_v6(
264        &self,
265        src: Option<Ipv6Addr>,
266        dst: Ipv6Addr,
267        mut buf: Buffer,
268        ttl: u8,
269        timeout: u32,
270        df: bool,
271    ) -> PingFuture {
272        let data_ptr = buf.request_data_ptr();
273        let data_len = buf.request_data_len();
274        let reply_ptr = buf.reply_data_ptr();
275        let reply_len = buf.reply_data_len();
276        let state = Arc::new(Mutex::new(State::Unpolled(buf)));
277        let cx = Arc::clone(&state);
278        let job = Job {
279            pair: IpOptionalPair::V6 { src, dst },
280            data_ptr,
281            data_len,
282            reply_ptr,
283            reply_len,
284            ttl,
285            timeout,
286            df,
287            cx,
288        };
289        self.inner
290            .send(job)
291            .expect("the async worker thread never drops the receiver");
292        // SAFETY: input_event is a live event handle created with EVENT_MODIFY_STATE.
293        unsafe { SetEvent(ASYNC.handles.input_event) };
294        PingFuture {
295            state,
296            kind: IpKind::V6,
297        }
298    }
299}
300
301/// The handles shared by every AsyncPinger, created once when the async worker
302/// thread is started and only ever read afterwards.
303#[derive(Copy, Clone)]
304struct Handles {
305    input_event: HANDLE,
306    icmp: HANDLE,
307    icmp6: HANDLE,
308}
309// Safety: ICMP file handles and event handles are not thread-affine; Windows
310// allows them to be used from any thread. These are never mutated after
311// creation, so sharing them across the calling and worker threads is sound.
312// SAFETY: ICMP and event handles are not thread-affine, and these are written
313// once during LazyLock initialization and only read afterwards.
314unsafe impl Send for Handles {}
315// SAFETY: see the comment on the Send impl above.
316unsafe impl Sync for Handles {}
317
318struct AsyncGlobals {
319    handles: Handles,
320    tx: SyncSender<Job>,
321}
322
323static ASYNC_BUFFER_SIZE_CT: Option<&'static str> = std::option_env!("WINPING_ASYNC_BUFFER_SIZE");
324static ASYNC_BUFFER_SIZE_RT_IS_SET: AtomicBool = AtomicBool::new(false);
325static ASYNC_BUFFER_SIZE_RT: AtomicUsize = AtomicUsize::new(0);
326static ASYNC_BUFFER_SIZE_DEFAULT: usize = 1024;
327
328/// Sets the size of the channel used to send ping requests to the async IO
329/// thread described in [`AsyncPinger::new`].
330///
331/// Must be called before the first AsyncPinger is created, and takes precedence
332/// over the `WINPING_ASYNC_BUFFER_SIZE` compile-time environment variable. If
333/// neither is set, the size is 1024.
334///
335/// If that environment variable is set but cannot be parsed, creating the first
336/// AsyncPinger panics.
337pub fn set_async_buffer_size(size: usize) {
338    ASYNC_BUFFER_SIZE_RT.store(size, Ordering::SeqCst);
339    ASYNC_BUFFER_SIZE_RT_IS_SET.store(true, Ordering::SeqCst);
340}
341
342static ASYNC: LazyLock<AsyncGlobals> = LazyLock::new(|| {
343    let channel_size = if ASYNC_BUFFER_SIZE_RT_IS_SET.load(Ordering::Relaxed) {
344        ASYNC_BUFFER_SIZE_RT.load(Ordering::Relaxed)
345    } else {
346        ASYNC_BUFFER_SIZE_CT.map_or(ASYNC_BUFFER_SIZE_DEFAULT, |s| {
347            s.parse()
348                .expect("Failed to parse value of WINPING_ASYNC_BUFFER_SIZE compile-time environment variable")
349        })
350    };
351    let (tx, rx) = mpsc::sync_channel(channel_size);
352    const EVENT_ACCESS: u32 = DELETE | EVENT_MODIFY_STATE | SYNCHRONIZE;
353    // SAFETY: null attributes and name are valid (unnamed event with default
354    // security); the flags/access values are constants accepted by the API.
355    let input_event = unsafe { CreateEventExW(ptr::null(), ptr::null(), 0, EVENT_ACCESS) };
356    assert!(!input_event.is_null(), "could not initialize event handle");
357    // Ignore failures for ICMP handles - instead, allow IcmpSendEcho (and similar) to error on use
358    // SAFETY: IcmpCreateFile has no preconditions.
359    let icmp = unsafe { IcmpCreateFile() };
360    // SAFETY: Icmp6CreateFile has no preconditions.
361    let icmp6 = unsafe { Icmp6CreateFile() };
362    let handles = Handles {
363        input_event,
364        icmp,
365        icmp6,
366    };
367
368    thread::spawn(move || {
369        loop {
370            // WaitForSingleObjectEx returns if input_event is signaled, or if callback_fn is called
371            // SAFETY: input_event is a live event handle owned by this thread's
372            // captured Handles, and SYNCHRONIZE access was requested for it.
373            let wait = unsafe { WaitForSingleObjectEx(handles.input_event, INFINITE, 1) };
374            match wait {
375                WAIT_IO_COMPLETION | WAIT_OBJECT_0 => while try_recv_job(&rx, &handles) {},
376                WAIT_FAILED => {
377                    let err = Error::from_lasterror();
378                    unreachable!("AsyncPinger thread failed to wait in event loop: {}", err)
379                }
380                x => unreachable!("unexpected return from WaitForSingleObjectEx: {:x}", x),
381            }
382        }
383    });
384
385    AsyncGlobals { handles, tx }
386});
387
388#[inline]
389fn try_recv_job(rx: &Receiver<Job>, handles: &Handles) -> bool {
390    let job = match rx.try_recv() {
391        Ok(job) => job,
392        _ => return false,
393    };
394    // IP_OPTION_INFORMATION::Flags is a u8, but windows-sys types IP_FLAG_DF as u32.
395    #[expect(
396        clippy::as_conversions,
397        clippy::cast_possible_truncation,
398        reason = "IP_FLAG_DF is the constant 2"
399    )]
400    const DONT_FRAGMENT: u8 = IP_FLAG_DF as u8;
401    let ip_opts = IP_OPTION_INFORMATION {
402        Ttl: job.ttl,
403        Flags: if job.df { DONT_FRAGMENT } else { 0 },
404        ..Default::default()
405    };
406    let arcptr = Arc::into_raw(job.cx);
407
408    #[inline]
409    fn after_send(ret: u32, arcptr: *const Mutex<State>) {
410        // Only one branch may reclaim the leaked Arc, so the ret != 0 path
411        // returns rather than falling through into the GetLastError check.
412        if ret != 0 {
413            // SAFETY: arcptr came from Arc::into_raw, and only one path reclaims it.
414            let arc = unsafe { Arc::from_raw(arcptr) };
415            let mut lock = arc.lock().expect("state mutex poisoned");
416            let state = replace(&mut *lock, State::Invalid);
417            match state {
418                State::Unpolled(buf) => *lock = State::FailedAsyncSend(buf, ret),
419                State::Polled(buf, waker) => {
420                    *lock = State::FailedAsyncSend(buf, ret);
421                    waker.wake();
422                }
423                _ => {} // Leave state as Invalid, pushes panic out of async thread
424            }
425            return;
426        }
427        // SAFETY: GetLastError has no preconditions and no out-parameters.
428        let err = unsafe { GetLastError() };
429        if err != ERROR_IO_PENDING {
430            // SAFETY: arcptr came from Arc::into_raw, and only one path reclaims it.
431            let arc = unsafe { Arc::from_raw(arcptr) };
432            let mut lock = arc.lock().expect("state mutex poisoned");
433            let state = replace(&mut *lock, State::Invalid);
434            match state {
435                State::Unpolled(buf) => *lock = State::Failed(buf, err),
436                State::Polled(buf, waker) => {
437                    *lock = State::Failed(buf, err);
438                    waker.wake();
439                }
440                _ => {} // Leave state as Invalid, pushes panic out of async thread
441            }
442        }
443    }
444
445    use IpOptionalPair::{V4, V6};
446    match job.pair {
447        V4 { src: Some(src), dst } => {
448            // SAFETY: the buffers behind arcptr stay alive until the APC runs, and
449            // Icmp*SendEcho2* copies ip_opts before returning.
450            let ret = unsafe {
451                IcmpSendEcho2Ex(
452                    handles.icmp,
453                    ptr::null_mut(),   // Event
454                    Some(callback_fn), // ApcRoutine
455                    arcptr.cast(),     // ApcContext
456                    windows_ipv4(src),
457                    windows_ipv4(dst),
458                    job.data_ptr,
459                    job.data_len,
460                    &ip_opts,
461                    job.reply_ptr,
462                    job.reply_len,
463                    job.timeout,
464                )
465            };
466            after_send(ret, arcptr);
467        }
468        V4 { src: None, dst } => {
469            // SAFETY: the buffers behind arcptr stay alive until the APC runs, and
470            // Icmp*SendEcho2* copies ip_opts before returning.
471            let ret = unsafe {
472                IcmpSendEcho2(
473                    handles.icmp,
474                    ptr::null_mut(),   // Event
475                    Some(callback_fn), // ApcRoutine
476                    arcptr.cast(),     // ApcContext
477                    windows_ipv4(dst),
478                    job.data_ptr,
479                    job.data_len,
480                    &ip_opts,
481                    job.reply_ptr,
482                    job.reply_len,
483                    job.timeout,
484                )
485            };
486            after_send(ret, arcptr);
487        }
488        V6 { src, dst } => {
489            let src = SOCKADDR_IN6 {
490                sin6_family: AF_INET6,
491                sin6_addr: windows_ipv6(src.unwrap_or(Ipv6Addr::UNSPECIFIED)),
492                ..Default::default()
493            };
494            let dst = SOCKADDR_IN6 {
495                sin6_family: AF_INET6,
496                sin6_addr: windows_ipv6(dst),
497                ..Default::default()
498            };
499            // SAFETY: the buffers behind arcptr stay alive until the APC runs, and
500            // Icmp*SendEcho2* copies ip_opts before returning.
501            let ret = unsafe {
502                Icmp6SendEcho2(
503                    handles.icmp6,
504                    ptr::null_mut(),   // Event
505                    Some(callback_fn), // ApcRoutine
506                    arcptr.cast(),     // ApcContext
507                    &src,
508                    &dst,
509                    job.data_ptr,
510                    job.data_len,
511                    &ip_opts,
512                    job.reply_ptr,
513                    job.reply_len,
514                    job.timeout,
515                )
516            };
517            after_send(ret, arcptr);
518        }
519    }
520    true
521}
522
523/// Matches [`windows_sys::Win32::System::IO::PIO_APC_ROUTINE`]. `apccontext` is
524/// the pointer leaked by `Arc::into_raw` in `try_recv_job`, and this reclaims it.
525unsafe extern "system" fn callback_fn(apccontext: *mut c_void, _io_status_block: *mut IO_STATUS_BLOCK, _rsvd: u32) {
526    // SAFETY: apccontext is this request's Arc::into_raw pointer, and the APC
527    // fires at most once, so the leaked strong count is reclaimed exactly once.
528    let state_arc = unsafe { Arc::from_raw(apccontext.cast::<Mutex<State>>()) };
529    let mut lock = state_arc.lock().expect("state mutex poisoned");
530    let state = replace(&mut *lock, State::Invalid);
531    match state {
532        State::Unpolled(buf) => *lock = State::Ready(buf),
533        State::Polled(buf, waker) => {
534            *lock = State::Ready(buf);
535            waker.wake();
536        }
537        _ => {} // Leave state as Invalid, pushes panic out of async thread
538    }
539}
540
541impl Future for PingFuture {
542    type Output = AsyncResult;
543    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
544        let mut lock = self.state.lock().expect("state mutex poisoned");
545        let state = replace(&mut *lock, State::Invalid);
546        match state {
547            State::Unpolled(buf) | State::Polled(buf, _) => {
548                *lock = State::Polled(buf, cx.waker().clone());
549                Poll::Pending
550            }
551            State::Ready(mut buf) => {
552                drop(lock);
553                let ret = match self.kind {
554                    // SAFETY: the reply buffer is live and reply_data_len describes it.
555                    IpKind::V4 => unsafe { IcmpParseReplies(buf.reply_data_ptr(), buf.reply_data_len()) },
556                    // SAFETY: as above, for the v6 parser.
557                    IpKind::V6 => unsafe { Icmp6ParseReplies(buf.reply_data_ptr(), buf.reply_data_len()) },
558                };
559                let result = if ret == 0 {
560                    Err(Error::from_lasterror())
561                } else {
562                    // init_for_send always sizes for a full reply, so None is unreachable.
563                    let parsed = match self.kind {
564                        IpKind::V4 => {
565                            #[cfg(target_pointer_width = "32")]
566                            let reply = buf.as_echo_reply();
567                            #[cfg(target_pointer_width = "64")]
568                            let reply = buf.as_echo_reply32();
569
570                            let parsed = reply.map(|reply| (reply.Status, reply.RoundTripTime));
571                            if parsed.is_some() {
572                                buf.set_filled4();
573                            }
574                            parsed
575                        }
576                        IpKind::V6 => {
577                            let parsed = buf.as_echo_reply6().map(|reply| (reply.Status, reply.RoundTripTime));
578                            if parsed.is_some() {
579                                buf.set_filled6();
580                            }
581                            parsed
582                        }
583                    };
584                    match parsed {
585                        Some((IP_SUCCESS, rtt)) => Ok(rtt),
586                        Some((status, _)) => Err(Error::from_iperror(status)),
587                        None => Err(Error::from_iperror(IP_BUF_TOO_SMALL)),
588                    }
589                };
590                Poll::Ready(AsyncResult { result, buffer: buf })
591            }
592            State::Failed(buf, err) => {
593                drop(lock);
594                Poll::Ready(AsyncResult {
595                    result: Err(Error::from_winerror(err)),
596                    buffer: buf,
597                })
598            }
599            State::FailedAsyncSend(_buf, err) => {
600                unreachable!("Failed to send async. Expected return of 0, got {} instead.", err)
601            }
602            State::Invalid => unreachable!(),
603        }
604    }
605}