Corrade::Utility::FileWatcher class
#include <Corrade/Utility/FileWatcher.h>

File watcher.

Provides a non-blocking interface to watch a single file for changes. Example usage:

Utility::FileWatcher watcher{"settings.conf"};

// in the main application loop
if(watcher.hasChanged()) {
    // reload the settings
}

Behavior

The generic implementation (currently used on all supported systems) checks for file modification time and reports a change if the modification time changes. Deleting a file and immediately recreating it with the same name will behave the same as simply updating that file, unless the file status is checked during the short time when it was deleted — in that case isValid() will return false and monitoring is stopped. Pass Flag::IgnoreErrors to the constructor to disable this behavior. Similarly, in some cases a file update might first empty the contents, update modification timestamp and only then populate it with updated data but without a second timestamp update. Reacting to the update when the file is still empty might be counterproductive as well, enable Flag::IgnoreChangeIfEmpty to detect and ignore this case as well.

Different OSes and filesystems have different granularity of filesystem modification time:

  • Most native Linux filesystems (such as ext4) will report file modification time in millisecond precision (usually tens of milliseconds)
  • Windows, macOS and Emscripten file modification time APIs return the value in seconds, FAT filesystems have two-second precision

Public types

enum class Flag: std::uint8_t { IgnoreErrors = 1 << 0, IgnoreChangeIfEmpty = 1 << 1 } new in 2019.10
Watch behavior flag.
using Flags = Containers::EnumSet<Flag> new in 2019.10
Watch behavior flags.

Constructors, destructors, conversion operators

FileWatcher(Containers::StringView filename, Flags flags = {}) explicit
Constructor.
FileWatcher(const FileWatcher&) deleted
Copying is not allowed.
FileWatcher(FileWatcher&&) noexcept
Move constructor.

Public functions

auto operator=(const FileWatcher&) -> FileWatcher& deleted
Copying is not allowed.
auto operator=(FileWatcher&&) -> FileWatcher& noexcept
Move assignment.
auto flags() const -> Flags
Watch behavior flags.
auto isValid() const -> bool
Whether the file watcher is valid.
auto hasChanged() -> bool
Whether the file has changed.

Enum documentation

enum class Corrade::Utility::FileWatcher::Flag: std::uint8_t new in 2019.10

Watch behavior flag.

Enumerators
IgnoreErrors

Don't abort the watch on errors. Useful if the watched file is being updated by deleting it first and then creating a new one.
IgnoreChangeIfEmpty

Don't signal a file change if it's currently empty. Useful if the watched file is being updated by first clearing its contents together with updating the modification time and then populating it without updating the modifcation time again.

Typedef documentation

typedef Containers::EnumSet<Flag> Corrade::Utility::FileWatcher::Flags new in 2019.10

Watch behavior flags.

Function documentation

Corrade::Utility::FileWatcher::FileWatcher(Containers::StringView filename, Flags flags = {}) explicit

Constructor.

Expects that the filename is in UTF-8. If it's already Containers::StringViewFlag::Global and NullTerminated, it's stored and passed to system APIs directly, otherwise a null-terminated copy is allocated first. On Windows the path is instead first converted to UTF-16 using Unicode::widen() and then passed to system APIs.

bool Corrade::Utility::FileWatcher::isValid() const

Whether the file watcher is valid.

Returns true if the watcher was valid the last time hasChanged() was called (or, if not called yet, on construction). For example, a file could get deleted in the meantime or a filesystem unmounted. Note that it's also possible for an invalid watch to become valid later, for example if the file under watch gets recreated again.

bool Corrade::Utility::FileWatcher::hasChanged()

Whether the file has changed.

Returns true if the file modification time was updated since the previous call, false otherwise.

Debug& operator<<(Debug& debug, FileWatcher::Flag value)

Debug output operator.

Debug& operator<<(Debug& debug, FileWatcher::Flags value)

Debug output operator.