Files
Refresh an object's file-backed values and invalidate their dependents with TrackedFile and sync!. Reading an ordinary path string does not establish this relationship; the dependency is the tracked value read by a property.
Tracked input
This object retains a tracked file and derives text from it. Hash-based versioning detects content changes even when file size is unchanged.
using DynamicObjects
directory = mktempdir()
path = joinpath(directory, "message.txt")
write(path, "first")
@dynamicstruct struct Message
path::String
source = TrackedFile(path; read = path -> read(path, String), version = :hash)
text = read(source)
uppercase_text = uppercase(text)
end
message = Message(path)
message.uppercase_text"FIRST"A subsequent property read reuses the cached text until the object is synchronized. sync! checks materialized tracked inputs, then drops their transitive derived values. It does not run every unmaterialized property.
write(path, "other")
before = message.uppercase_text
invalidated = sync!(message)
(before = before, after = message.uppercase_text,
dropped = sort(invalidated))(before = "FIRST", after = "OTHER", dropped = [:text, :uppercase_text])The output distinguishes an unchanged cache read from a read after synchronization. Use sync! at the boundary where your application intends to observe external changes, such as before rendering a refreshed view. A tracked file is not a background file watcher.
Directories
TrackedDirectory represents a collection of paths. Its match, key, and read functions choose which entries participate, how they are named, and how their values are loaded. A key should uniquely identify an entry.
write(joinpath(directory, "second.txt"), "second")
@dynamicstruct struct Library
path::String
files = TrackedDirectory(path;
match = path -> endswith(path, ".txt"), key = basename,
read = path -> read(path, String), version = :hash)
names = sort(collect(keys(files)))
end
library = Library(directory)
library.names2-element Vector{String}:
"message.txt"
"second.txt"Create, remove, or edit entries, then synchronize the holder before reading its derived listing. tracked_paths and tracked_version inspect the tracked value. notify_change! supports an application that already knows an input changed; on_change! registers change listeners.
Disk identity
Tracked inputs update a retained object's memory values. A disk cache also needs an identity that distinguishes file contents across object instances and processes. Declare a computed @versioned property with file_version when persisted outputs depend on a file.
@dynamicstruct struct StoredMessage
path::String
source = TrackedFile(path; read = path -> read(path, String), version = :hash)
@versioned content_version = file_version(path; by = :hash)
@cached text = read(source)
end
cache_directory = mktempdir()
first_object = StoredMessage(path; __cache_base__ = cache_directory)
first_text = first_object.text
first_cache = @cache_path first_object.text
write(path, "third")
second_object = StoredMessage(path; __cache_base__ = cache_directory)
(first_text = first_text, second_text = second_object.text,
different_disk_entry = first_cache != (@cache_path second_object.text))(first_text = "other", second_text = "third", different_disk_entry = true)A version marker applies to the object's persisted outputs. It does not replace sync! for an instance that is already retained. The default mtime version is less expensive to probe; hash mode reads the file contents. Choose the mode that matches how your input files change.
Cached signal analysis shows how to inspect the recomputation caused by invalidation before introducing external files.