FileSystemWatcher.h

// Copyright (c) Stefano Cristiano
// SPDX-License-Identifier: MIT
#pragma once
 
#include "../Common/CompilerMacrosExport.h"
#ifndef SC_EXPORT_LIBRARY_FILE_SYSTEM_WATCHER
#define SC_EXPORT_LIBRARY_FILE_SYSTEM_WATCHER 0
#endif
#define SC_FILE_SYSTEM_WATCHER_EXPORT SC_COMPILER_LIBRARY_EXPORT(SC_EXPORT_LIBRARY_FILE_SYSTEM_WATCHER)
 
#include "../Common/Assert.h"
#include "../Common/CompilerOffsetOf.h"
#include "../Common/Function.h"
#include "../Common/IGrowableBufferStringPath.h"
#include "../Common/OpaqueObject.h"
#include "../Common/PlatformMacrosType.h"
#include "../Common/Result.h"
#include "FileSystemWatcherError.h"
 
namespace SC
{
SC_DECLARE_ASSERT_PROVIDER(FileSystemWatcherAssert, SC_FILE_SYSTEM_WATCHER_EXPORT);
 
#define SC_FILE_SYSTEM_WATCHER_ASSERT_RELEASE(e)        SC_ASSERT_PROVIDER_RELEASE(SC::FileSystemWatcherAssert, e)
#define SC_FILE_SYSTEM_WATCHER_ASSERT_DEBUG(e)          SC_ASSERT_PROVIDER_DEBUG(SC::FileSystemWatcherAssert, e)
#define SC_FILE_SYSTEM_WATCHER_TRUST_RESULT(expression) SC_FILE_SYSTEM_WATCHER_ASSERT_RELEASE(expression)
 
 
 
 
struct FileSystemWatcher
{
  private:
    struct Internal;
 
    struct InternalDefinition
    {
        static constexpr int Windows = 3 * sizeof(void*);
        // Two extra pointers are temporary while Result and ResultFileSystemWatcher carry migration context.
        static constexpr int Apple   = 44 * sizeof(void*);
        static constexpr int Linux   = sizeof(void*) * 4;
        static constexpr int Default = Linux;
 
        static constexpr size_t Alignment = alignof(void*);
 
        using Object = Internal;
    };
 
  public:
    // Must be public to avoid GCC complaining
    using InternalOpaque = OpaqueObject<InternalDefinition>;
 
  private:
    InternalOpaque internal;
 
    //...
    struct ThreadRunnerInternal;
    struct ThreadRunnerDefinition
    {
        static constexpr int MaxWatchablePaths = 1024;
 
        static constexpr int Windows = (2 * MaxWatchablePaths + 2) * sizeof(void*) + sizeof(uint64_t);
        static constexpr int Apple   = sizeof(void*);
        static constexpr int Linux   = sizeof(void*) * 6;
        static constexpr int Default = Linux;
 
        static constexpr size_t Alignment = alignof(void*);
 
        using Object = ThreadRunnerInternal;
    };
 
    struct FolderWatcherInternal;
    struct FolderWatcherSizes
    {
        static constexpr int MaxNumberOfSubdirs   = 128; // Max number of subfolders tracked in a watcher
        static constexpr int MaxChangesBufferSize = 16 * 1024;
 
        static constexpr int Windows = MaxChangesBufferSize + sizeof(void*) + sizeof(void*);
        static constexpr int Apple   = sizeof(void*);
        static constexpr int Linux   = 1056 + 4096 + 8;
        static constexpr int Default = Linux;
 
        static constexpr size_t Alignment = alignof(void*);
 
        using Object = FolderWatcherInternal;
    };
 
  public:
    enum class Operation
    {
        Modified,        
        AddRemoveRename, 
    };
 
    struct Notification
    {
        StringSpan basePath;                        
        StringSpan relativePath;                    
        Operation  operation = Operation::Modified; 
 
        ResultFileSystemWatcher getFullPath(StringPath& path) const;
 
      private:
        friend struct Internal;
#if SC_PLATFORM_APPLE
        StringSpan fullPath;
#endif
    };
 
    struct FolderWatcher
    {
        FolderWatcher(Span<char> subFolderRelativePathsBuffer = {});
 
        Function<void(const Notification&)> notifyCallback; 
 
        ResultFileSystemWatcher stopWatching();
 
        void setDebugName(const char* debugName);
 
      private:
        friend struct FileSystemWatcher;
        template <typename T_AsyncEventLoop>
        friend struct FileSystemWatcherAsyncT;
#if SC_PLATFORM_WINDOWS
#if SC_ASYNC_ENABLE_LOG
        AlignedStorage<160> asyncStorage;
#else
        AlignedStorage<152> asyncStorage;
#endif
#endif
        OpaqueObject<FolderWatcherSizes> internal;
 
        FileSystemWatcher* parent = nullptr;
        FolderWatcher*     next   = nullptr;
        FolderWatcher*     prev   = nullptr;
 
        StringPath path;
 
#if SC_PLATFORM_LINUX
        Span<char> subFolderRelativePathsBuffer;
#endif
    };
 
    struct EventLoopRunner
    {
        virtual ~EventLoopRunner() {}
 
      protected:
#if SC_PLATFORM_APPLE
        virtual Result appleStartWakeUp()       = 0;
        virtual Result appleStopWakeUp()        = 0;
        virtual void   appleSignalEventObject() = 0;
        virtual Result appleWakeUpAndWait()     = 0;
 
#elif SC_PLATFORM_LINUX
        virtual Result linuxStartSharedFileReadiness() = 0;
        virtual Result linuxStopSharedFileReadiness()  = 0;
 
        int notifyFd = -1;
 
#else
        virtual Result windowsStartFolderExternalCompletion(FolderWatcher& watcher, void* handle) = 0;
        virtual Result windowsRequestStopFolderExternalCompletion(FolderWatcher& watcher)         = 0;
        virtual Result windowsWaitFolderExternalCompletionStopped(FolderWatcher& watcher)         = 0;
        virtual Result windowsMarkFolderExternalCompletionPending(FolderWatcher& watcher)         = 0;
        virtual Result windowsClearFolderExternalCompletionPending(FolderWatcher& watcher)        = 0;
        virtual void*  windowsGetOverlapped(FolderWatcher& watcher)                               = 0;
#endif
        friend struct Internal;
        FileSystemWatcher* fileSystemWatcher = nullptr;
 
        void internalInit(FileSystemWatcher& fsWatcher, int handle);
    };
 
    using ThreadRunner = OpaqueObject<ThreadRunnerDefinition>;
 
    ResultFileSystemWatcher init(ThreadRunner& runner);
 
    ResultFileSystemWatcher init(EventLoopRunner& runner);
 
    ResultFileSystemWatcher close();
 
    ResultFileSystemWatcher watch(FolderWatcher& watcher, StringSpan path);
 
    void asyncNotify(FolderWatcher* watcher, size_t bytesTransferred = 0);
 
  private:
    friend decltype(internal);
    friend decltype(FolderWatcher::internal);
    template <typename T_AsyncEventLoop>
    friend struct FileSystemWatcherAsyncT;
    // Trimmed duplicate of IntrusiveDoubleLinkedList<T>
    struct WatcherLinkedList
    {
        FolderWatcher* back  = nullptr; // has no next
        FolderWatcher* front = nullptr; // has no prev
 
        void queueBack(FolderWatcher& watcher);
        void remove(FolderWatcher& watcher);
    };
    WatcherLinkedList watchers;
};
 
template <typename T_AsyncEventLoop>
struct FileSystemWatcherAsyncT : public FileSystemWatcher::EventLoopRunner
{
    using Self = FileSystemWatcherAsyncT;
 
    using T_AsyncLoopWakeUp         = typename T_AsyncEventLoop::LoopWakeUp;
    using T_AsyncFileReadiness      = typename T_AsyncEventLoop::FileReadiness;
    using T_AsyncExternalCompletion = typename T_AsyncEventLoop::ExternalCompletion;
    using T_EventObject             = typename T_AsyncEventLoop::EventObjectType;
    using T_AsyncResult             = typename T_AsyncEventLoop::ResultType;
 
    void init(T_AsyncEventLoop& loop) { eventLoop = &loop; }
 
  protected:
    T_AsyncEventLoop* eventLoop = nullptr;
 
#if SC_PLATFORM_APPLE
    virtual Result appleStartWakeUp() override
    {
        if (eventLoop == nullptr or fileSystemWatcher == nullptr)
            return Result::Error(FileSystemWatcherResultCategory, FileSystemWatcherError::NotInitialized);
        T_AsyncLoopWakeUp& wakeUp = asyncWakeUp;
        wakeUp.callback.template bind<Self, &Self::onEventLoopNotification>(*this);
        return wakeUp.start(*eventLoop);
    }
 
    virtual void appleSignalEventObject() override { eventObject.signal(); }
 
    virtual Result appleStopWakeUp() override
    {
        notificationGeneration++;
        if (not asyncWakeUp.isFree())
        {
            SC_TRY(asyncWakeUp.stop(*eventLoop));
            while (not asyncWakeUp.isFree())
            {
                SC_TRY(eventLoop->runNoWait());
            }
        }
        // The producer is quiescent now; consume any unused refresh/close handoff signal.
        eventObject.signal();
        eventObject.wait();
        return Result(true);
    }
 
    virtual Result appleWakeUpAndWait() override
    {
        const Result res = asyncWakeUp.wakeUp(*eventLoop);
        eventObject.wait();
        return res;
    }
 
    void onEventLoopNotification(typename T_AsyncLoopWakeUp::Result& result)
    {
        const size_t generation = notificationGeneration;
        result.reactivateRequest(true);
        fileSystemWatcher->asyncNotify(nullptr);
        if (generation == notificationGeneration)
        {
            eventObject.signal();
        }
    }
 
    size_t notificationGeneration = 0;
 
    T_AsyncLoopWakeUp asyncWakeUp = {};
    T_EventObject     eventObject = {};
#elif SC_PLATFORM_LINUX
    virtual Result linuxStartSharedFileReadiness() override
    {
        if (eventLoop == nullptr or fileSystemWatcher == nullptr)
            return Result::Error(FileSystemWatcherResultCategory, FileSystemWatcherError::NotInitialized);
        SC_TRY(eventLoop->associateExternallyCreatedFileDescriptorHandle(notifyFd));
        asyncPoll.callback.template bind<Self, &Self::onEventLoopNotification>(*this);
        return asyncPoll.start(*eventLoop, notifyFd);
    }
 
    virtual Result linuxStopSharedFileReadiness() override { return asyncPoll.stop(*eventLoop); }
 
    void onEventLoopNotification(typename T_AsyncFileReadiness::Result& result)
    {
        fileSystemWatcher->asyncNotify(nullptr);
        result.reactivateRequest(true);
    }
 
    T_AsyncFileReadiness asyncPoll = {};
#else
    using FolderWatcher = FileSystemWatcher::FolderWatcher;
    virtual Result windowsStartFolderExternalCompletion(FolderWatcher& watcher, void* handle) override
    {
        if (eventLoop == nullptr or fileSystemWatcher == nullptr)
            return Result::Error(FileSystemWatcherResultCategory, FileSystemWatcherError::NotInitialized);
        T_AsyncExternalCompletion& completion =
            watcher.asyncStorage.template reinterpret_as<T_AsyncExternalCompletion>();
        placementNew(completion);
        completion.setDebugName("FileSystemWatcherAsync Completion");
        completion.callback.template bind<Self, &Self::onEventLoopNotification>(*this);
        return completion.start(*eventLoop, handle);
    }
 
    virtual Result windowsRequestStopFolderExternalCompletion(FolderWatcher& watcher) override
    {
        T_AsyncExternalCompletion& completion =
            watcher.asyncStorage.template reinterpret_as<T_AsyncExternalCompletion>();
 
        windowsFolderCompletionStopped = false;
        onAsyncCompletionClose         = [this, &watcher](T_AsyncResult&)
        {
            T_AsyncExternalCompletion& completion =
                watcher.asyncStorage.template reinterpret_as<T_AsyncExternalCompletion>();
            completion.~T_AsyncExternalCompletion();
            windowsFolderCompletionStopped = true;
        };
        return completion.stop(*eventLoop, &onAsyncCompletionClose);
    }
 
    virtual Result windowsWaitFolderExternalCompletionStopped(FolderWatcher&) override
    {
        while (not windowsFolderCompletionStopped)
        {
            SC_TRY(eventLoop->runOnce());
        }
        return Result(true);
    }
 
    virtual Result windowsMarkFolderExternalCompletionPending(FolderWatcher& watcher) override
    {
        T_AsyncExternalCompletion& completion =
            watcher.asyncStorage.template reinterpret_as<T_AsyncExternalCompletion>();
        return completion.markSubmissionPending();
    }
 
    virtual Result windowsClearFolderExternalCompletionPending(FolderWatcher& watcher) override
    {
        T_AsyncExternalCompletion& completion =
            watcher.asyncStorage.template reinterpret_as<T_AsyncExternalCompletion>();
        return completion.clearSubmissionPending();
    }
 
    virtual void* windowsGetOverlapped(FolderWatcher& watcher) override
    {
        T_AsyncExternalCompletion& completion =
            watcher.asyncStorage.template reinterpret_as<T_AsyncExternalCompletion>();
        return completion.getWindowsOverlapped();
    }
 
    void onEventLoopNotification(typename T_AsyncExternalCompletion::Result& result)
    {
        SC_COMPILER_WARNING_PUSH_OFFSETOF;
        auto&          storage = reinterpret_cast<decltype(FolderWatcher::asyncStorage)&>(result.getAsync());
        FolderWatcher& watcher = SC_COMPILER_FIELD_OFFSET(FolderWatcher, asyncStorage, storage);
        fileSystemWatcher->asyncNotify(&watcher, result.completionData.bytesTransferred);
        if (watcher.parent != nullptr and result.getAsync().hasSubmissionPending())
        {
            result.reactivateRequest(true);
        }
        SC_COMPILER_WARNING_POP_OFFSETOF;
    }
 
    Function<void(T_AsyncResult&)> onAsyncCompletionClose;
    bool                           windowsFolderCompletionStopped = false;
#endif
};
 
} // namespace SC