//===- DirectoryWatcher.h - Listens for directory file changes --*- C++ -*-===//

//

// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.

// See https://llvm.org/LICENSE.txt for license information.

// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

//

//===----------------------------------------------------------------------===//

#ifndef LLVM_CLANG_DIRECTORYWATCHER_DIRECTORYWATCHER_H

#define LLVM_CLANG_DIRECTORYWATCHER_DIRECTORYWATCHER_H

#include "llvm/ADT/ArrayRef.h"

#include "llvm/ADT/StringRef.h"

#include "llvm/Support/Error.h"

#include <functional>

#include <memory>

#include <string>

namespace clang {

/// Provides notifications for file changes in a directory.

///

/// Invokes client-provided function on every filesystem event in the watched

/// directory. Initially the watched directory is scanned and for every file

/// found, an event is synthesized as if the file was added.

///

/// This is not a general purpose directory monitoring tool - list of

/// limitations follows.

///

/// Only flat directories with no subdirectories are supported. In case

/// subdirectories are present the behavior is unspecified - events *might* be

/// passed to Receiver on macOS (due to FSEvents being used) while they

/// *probably* won't be passed on Linux (due to inotify being used).

///

/// Known potential inconsistencies

/// - For files that are deleted befor the initial scan processed them, clients

/// might receive Removed notification without any prior Added notification.

/// - Multiple notifications might be produced when a file is added to the

/// watched directory during the initial scan. We are choosing the lesser evil

/// here as the only known alternative strategy would be to invalidate the

/// watcher instance and force user to create a new one whenever filesystem

/// event occurs during the initial scan but that would introduce continuous

/// restarting failure mode (watched directory is not always "owned" by the same

/// process that is consuming it). Since existing clients can handle duplicate

/// events well, we decided for simplicity.

///

/// Notifications are provided only for changes done through local user-space

/// filesystem interface. Specifically, it's unspecified if notification would

/// be provided in case of a:

/// - a file mmap-ed and changed

/// - a file changed via remote (NFS) or virtual (/proc) FS access to monitored

/// directory

/// - another filesystem mounted to the watched directory

///

/// No support for LLVM VFS.

///

/// It is unspecified whether notifications for files being deleted are sent in

/// case the whole watched directory is sent.

///

/// Directories containing "too many" files and/or receiving events "too

/// frequently" are not supported - if the initial scan can't be finished before

/// the watcher instance gets invalidated (see WatcherGotInvalidated) there's no

/// good error handling strategy - the only option for client is to destroy the

/// watcher, restart watching with new instance and hope it won't repeat.

class DirectoryWatcher {

public:

  struct Event {

    enum class EventKind {

      Removed,

      /// Content of a file was modified.

      Modified,

      /// The watched directory got deleted.

      WatchedDirRemoved,

      /// The DirectoryWatcher that originated this event is no longer valid and

      /// its behavior is unspecified.

      ///

      /// The prime case is kernel signalling to OS-specific implementation of

      /// DirectoryWatcher some resource limit being hit.

      /// *Usually* kernel starts dropping or squashing events together after

      /// that and so would DirectoryWatcher. This means that *some* events

      /// might still be passed to Receiver but this behavior is unspecified.

      ///

      /// Another case is after the watched directory itself is deleted.

      /// WatcherGotInvalidated will be received at least once during

      /// DirectoryWatcher instance lifetime - when handling errors this is done

      /// on best effort basis, when an instance is being destroyed then this is

      /// guaranteed.

      ///

      /// The only proper response to this kind of event is to destruct the

      /// originating DirectoryWatcher instance and create a new one.

      WatcherGotInvalidated

    };

    EventKind Kind;

    /// Filename that this event is related to or an empty string in

    /// case this event is related to the watched directory itself.

    std::string Filename;

    Event(EventKind Kind, llvm::StringRef Filename)

        : Kind(Kind), Filename(Filename) {}

  };

  /// llvm fatal_error if \param Path doesn't exist or isn't a directory.

  /// Returns llvm::Expected Error if OS kernel API told us we can't start

  /// watching. In such case it's unclear whether just retrying has any chance

  /// to succeed.

  static llvm::Expected<std::unique_ptr<DirectoryWatcher>>

  create(llvm::StringRef Path,

         std::function<void(llvm::ArrayRef<DirectoryWatcher::Event> Events,

                            bool IsInitial)>

             Receiver,

         bool WaitForInitialSync);

  virtual ~DirectoryWatcher() = default;

  DirectoryWatcher(const DirectoryWatcher &) = delete;

  DirectoryWatcher &operator=(const DirectoryWatcher &) = delete;

  DirectoryWatcher(DirectoryWatcher &&) = default;

protected:

  DirectoryWatcher() = default;

};

} // namespace clang

#endif // LLVM_CLANG_DIRECTORYWATCHER_DIRECTORYWATCHER_H