Skip to content

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.

julia
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.

julia
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.

julia
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.names
2-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.

julia
@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.