Files
Tracked inputs
DynamicObjects.TrackedFile Type
TrackedFile(path; read=Base.read, version=:mtime)One file, observed rather than re-read.
read(file) returns read(path)'s result, memoized until the file changes. Pass read=JSON.parsefile (any path -> value) to track parsed content instead of bytes. version selects the change probe, run on every access:
:mtime— onestat; the stamp is the file's mtime, ctime, size and inode, so an in-place rewrite and an atomic replace (a new inode) both register;:hash— the hash of the file's bytes (reads the file; exact);:git— the file's git blob id, falling back to:hashwithout git.
A missing file is not an error: it stamps as absent, has a stable version, and starts producing changes when it appears. read on a missing file throws, as Base.read would.
There is no watcher: the probe runs when someone reads the file or asks for its tracked_version — sync! does, once per call.
DynamicObjects.TrackedDirectory Type
TrackedDirectory(path; match=Returns(true), key=path -> Symbol(basename(path)),
read=identity, version=:mtime)The entries of one directory, as an AbstractDict that observes membership and content as ONE version: an entry appearing, disappearing or changing all move tracked_version the same way, so a listing never disagrees with the contents.
match filters absolute entry paths (isdir selects subdirectories), key names each entry, and read turns a path into the value — the default identity yields the path. Values are memoized per entry and dropped only for entries that changed; a value that is itself a @dynamicstruct object (e.g. read = path -> Run(; path)) is reached by sync!, so tracked files inside it are observed too.
Each matched entry is probed like a TrackedFile. A subdirectory's :mtime stamp moves when an entry inside it is added, removed or renamed (an atomic write-and-rename included), not when a nested file is rewritten in place: track a nested file you rewrite in place with its own TrackedFile. A missing directory is empty, not an error. Keys iterate in sorted path order.
DynamicObjects.tracked_path Function
tracked_path(tracked) -> StringThe path a TrackedFile or TrackedDirectory observes. A different path is a different tracked value, not a mutation of this one.
DynamicObjects.tracked_paths Function
tracked_paths(dir::TrackedDirectory) -> DictEach key's path, for a consumer that needs the entry rather than its value.
sourceDynamicObjects.tracked_version Function
tracked_version(x) -> Union{UInt64,Nothing}Observable version of a TrackedFile or TrackedDirectory, or nothing for a value that is not tracked. Polls the filesystem first.
Monotone: any observed change produces a strictly greater number. Equal versions mean "nothing this value can see has changed"; the number is not comparable across values.
sourceDynamicObjects.file_version Function
file_version(path; by=:mtime) -> StringProbe a file's current state, for use as a @versioned field's value. This is the "DO derives the version" half of the file-backed pattern: compute it AT THE CALL SITE (no per-access I/O) and pass it to the constructor / remake at the mutation boundary. by trades cost against precision:
:mtime— modification time (onestat, cheapest; coarse: misses a content-preserving rewrite, and agit checkoutbumps mtimes).:hash— a stable hash of the file bytes (reads the whole file; exact).:git— the file's git blob id (git hash-object; exact, cheap for tracked files), falling back to:hashif git is unavailable.
Returns "" for a missing file, so a not-yet-created file has a stable version.
Change propagation
DynamicObjects.sync! Function
sync!(o) -> Vector{Symbol}Bring o's cache up to date with the tracked values it holds, and return the names of o's properties dropped (sorted).
Every fixed field and every already-computed property of o — including each settled entry of an indexed property — is examined:
a
TrackedFile/TrackedDirectoryis polled and itstracked_versioncompared with the one seen last time;a nested
@dynamicstructobject (directly, as an indexed-property entry, as aTrackedDirectoryvalue, or as an element of an array, tuple or dict) is synced first, and itsobject_versioncompared the same way.
Where a version moved, the transitive dependents of that property are dropped — memory, and the disk entry of a @cached / @mmap dependent — so the next read recomputes them. The changed slot itself is kept: it is the same container (or object) that observed the change. So is every input of o: a property o was constructed with a keyword for (T(root; mode = "kept"), or one remake kept) holds that value until o is rebuilt, even where its declared default reads the changed value, a child or a computed @versioned version; on a remount view, so is the context the view rebinds. The properties declared to read such an input still drop with the other dependents.
The children o holds — inline @struct children, and any object constructed with __parent__ = o held where sync! looks — drop what they read of a dropped or changed property of o, and what they derived from it. A child reads a parent property through a forwarded (bare) name, __parent__.name, __self__.__parent__.name or (; name) = __parent__; a forwarded copy still holding the very value o keeps stays. The child instance, its inputs and its @state are kept, and o drops what it derived from a child that dropped something in the same call. A dropped indexed property loses all its entries. A file changing under one entry of @struct run(id) = … drops only that child's own derived properties, plus whatever the parent derived from run. A @state property is never dropped, even when a fixed field its initializer read moved; what reads the state still drops when the state's own value observes a change.
On an object with a computed @versioned property, dropping anything also drops that property, what reads it (memory only) and the cache path, so the next read re-derives the version and publishes recomputed values under it; its children's cache paths, which extend it, move with it. A fixed @versioned field is kept: move it with remake.
A slot sync! has not stamped yet compares against the version its value had when it was first read, so a change between a dependent's computation and the first sync! is still a change.
Computes nothing: only values already in memory are examined, at the cost of one probe per tracked file plus a walk of the cached entries. Each object is synced once per call however many parents hold it; __parent__ back-references are not followed. On a remount view it syncs the retained object and then drops the view's own copies of the dropped names, and its child views' copies of what they read of them. sync! of a value that is not a @dynamicstruct object returns Symbol[]: it holds no property cache.
Call it where a host decides what to serve. HTMXObjects' root provider calls it on every request root. In-flight semantics follow invalidate!: a compute running when its entry is dropped stores nothing, and the next read recomputes.
DynamicObjects.notify_change! Function
notify_change!(tracked) -> UInt64Bump tracked's version and run its observers, returning the new version.
For a writer that knows it changed a file and does not want to rely on the probe — a rewrite that preserves size within one mtime tick, for instance. The next sync! drops everything derived from tracked, and a memoized read is dropped too, so the next read re-reads the file.
DynamicObjects.on_change! Function
on_change!(f, tracked) -> fRegister a zero-argument f to run after tracked changes — when a poll observes a change, or on notify_change!.
Runs outside the value's lock, so f may read the value. A throwing f is logged with its backtrace and skipped: the change already happened. Observers are never removed; register them once, at wiring time. This is the push counterpart to sync!'s poll, and it fires only when something polls.
DynamicObjects.object_version Function
object_version(o) -> UInt64Monotone count of the changes sync! has observed through o — a tracked value it holds moving, or a nested object it holds changing — and of the invalidations that dropped values of o (DynamicObjects.clear_cache!, clear_mem_caches!). The aggregate a holder watches: sync! stamps each child's version per holder, so a child shared by several parents reports its change to each, whenever each looks. A remount view reports its retained object's number. Eviction (prune_mem_caches!) does not move it.
DynamicObjects.dependents Function
dependents(T::Type, name::Symbol) -> Vector{Symbol}Every property of T whose value can change when name's does, transitively — the inverse of the dependson walk the macro runs on every property body. Exact for source-visible sibling reads; a value reached some other way (a global, or __self__ handed to foreign code) is invisible to it, exactly as for remake's carry-over. Sorted; excludes name itself.
Composite mmap formats
An extension implements DynamicObjects.save(Val(:mmap), path, value) and DynamicObjects.load(Val(:mmap), path, Type). Register a distinct leading magic with DynamicObjects.register_mmap_container!(magic::AbstractVector{UInt8}, loader) from the extension's __init__; loader(path) handles unannotated properties. DynamicObjects supplies the writer with an unpublished temporary path and publishes it atomically after save returns. The extension must close and validate its complete file before returning.
The stream overloads below let composite formats reuse numeric array blocks. Record each block's exclusive end and pass it as end_offset when loading so a corrupt header cannot map bytes from the next block.
DynamicObjects.save Function
DynamicObjects.save(Val(:mmap), io::IO, array::AbstractArray)Write a self-describing DOMM numeric array block at position(io) and leave io open at its end. Return the dense array written, without mutating the input. Supports the same numeric element types as the path overload, including empty and zero-dimensional arrays. Payload alignment is relative to the whole stream.
Composite mmap formats can record the starting and ending positions of each block and reuse load. This overload flushes and checks the block write; the enclosing format must also validate its complete file after closing its writer. When implementing save(Val(:mmap), path, container), DO supplies an unpublished temporary path and atomically publishes it only after save returns.
DynamicObjects.load Function
DynamicObjects.load(Val(:mmap), io::IOStream, annotation=nothing; end_offset=filesize(io))Read a DOMM numeric array block from position(io) and memory-map its payload. io must be a read-only file stream. Leave it open at the block's end; the array remains valid after the caller closes the stream. An optional array type checks the stored element type and number of dimensions; nothing reads them from the header. Only numeric DOMM blocks are supported by the stream overload.
Set end_offset to the exclusive end of an embedded block so a corrupt header cannot map bytes belonging to the next block. Header dimensions, byte-count overflow, file truncation and this enclosing boundary are checked before mapping.