add latency support (& remarks in the README)

Author: DivineDominion

Example/AppDelegate.swift

@@ -32,7 +32,7 @@ class AppDelegate: NSObject, NSApplicationDelegate {
 
         report(url)
 
-        FolderContentMonitor(url: url)
+        FolderContentMonitor(url: url, latency: 0)
             .asObservable()
 
             // Ignore Finder folder settings

README.md

@@ -67,6 +67,75 @@ let changedFile = FolderContentMonitor(url: folderUrl)
     })
 ```
 
+## A Note on Latency
+
+A latency of 0.0 (default value) can produce too much noise. Experiment with slightly higher values so the system can coalesce events when appropriate.
+
+When you run the example app to see which kinds of events are fired, make sure to use TextEdit to create and modify a file so you see what kinds of events are bound to happen. Here's an annotated log:
+
+```
+// Create file in folder
+
+texteditfile.txt changed (isFile, renamed, xattrsModified)
+texteditfile.txt changed (isFile, renamed, finderInfoModified, xattrsModified)
+
+
+// Save changes to file
+
+texteditfile.txt changed (isFile, renamed, finderInfoModified, xattrsModified)
+texteditfile.txt.sb-56afa5c6-DmdqsL changed (isFile, renamed)
+texteditfile.txt changed (isFile, renamed, finderInfoModified, xattrsModified)
+texteditfile.txt changed (isFile, renamed, finderInfoModified, inodeMetaModified, xattrsModified)
+texteditfile.txt.sb-56afa5c6-DmdqsL changed (isFile, modified, removed, renamed, changeOwner)
+texteditfile.txt changed (isFile, renamed, finderInfoModified, inodeMetaModified, xattrsModified)
+```
+
+You see that overwriting a file _atomically_ will fire a lot of events when you use a modern document-based macOS app like TextEdit. The authors interpretation of these events is: "get rid of the original file, move in temp file with changes, copy temp file to original file's path, then get rid of the temp file". It could mean the original file is renamed to the temporary looking name just as well as far as I know. (Which, apparently, isn't much.)
+
+Now see the log for the same actions with a latency of 1 second:
+
+```
+// Create file in folder
+
+texteditfile.txt changed (isFile, renamed, finderInfoModified, xattrsModified)
+
+// Save changes to file
+
+texteditfile.txt changed (isFile, renamed, finderInfoModified, xattrsModified)
+texteditfile.txt.sb-56afa5c6-SOiDRl changed (isFile, renamed)
+texteditfile.txt changed (isFile, renamed, finderInfoModified, inodeMetaModified, xattrsModified)
+texteditfile.txt.sb-56afa5c6-SOiDRl changed (isFile, modified, removed, renamed, changeOwner)
+```
+
+(Doesn't get any better than this.)
+
+So maybe a latency of slightly above >0.0 can help get rid of noise. Makes even more sense when you coalesce the `RxSwift.Observable` events in the end.
+
+Note that other editors like TextMate 2 don't write to files with the same mechanism and only generate a single event, similar to what you'd expect from file changes originating in the shell:
+
+```
+texteditfile.txt changed (isFile, modified, xattrsModified)
+```
+
+
+## Event Interpretation
+
+Look at the repository's issues -- there's still a lot of room for improvement. This boils down to applying _interpretation_ and _heuristics_. In other words, it might break or be utterly wrong.
+
+At the moment, each and every FSEvent is forwarded to the callback (or observer).
+
+But FSEvents sometimes come in pairs, like:
+
+```
+texteditfile.txt changed (isFile, renamed, finderInfoModified, xattrsModified)
+texteditfile.txt.sb-56afa5c6-SOiDRl changed (isFile, renamed)
+```
+
+That means the library could try to make sense of event pairs and reduce them to single events for the client. Instead of forwarding an event of the form "`texteditfile.txt.sb-56afa5c6-SOiDRl` was renamed" which, in client's terms, will be interpreted as "the file was moved in there", the library could fire a single "edited" event.
+
+Also noteworthy: the `removed` event will not be fired when trashing a file from Finder even though it was fired when TextEdit saved file changes and got rid of the intermediate result file. Some `renamed` events thus really are `removed` events and you need to check the file at the URL for existence after the event comes in. With a certain latency, or else you may pick up the about-to-be-trashed file _before_ its being moved is completed. 
+
+
 ## License
 
 Copyright (c) 2016 RxSwiftCommunity https://github.com/RxSwiftCommunity

RxFileMonitor/FolderContentMonitor.swift

@@ -21,34 +21,43 @@ public class FolderContentMonitor {
     public let pathsToWatch: [String]
     public private(set) var hasStarted = false
     private var streamRef: FSEventStreamRef!
-
+    public let latency: CFTimeInterval
     public private(set) var lastEventId: FSEventStreamEventId
 
     /// - parameter url: Folder to monitor.
     /// - parameter sinceWhen: Reference event for the subscription. Default
     ///   is `kFSEventStreamEventIdSinceNow`.
+    /// - parameter latency: Interval (in seconds) to allow coalescing events.
     /// - parameter callback: Callback for incoming file system events. Can be ignored
     ///   when you use the monitor `asObservable`
     public convenience init(
         url: URL,
         sinceWhen: FSEventStreamEventId = FSEventStreamEventId(kFSEventStreamEventIdSinceNow),
+        latency: CFTimeInterval = 0,
         callback: ((FolderContentChangeEvent) -> Void)? = nil) {
 
-        self.init(pathsToWatch: [url.path], sinceWhen: sinceWhen, callback: callback)
+        self.init(
+            pathsToWatch: [url.path],
+            sinceWhen: sinceWhen,
+            latency: latency,
+            callback: callback)
     }
 
     /// - parameter pathsToWatch: Collection of file or folder paths.
     /// - parameter sinceWhen: Reference event for the subscription. Default 
     ///   is `kFSEventStreamEventIdSinceNow`.
+    /// - parameter latency: Interval (in seconds) to allow coalescing events.
     /// - parameter callback: Callback for incoming file system events. Can be ignored
     ///   when you use the monitor `asObservable`
     public init(
         pathsToWatch: [String],
         sinceWhen: FSEventStreamEventId = FSEventStreamEventId(kFSEventStreamEventIdSinceNow),
+        latency: CFTimeInterval = 0,
         callback: ((FolderContentChangeEvent) -> Void)? = nil) {
 
         self.lastEventId = sinceWhen
         self.pathsToWatch = pathsToWatch
+        self.latency = latency
         self.callback = callback
     }
 
@@ -63,7 +72,14 @@ public class FolderContentMonitor {
         var context = FSEventStreamContext(version: 0, info: nil, retain: nil, release: nil, copyDescription: nil)
         context.info = Unmanaged.passUnretained(self).toOpaque()
         let flags = UInt32(kFSEventStreamCreateFlagUseCFTypes | kFSEventStreamCreateFlagFileEvents)
-        streamRef = FSEventStreamCreate(kCFAllocatorDefault, eventCallback, &context, pathsToWatch as CFArray, lastEventId, 0, flags)
+        streamRef = FSEventStreamCreate(
+            kCFAllocatorDefault,
+            eventCallback,
+            &context,
+            pathsToWatch as CFArray,
+            lastEventId,
+            latency,
+            flags)
 
         FSEventStreamScheduleWithRunLoop(streamRef, CFRunLoopGetMain(), CFRunLoopMode.defaultMode.rawValue)
         FSEventStreamStart(streamRef)