Skip to content

Files ​

Tracked inputs ​

DynamicObjects.TrackedFile Type
julia
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 — one stat; 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 :hash without 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.

source
DynamicObjects.TrackedDirectory Type
julia
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.

source
DynamicObjects.tracked_path Function
julia
tracked_path(tracked) -> String

The path a TrackedFile or TrackedDirectory observes. A different path is a different tracked value, not a mutation of this one.

source
DynamicObjects.tracked_paths Function
julia
tracked_paths(dir::TrackedDirectory) -> Dict

Each key's path, for a consumer that needs the entry rather than its value.

source
DynamicObjects.tracked_version Function
julia
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.

source
DynamicObjects.file_version Function
julia
file_version(path; by=:mtime) -> String

Probe 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 (one stat, cheapest; coarse: misses a content-preserving rewrite, and a git checkout bumps 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 :hash if git is unavailable.

Returns "" for a missing file, so a not-yet-created file has a stable version.

source

Change propagation ​

DynamicObjects.sync! Function
julia
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 / TrackedDirectory is polled and its tracked_version compared with the one seen last time;

  • a nested @dynamicstruct object (directly, as an indexed-property entry, as a TrackedDirectory value, or as an element of an array, tuple or dict) is synced first, and its object_version compared 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.

source
DynamicObjects.notify_change! Function
julia
notify_change!(tracked) -> UInt64

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

source
DynamicObjects.on_change! Function
julia
on_change!(f, tracked) -> f

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

source
DynamicObjects.object_version Function
julia
object_version(o) -> UInt64

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

source
DynamicObjects.dependents Function
julia
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.

source

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

source
DynamicObjects.load Function
julia
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.

source