Guard/listen includes a polling adapter. The README.md says, although it's much slower than other adapters, it works on every platform/system and scenario (including network filesystems such as VM shared folders). But how does it work? Does it scan the filesystem and store mtime values and self-notify if they change? (It's not clear from reading the source.)
(If you answer, it'd also be great to post the info on the Guard wiki.)
It continously scans all the given directories recursively.
The :latency parameter tell it how long to sleep between scans.
The code it quite complex, because polling shares a lot with the OSX adapter.
Here is where the directories are scanned: https://github.com/guard/listen/blob/master/lib/listen/directory.rb
And here is the structure where the modes and mtime are stored: https://github.com/guard/listen/blob/master/lib/listen/record.rb
And here is how parts of the filesystem snapshot are invalidated: https://github.com/guard/listen/blob/master/lib/listen/change.rb#L31
In general, polling will only be slow if there are too many large directories to scan. That's why it's best to only watch selected directories and avoid huge ones with files you don't edit/change, e.g. things like node_modules or vendor. Listen has ignore rules for some directories.
The debug mode (set with environment variable LISTEN_GEM_DEBUGGING=2) can give you insights on what's happening under the hood.
I actually could answer in more detail, except I think the existing architecture is poor.
So I'd rather rewrite it to make it clearer and more maintainable.
See this for a description: https://github.com/guard/listen/issues/381