RFR: 8293067: (fs) Implement WatchService using system library (macOS) [v3]

[Brian Burkhalter]

On Tue, 13 Sep 2022 08:10:53 GMT, Maxim Kartashev <mkartashev at openjdk.org> wrote:

>> This is an implementation of `WatchService` based on File System Events API that is capable of generating events whenever a change occurs in an interesting directory or underneath it. Since the API naturally supports "recursive" watch, the `FILE_TREE` is supported by the watch service. 
>> 
>> Some things of note:
>> * There's one "service" thread per `WatchService` instance that is inactive unless changes occur in the watched directory. The changes are grouped by introducing a time delay between when they occurred and when they are reported, which is controlled by the sensitivity modifier of the watch service.
>> * Since FSEvents API reports directories only, the watch service keeps a snapshot (hierarchical if necessary) of the files in the directory being watched. The snapshot gets updated when an event in that directory or underneath it gets delivered. File changes are detected by comparing "last modified" time with a millisecond precision (`BasicFileAttributes.lastModifiedTime()`).
>> * There is a slight complication with the move of an entire directory hierarchy: FSEvents API only reports about the containing directory of that move and not about any of the directories actually moved. There's a separate test for that (`Move.java`).
>> * The code is careful not to do any I/O (such as reading the contents of a directory or attributes of a file) unless unavoidable. Any deviation from this line should be considered a bug (of, arguably, low priority).
>> * The native part consists mostly of API wrappers with one exception of the callback function invoked by the system to report the events that occurred. The sole task of the function is to convert from C strings to Java strings and pass the array of affected directories to Java code. This can be rewritten if desired to make the code more future-proof.
>> 
>> This commit leaves `PollingWatchService` unused. I'm not sure if I should/can do anything about it. Any advice is welcomed.
>> 
>> ### Testing
>> 
>> * Tested by running `test/jdk/java/nio/file` and `test/jdk/jdk/nio` on MacOS 10.15.7 (x64) and `test/jdk/java/nio/` plus `test/jdk/jdk/nio` on MacOS 12.5.1 (aarch64).
>> * Also verified that new tests pass on Linux and Windows.
>> * This code (albeit in a slightly modified form) has been in use at JetBrains for around half a year and a few bugs have been found and fixed during that time period.
>
> Maxim Kartashev has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Removed the change unnecessary without recursive watch

src/java.base/macosx/classes/sun/nio/fs/MacOSXWatchService.java line 129:

> 127:      * that need to be re-scanned.
> 128:      */
> 129:     private void callback(final long eventStreamRef,

Could this be named something more descriptive than `callback`, perhaps even `handleEvents` even though there is a method of the same name defined in `MacOSXWatchKey`?

src/java.base/macosx/classes/sun/nio/fs/MacOSXWatchService.java line 396:

> 394:                 if (!relativeRootPath.equals(path)) {
> 395:                     // Ignore events from subdirectories for now.
> 396:                     continue;

Should a line

eventFlagsPtr += SIZEOF_FS_EVENT_STREAM_EVENT_FLAGS;

be added here? (The definition of `SIZEOF_FS_EVENT_STREAM_EVENT_FLAGS` would have to be moved up.)

src/java.base/macosx/classes/sun/nio/fs/MacOSXWatchService.java line 399:

> 397:                 }
> 398: 
> 399:                 final int flags = unsafe.getInt(eventFlagsPtr);

This looks like the only use of `Unsafe`. Could the objective be accomplished without using it, e.g., changing `long eventFlagsPtr` to a `long[]` or, maybe even simpler, a `boolean[]`?

src/java.base/macosx/native/libnio/fs/MacOSXWatchService.c line 73:

> 71:         (*env)->CallVoidMethod(env, watchService, callbackMID,
> 72:                                streamRef, javaEventPathsArray, eventFlags);
> 73:     }

Is there a way to notify of events without an upcall? Maybe add the necessary values to a queue of some sort observed by the Java layer?

src/java.base/macosx/native/libnio/fs/MacOSXWatchService.c line 89:

> 87: {
> 88:     JNIEnv *env = (JNIEnv *) JNU_GetEnv(jvm, JNI_VERSION_1_2);
> 89:     if (!env) { // Shouldn't happen as run loop starts from Java code

Is this check, hence the `jvm` extern, really necessary?

src/java.base/macosx/native/libnio/fs/MacOSXWatchService.c line 199:

> 197: 
> 198:     FSEventStreamStop(streamRef);       // Unregister with the FS Events service.
> 199:                                         // No more callbacks from this stream.

Does `FSEventStreamUnscheduleFromRunLoop()` need to be called here?

-------------

PR: https://git.openjdk.org/jdk/pull/10140