Fix FileSystemWatcher startup race on Linux

[lewing]

Summary

Fix a race condition in FileSystemWatcher on Linux where events can be missed if they occur immediately after Start() returns, before the ProcessEvents background thread enters its read() loop.

Root Cause

PR #117148 refactored the Linux FileSystemWatcher to use a single shared inotify instance. The refactor introduced a race in Start(): after StartThread() spawns the background thread and CreateRootWatch() registers the inotify watch, Start() returns without ensuring the processing thread is actually reading events. If a filesystem operation triggers an event in this window, the event is missed.

This manifests as "Created event did not occur as expected" failures in SymbolicLink_Changed_Tests tests, particularly under jitstress on slower hardware (arm32) where the race window is wider.

Fix

Add a ManualResetEventSlim that:

1. ProcessEvents() signals just before entering its TryReadEvent loop
2. Start() waits on after releasing the watchers lock

For shared inotify instances (when a subsequent watcher reuses an already-running instance), the event is already set so WaitForReadReady() returns immediately.

Testing

The fix should resolve:

• SymbolicLink_Changed_Tests.FileSystemWatcher_SymbolicLink_TargetsDirectory_Create (currently failing on linux arm32 jitstress)
• SymbolicLink_Changed_Tests.FileSystemWatcher_SymbolicLink_TargetsDirectory_Create_IncludeSubdirectories (currently disabled via Disable FileSystemWatcher_SymbolicLink_TargetsDirectory_Create_IncludeSubdirectories #124849)

Related

• Fixes FileSystemWatcher SymbolicLink tests failing after inotify refactor (#117148) #125737
• Regression from FileSystemWatcher.Linux: use a single inotify instance and refactor watch tracking. #117148
• Related: FileSystemWatcher_SymbolicLink_TargetsDirectory_Create_IncludeSubdirectories failed with missed event #124677, FileSystemWatcher_SymbolicLink_TargetsDirectory_Create_IncludeSubdirectories failing on multiple OSes #124847, System.IO.Tests.Directory_Create_Tests.FileSystemWatcher_Directory_Create_InNestedDirectory fails with "Created event did not occur as expected" #103630 (false pattern match)

/cc @tmds @adamsitnik @jozkee

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-io
See info in area-owners.md if you want to be subscribed.

[Copilot]

Pull request overview

Fixes a Linux FileSystemWatcher startup race by adding a synchronization point so Start() can wait until the inotify processing thread is ready to read events.

Changes:

• Add a ManualResetEventSlim readiness signal in the Linux inotify processing thread and wait for it in Watcher.Start().
• Extend ConvertDllsToWebcil / WASM Browser targets to classify “pass-through” candidates separately and materialize shared framework assets per project.
• Update global.json SDK/tooling versions.

Reviewed changes

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

File	Description
src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.Linux.cs	Adds a read-readiness signal and waits in Start() to avoid missed inotify events.
src/tasks/Microsoft.NET.Sdk.WebAssembly.Pack.Tasks/ConvertDllsToWebCil.cs	Adds a new MSBuild task output (PassThroughCandidates) to classify non-converted inputs.
src/mono/nuget/Microsoft.NET.Sdk.WebAssembly.Pack/build/Microsoft.NET.Sdk.WebAssembly.Browser.targets	Uses PassThroughCandidates to materialize shared framework assets and avoid identity collisions.
global.json	Changes SDK/tools and MSBuild SDK versions (not described in PR summary).

---

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

Fixes a Linux FileSystemWatcher race introduced by the shared-inotify refactor, where Start() could return before the background processing thread is reliably able to consume inotify events, leading to missed/late events in stress environments.

Changes:

• Add a ManualResetEventSlim to synchronize Watcher.Start() with the inotify processing thread’s readiness.
• Signal readiness from ProcessEvents() before entering the TryReadEvent loop and again on exit to ensure waiters are released.
• Block Start() on WaitForReadReady() after releasing the shared watchers lock.

---

You can also share your feedback on Copilot code review. Take the survey.

[tmds]

Start() returns without ensuring the processing thread is actually reading events. If a filesystem operation triggers an event in this window, the event is missed.

When the Start method returns events should be queued up against the inotify and _emitEvents is true.
It doesn't matter that ProcessEvents may not be reading the inotify yet.

#117148 affects the timing of inotify stop/start. I suggest we first increase the timeouts on these tests to have some more certainty that a failed test indicates a functional issue rather than missing an event due to a timeout.

[lewing]

Start() returns without ensuring the processing thread is actually reading events. If a filesystem operation triggers an event in this window, the event is missed.

When the Start method returns events should be queued up against the inotify and _emitEvents is true. It doesn't matter that ProcessEvents may not be reading the inotify yet.

#117148 affects the timing of inotify stop/start. I suggest we first increase the timeouts on these tests to have some more certainty that a failed test indicates a functional issue rather than missing an event due to a timeout.

I'm happy to hand this off, I just looked at all the failures in https://github.com/dotnet/runtime/issue-03630 and decided something wasn't working as designed. If the issue is with the tests then we should fix or disable all of them rather than just letting the KBE be a catch-all

[lewing]

#125744

[tmds]

#125744

Thanks. I'll close this one because I don't think the described race exists.