class DirectoryWatcher

Declaration

class DirectoryWatcher { /* full declaration omitted */ };

Description

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.

Declared at: clang/include/clang/DirectoryWatcher/DirectoryWatcher.h:64

Method Overview

• public DirectoryWatcher(const clang::DirectoryWatcher &)
• public DirectoryWatcher(clang::DirectoryWatcher &&)
• protected DirectoryWatcher()
• public static llvm::Expected<std::unique_ptr<DirectoryWatcher>> create(llvm::StringRef Path, std::function<void (llvm::ArrayRef<DirectoryWatcher::Event>, bool)> Receiver, bool WaitForInitialSync)
• public virtual ~DirectoryWatcher()

Methods

¶DirectoryWatcher(const clang::DirectoryWatcher&)

Declared at: clang/include/clang/DirectoryWatcher/DirectoryWatcher.h:114

Parameters

const clang::DirectoryWatcher&

¶DirectoryWatcher(clang::DirectoryWatcher&&)

Declared at: clang/include/clang/DirectoryWatcher/DirectoryWatcher.h:116

Parameters

clang::DirectoryWatcher&&

¶DirectoryWatcher()

Declared at: clang/include/clang/DirectoryWatcher/DirectoryWatcher.h:119

¶static llvm::Expected<
    std::unique_ptr<DirectoryWatcher>>
create(
    llvm::StringRef Path,
    std::function<void(
        llvm::ArrayRef<DirectoryWatcher::Event>,
        bool)> Receiver,
    bool WaitForInitialSync)

Description

llvm fatal_error if

Declared at: clang/include/clang/DirectoryWatcher/DirectoryWatcher.h:107

Parameters

llvm::StringRef 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.

std::function<void( llvm::ArrayRef<DirectoryWatcher::Event>, bool)> Receiver

bool WaitForInitialSync

¶virtual ~DirectoryWatcher()

Declared at: clang/include/clang/DirectoryWatcher/DirectoryWatcher.h:113