windows-file-watcher 0.2.3

Memory-safe, queue-mediated Windows path-change watching over ReadDirectoryChangesW, with a coarse fallback.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
// Copyright (c) 2026 Mike Grier
//! The servicing path: a request queue drained by one `ThreadpoolWork`, so every
//! resident-state mutation happens under a single logical authority (D-2).
//!
//! This is the SQ half of the two-queue model. Requests arrive from any number of
//! client threads and are serviced one at a time, in order, on a pool thread the
//! crate never lends to client code.
//!
//! # The doorbell rings on idle -> scheduled, not on empty -> non-empty
//!
//! [`ThreadpoolWork::submit`] *is* the SQ doorbell (D-25) -- on this side of the
//! design the crate is the waiter, so queuing work beats an event and something
//! to wait on it. But each `submit` queues an **independent** invocation and they
//! do not coalesce, so ringing on every enqueue would queue 500 drains to service
//! 500 subscriptions, 499 of which would find the queue already emptied by the
//! first.
//!
//! The obvious fix -- ring only when the queue was empty -- coalesces but does
//! **not** serialise, and serialising is the part D-2 actually needs. A drain that
//! has emptied the queue and is still running its last handler leaves the queue
//! observably empty, so the next enqueue would ring and a second drain would
//! execute concurrently with the first. The condition is therefore whether a drain
//! is *outstanding*, not whether the queue is empty: [`Drain::Scheduled`] is set
//! under the queue lock by whoever rings, and cleared only by a drain that has
//! found nothing left to do. A drain loops until the queue is empty rather than
//! servicing one item per ring, which is what makes the two readings coincide in
//! the steady state.
//!
//! Clearing the flag is deliberately the drain's **last** touch of shared state: a
//! producer may ring the instant it is cleared, so anything done afterwards would
//! be racing the drain that ring starts.
//!
//! # Rundown
//!
//! Teardown closes the queue *before* waiting (the ordering lesson of D-23/D-34):
//! the other order lets a drain accept work after the wait began. Pending requests
//! are discarded rather than serviced, because every watcher they could act on is
//! being torn down in the same breath.

use std::collections::VecDeque;
use std::io;
use std::sync::{Arc, Condvar, Mutex};

use windows_threadpool_sys::work::ThreadpoolWork;

/// Whether a drain is outstanding.
///
/// This is the doorbell's edge, and it is not the same question as "is the queue
/// empty" -- see the module docs.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum Drain {
    /// No drain is queued or running, so the next enqueue must ring.
    Idle,
    /// A drain is queued or running. It will pick up anything enqueued now, so
    /// ringing again would only queue a drain that finds nothing to do.
    Scheduled,
}

/// A request that could not be accepted, handed back to its submitter.
///
/// The only rejection is a shut-down monitor. Returning the request rather than
/// dropping it is what lets M3.6 report the outcome as a completion (D-30)
/// instead of leaving a client waiting for something that will never happen.
#[derive(Debug)]
pub struct Rejected<T>(pub(crate) T);

/// The queue and the state that governs who drains it.
struct Queue<T> {
    items: VecDeque<T>,
    drain: Drain,
    /// Set by shutdown. One reason only: unlike the watcher's arm gate (D-34),
    /// nothing else ever stops the servicing path, because D-33's reservation
    /// means request draining is never throttled for backpressure.
    closed: bool,
    /// How many times the doorbell has been rung, so coalescing is measurable
    /// rather than merely asserted.
    rings: u64,
    /// How many requests shutdown discarded.
    discarded: u64,
    /// Producers that have decided to ring but have not yet published.
    ///
    /// `submit` releases the lock before calling `ThreadpoolWork::submit`, so
    /// between those two points a producer is committed to publishing and is
    /// invisible to anyone holding the lock. Without this count, `shut_down`
    /// could take the lock, close the queue, and run its cancellation entirely
    /// inside that window -- and the producer would then publish afterwards,
    /// making a callback start after `shut_down` had returned and promised
    /// that none could.
    ///
    /// Raised under the lock by the producer that decided to ring, and lowered
    /// once the publication has actually happened.
    publishing: usize,
}

struct Shared<T> {
    queue: Mutex<Queue<T>>,
    /// Signalled when `publishing` reaches zero, for `shut_down` to wait on.
    published: Condvar,
    /// Stops one producer between the queue decision and the publication.
    ///
    /// Per-servicer rather than a global, because the suite runs tests in
    /// parallel threads: a single static gate is armed by one test and then
    /// consumed by whichever producer reaches it first, anywhere in the
    /// process. That makes the test pass in isolation and fail in the suite,
    /// which is how it was found.
    #[cfg(test)]
    pause_before_publish: PauseBeforePublish,
}

/// A gate that parks one producer between the queue decision and the
/// publication, so a test can drive that interleaving instead of hoping for it.
///
/// The window is a few instructions wide and cannot be reached by timing.
#[cfg(test)]
#[derive(Default)]
pub(crate) struct PauseBeforePublish {
    armed: std::sync::atomic::AtomicBool,
    /// `(parked, released)`.
    state: Mutex<(bool, bool)>,
    changed: Condvar,
}

#[cfg(test)]
impl PauseBeforePublish {
    /// Park the next producer of *this* servicer that reaches the publication.
    pub(crate) fn arm(&self) {
        *self.state.lock().unwrap_or_else(|p| p.into_inner()) = (false, false);
        self.armed.store(true, std::sync::atomic::Ordering::SeqCst);
    }

    /// Called from `submit`; disarms itself, so only one producer is held.
    fn wait(&self) {
        if !self.armed.swap(false, std::sync::atomic::Ordering::SeqCst) {
            return;
        }
        let mut state = self.state.lock().unwrap_or_else(|p| p.into_inner());
        state.0 = true;
        self.changed.notify_all();
        while !state.1 {
            state = self.changed.wait(state).unwrap_or_else(|p| p.into_inner());
        }
    }

    /// Block until a producer is parked at the publication point.
    pub(crate) fn await_parked(&self) {
        let mut state = self.state.lock().unwrap_or_else(|p| p.into_inner());
        while !state.0 {
            state = self.changed.wait(state).unwrap_or_else(|p| p.into_inner());
        }
    }

    /// Let the parked producer publish.
    pub(crate) fn release(&self) {
        self.state.lock().unwrap_or_else(|p| p.into_inner()).1 = true;
        self.changed.notify_all();
    }
}

/// A request queue with exactly one servicing authority.
///
/// Generic over the request type so the mechanism can be tested on its own terms:
/// what it guarantees -- order, single-servicer, coalesced wakes, bounded rundown
/// -- is a property of the machinery, not of what flows through it.
pub(crate) struct Servicer<T: Send + 'static> {
    shared: Arc<Shared<T>>,
    work: ThreadpoolWork,
}

impl<T: Send + 'static> Servicer<T> {
    /// Build a servicing path that applies `handle` to each request in turn.
    ///
    /// `handle` runs on a pool thread, one call at a time, in submission order.
    /// Since M18 removed panic containment from the thread pool, a handler that
    /// unwinds aborts the process; it is crate-internal code, so that is a bug to
    /// fix rather than a condition to tolerate.
    ///
    /// # Errors
    ///
    /// Returns the error from `CreateThreadpoolWork`.
    pub(crate) fn new<H>(handle: H) -> io::Result<Self>
    where
        H: Fn(T) + Send + Sync + 'static,
    {
        let shared = Arc::new(Shared {
            queue: Mutex::new(Queue {
                items: VecDeque::new(),
                drain: Drain::Idle,
                closed: false,
                rings: 0,
                discarded: 0,
                publishing: 0,
            }),
            published: Condvar::new(),
            #[cfg(test)]
            pause_before_publish: PauseBeforePublish::default(),
        });

        // The callback holds a strong reference, not a `Weak`: unlike the
        // watcher's completion callback it is not reached *through* the object it
        // would point back at, so there is no cycle -- the work object owns the
        // closure, the closure owns the queue, and nothing owns the work object
        // but the `Servicer`.
        let queue = Arc::clone(&shared);
        let work = ThreadpoolWork::new(move || drain(&queue, &handle), None)?;

        Ok(Self { shared, work })
    }

    /// Enqueue a request, ringing the doorbell only if no drain is outstanding.
    ///
    /// Never blocks on servicing: the lock is held for the enqueue alone, and the
    /// ring happens outside it.
    ///
    /// # Errors
    ///
    /// Returns the request unserviced if the servicing path has shut down.
    pub(crate) fn submit(&self, item: T) -> Result<(), Rejected<T>> {
        let ring = {
            let mut queue = lock(&self.shared.queue);
            if queue.closed {
                return Err(Rejected(item));
            }
            queue.items.push_back(item);
            let ring = queue.drain == Drain::Idle;
            if ring {
                queue.drain = Drain::Scheduled;
                queue.rings += 1;
                // Counted while still holding the lock, so a `shut_down` that
                // takes it next cannot miss this publication.
                queue.publishing += 1;
            }
            ring
        };

        if ring {
            // The window this type's shutdown ordering is about: the lock is
            // released and the publication has not happened. A test needs to
            // stop here to drive that interleaving, because it is far too
            // narrow to hit by timing.
            #[cfg(test)]
            self.shared.pause_before_publish.wait();
            self.work.submit();
            let mut queue = lock(&self.shared.queue);
            queue.publishing -= 1;
            if queue.publishing == 0 {
                self.shared.published.notify_all();
            }
        }
        Ok(())
    }

    /// Refuse further requests, discard those pending, and wait for the drain.
    ///
    /// Idempotent, so a caller may shut down explicitly and still let `Drop` run
    /// (the teardown shape of D-34). After it returns, no handler is executing or
    /// can start.
    ///
    /// **That holds against a producer mid-`submit`, which took a second piece
    /// of ordering to achieve.** Closing the queue only stops producers that
    /// have not yet reached the gate; one that passed it and has not yet called
    /// `ThreadpoolWork::submit` holds no lock and cannot be seen from here. The
    /// `publishing` count makes that producer visible and this function waits
    /// for it, so the cancellation below cannot run entirely inside its window.
    ///
    /// Must not be called from inside a handler: it waits for that handler to
    /// finish, so it would wait on itself.
    pub(crate) fn shut_down(&self) {
        {
            let mut queue = lock(&self.shared.queue);
            queue.closed = true;
            queue.discarded += queue.items.len() as u64;
            queue.items.clear();
            // Closing the queue stops producers that have not reached the gate.
            // It does nothing about one that passed it and has not yet reached
            // `ThreadpoolWork::submit`, because that producer holds no lock and
            // is invisible here -- so without this wait the cancellation below
            // could run entirely inside its window and the publication would
            // land afterwards. Waiting costs nothing in the ordinary case, where
            // the count is already zero.
            //
            // Not a deadlock against the drain callback: `wait` releases the
            // lock, and a publisher's remaining work is a `SubmitThreadpoolWork`
            // that takes no lock of ours.
            while queue.publishing > 0 {
                queue = self
                    .shared
                    .published
                    .wait(queue)
                    .unwrap_or_else(|poison| poison.into_inner());
            }
        }

        // This is what actually delivers the "wait for the drain" guarantee
        // documented above, not merely an optimisation: `cancel_pending` maps to
        // `WaitForThreadpoolWorkCallbacks(handle, TRUE)`, which *always* blocks
        // until any currently-executing invocation of this `Servicer`'s single
        // `ThreadpoolWork` returns, and only additionally (`TRUE`) cancels one
        // that has not started yet rather than letting it run to discover the
        // queue empty. So by the time this call returns, no drain of this
        // servicer is executing or can start -- which is exactly why
        // `Monitor::shut_down` can safely walk the watcher table immediately
        // afterward (D-23/D-34): nothing can still be adopting one.
        self.work.cancel_pending();
    }

    /// Whether the servicing path is still accepting requests.
    pub(crate) fn is_open(&self) -> bool {
        !lock(&self.shared.queue).closed
    }

    /// Block until every request submitted so far has been serviced.
    ///
    /// A drain services the queue to empty before it returns, so waiting for the
    /// outstanding drains is the same as waiting for the outstanding requests.
    ///
    /// Must not be called from inside a handler, which would be waiting on
    /// itself.
    pub(crate) fn quiesce(&self) {
        self.work.wait();
    }

    /// How many requests are waiting to be serviced. Test-only: production code
    /// has no reason to inspect the queue depth directly.
    #[cfg(test)]
    pub(crate) fn pending(&self) -> usize {
        lock(&self.shared.queue).items.len()
    }

    /// How many times the doorbell has been rung.
    ///
    /// The measure of coalescing: this is the number of drains queued, which
    /// should stay far below the number of requests submitted. Test-only.
    #[cfg(test)]
    pub(crate) fn rings(&self) -> u64 {
        lock(&self.shared.queue).rings
    }

    /// The gate that parks a producer before it publishes. Test-only.
    #[cfg(test)]
    pub(crate) fn pause_gate(&self) -> &PauseBeforePublish {
        &self.shared.pause_before_publish
    }

    /// How many requests shutdown discarded unserviced. Test-only.
    #[cfg(test)]
    pub(crate) fn discarded(&self) -> u64 {
        lock(&self.shared.queue).discarded
    }
}

impl<T: Send + 'static> Drop for Servicer<T> {
    fn drop(&mut self) {
        // One teardown implementation with two triggers; `shut_down` is
        // idempotent, so an explicit call beforehand costs nothing.
        //
        // No drain is needed after it, and one used to be here. `shut_down`
        // ends with `ThreadpoolWork::cancel_pending`, which returns only once
        // nothing is queued and nothing is executing -- and which now settles
        // the drain obligation for exactly that reason, so the doorbell owes
        // nothing by the time this returns. The second `stop_and_drain` added
        // with the draining teardown was justified by an obligation that is no
        // longer left behind; it bought a second native pool synchronisation on
        // every drop and nothing else. Measured rather than assumed: with
        // `cancel_pending`'s settle removed, this crate's suite panics on the
        // obligation across many tests under `fail-fast`; with it, the suite is
        // green without any drain here.
        self.shut_down();
    }
}

impl<T: Send + 'static> std::fmt::Debug for Servicer<T> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let queue = lock(&self.shared.queue);
        f.debug_struct("Servicer")
            .field("pending", &queue.items.len())
            .field("drain", &queue.drain)
            .field("closed", &queue.closed)
            .field("rings", &queue.rings)
            .finish_non_exhaustive()
    }
}

/// Service requests until none are left.
///
/// Draining to empty rather than one-per-ring is what makes the doorbell's
/// idle/scheduled edge coincide with the queue's empty/non-empty edge in the
/// steady state, and it is why 500 submissions do not need 500 rings.
fn drain<T, H>(shared: &Shared<T>, handle: &H)
where
    H: Fn(T),
{
    loop {
        let next = {
            let mut queue = lock(&shared.queue);
            match queue.items.pop_front() {
                Some(item) => item,
                None => {
                    // Deliberately the last touch of shared state in this
                    // callback: a producer may ring the instant this is cleared,
                    // and the drain that ring starts must not overlap this one.
                    queue.drain = Drain::Idle;
                    return;
                }
            }
        };

        // Outside the lock: servicing a request can be slow (opening a directory,
        // arming a read), and producers must not queue behind it.
        handle(next);
    }
}

/// Lock, recovering the guard if a previous holder panicked.
///
/// Panic containment was removed from the thread pool in M18, so a handler that
/// unwinds aborts rather than poisoning this lock; recovery here covers only a
/// panic on a client thread inside `submit`, which leaves the queue structurally
/// intact.
fn lock<T>(mutex: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
    mutex.lock().unwrap_or_else(|poison| poison.into_inner())
}

#[cfg(test)]
mod tests;