/*
 * Copyright 2021 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.gradle.internal.watch.registry;

import java.io.File;
import java.util.stream.Stream;

public interface FileWatcherProbeRegistry {
    void registerProbe(File hierarchy);

    Stream<File> unprovenHierarchies();

    void armWatchProbe(File watchableHierarchy);

    void disarmWatchProbe(File watchableHierarchy);

    void triggerWatchProbe(String path);

    File getProbeDirectory(File hierarchy);
}

@@ -709,16 +709,1277 @@
 tream;%0A%0A
+/**%0A * A registry of watch probes. A probe serves as a way to prove that a hierarchy Gradle is interested in%0A * indeed receives file system events from the operating system.%0A * This is to avoid trusting locations where OSs silently not send any events, despite watchers being registered.%0A *%0A * When the hierarchy is first registered via %7B@link #registerProbe(File)%7D, we don't yet create the probe.%0A * That only happens when the hierarchy is actually read or written by Gradle, in which case%0A * %7B@link #armWatchProbe(File)%7D is called.%0A *%0A * When the probe is armed, a probe file is created (or re-created) under the hierarchy.%0A * This should cause a file system event to be produced by the operating system.%0A * We listen to specifically in %7B@link FileWatcherRegistry%7D.%0A * Once the event arrives, %7B@link #triggerWatchProbe(String)%7D is called with the path,%0A * and the probe becomes triggered (or proven).%0A *%0A * The %7B@link #unprovenHierarchies()%7D stream returns any hierarchies that were armed, but never received%0A * a file system event.%0A * These locations cannot be trusted to receive file system events in a timely manner.%0A *%0A * Note: a probe needs to be armed only once, if it receives an event, we will trust that location until%0A * the registry is closed.%0A */%0A
 public i

Document registry