Features

Get notified about modified files or directories
Get notified about added / removed / renamed files or directories

Status

🟩 Usable
Library does have basic capabilities and it can be used just fine.

Description

Caller can specify a callback for receiving notifications the SC::FileSystemWatcher::watch method.

Changes are grouped in two categories:

Added, removed and renamed files and directories
Modified files

There are two modes in which FileSystemWatcher can be initialized, defining how notifications are delivered:

Mode	Description
SC::FileSystemWatcher::ThreadRunner	Delivers notifications on a background thread.
SC::FileSystemWatcher::EventLoopRunner	Delivers notifications using Async (SC::AsyncEventLoop).

Example using SC::FileSystemWatcher::EventLoopRunner:

    // Initialize the FileSystemWatcher
    FileSystemWatcher fileSystemWatcher;
 
    FileSystemWatcher::EventLoopRunner eventLoopRunner;
    SC_TRY(fileSystemWatcher.init(eventLoopRunner, eventLoop));
 
    // Setup notification callback
    auto onFileModified = [&](const FileSystemWatcher::Notification& notification)
    {
        // This callback will be called from the thread calling AsyncEventLoop::run
        SmallString<1024> buffer;
        StringView        fullPath;
        if (notification.getFullPath(buffer, fullPath))
        {
            switch (notification.operation)
            {
            case FileSystemWatcher::Operation::Modified: // File has been modified
                console.print("Modified {} {}\n", notification.relativePath, fullPath);
                break;
            case FileSystemWatcher::Operation::AddRemoveRename: // File was added / removed
                console.print("AddRemoveRename {} {}\n", notification.relativePath, fullPath);
                break;
            }
        }
    };
 
    // Start watching a specific folder
    FileSystemWatcher::FolderWatcher folderWatcher;
    folderWatcher.notifyCallback = onFileModified;
    SC_TRY(fileSystemWatcher.watch(folderWatcher, "/path/to/dir"));
 
    // ...
    // At a later point when there is no more need of watching the folder
    SC_TRY(folderWatcher.stopWatching());
 
    // ...
    // When all watchers have been unwatched and to dispose all system resources
    SC_TRY(fileSystemWatcher.close());

Example using SC::FileSystemWatcher::ThreadRunner:

    // Initialize the FileSystemWatcher
    FileSystemWatcher::ThreadRunner threadRunner; // <--- The thread runner
 
    FileSystemWatcher fileSystemWatcher;
    SC_TRY(fileSystemWatcher.init(threadRunner));
 
    // Setup notification callback
    auto onFileModified = [&](const FileSystemWatcher::Notification& notification)
    {
        // Warning! This callback is called from a background thread!
        // Make sure to do proper synchronization!
        SmallString<1024> buffer;
        StringView        fullPath;
        if (notification.getFullPath(buffer, fullPath))
        {
            switch (notification.operation)
            {
            case FileSystemWatcher::Operation::Modified: // File has been modified
                console.print("Modified {} {}\n", notification.relativePath, fullPath);
                break;
            case FileSystemWatcher::Operation::AddRemoveRename: // File was added / removed
                console.print("AddRemoveRename {} {}\n", notification.relativePath, fullPath);
                break;
            }
        }
    };
 
    // Start watching a specific folder
    FileSystemWatcher::FolderWatcher folderWatcher;
    folderWatcher.notifyCallback = onFileModified;
    SC_TRY(fileSystemWatcher.watch(folderWatcher, "/path/to/dir"));
 
    // ...
    // At a later point when there is no more need of watching the folder
    SC_TRY(folderWatcher.stopWatching());
 
    // ...
    // When all watchers have been unwatched and to dispose all system resources
    SC_TRY(fileSystemWatcher.close());

Videos

This is the list of videos that have been recorded showing some of the internal thoughts that have been going into this library:

Ep.09 - SC::FileSystemWatcher Linux inotify implementation

Blog

Some relevant blog posts are:

June 2024 Update

Details

The class tries to unify differences between OS specific API to deliver folder change notifications

On macOS and iOS FSEvents by CoreServices is used.
On Windows ReadDirectoryChangesW is used.

The behavior between these different system also depends on the file system where the watched directory resides.

Note: On iOS FSEvents api is private so using SC::FileSystemWatcher will be very likely causing your app to be rejected from the app store.

Examples

SCExample uses SC::FileSystemWatcher for a simple hot-reload system
Unit test inside FileSystemWatcherTest.cpp show how the API is meant to be used

Roadmap

🟦 Complete Features:

Not sure what else could be useful here

💡 Unplanned Features:

Having a thread based polling stat watcher that checks file modifications on intervals as fallback
Allow users to provide their own thread instead of creating it behind the scenes

Table of Contents