Skip to content

Caches ​

Inspection ​

DynamicObjects.@cache_status Macro
julia
@cache_status object.property
@cache_status object.property(arguments...)

Report the disk entry's state: :unstarted, :started, or :ready. Use a call expression for one indexed entry and a dot expression for a scalar. This inspects disk state, not the in-memory memo table. Inside a @dynamicstruct body the object prefix may be omitted.

source
DynamicObjects.@is_cached Macro
julia
@is_cached object.property
@is_cached object.property(arguments...)

Return whether the selected disk entry is ready, equivalent to comparing @cache_status with :ready. This is not a test for an in-memory hit. Inside a @dynamicstruct body the object prefix may be omitted.

source
DynamicObjects.@cache_path Macro
julia
@cache_path object.property
@cache_path object.property(arguments...)

Return the selected property's disk-cache path without computing its value. An indexed call selects one argument tuple. The path depends on the object's identity and version. Inside a @dynamicstruct body the object prefix may be omitted.

source
DynamicObjects.entries Function
julia
entries(ip::IndexableProperty)

Return a vector of (; key, state, status, value) for all entries in a ThreadsafeDict-backed IndexableProperty. state is one of :running, :failed, or :done. value is the cached result (for :done), a Pending handle (for :running), or the captured exception (for :failed). status is the substatus object or nothing.

source
DynamicObjects.cached_entries Function
julia
cached_entries(ip::IndexableProperty)

Return a vector of (key, value) pairs for completed entries only.

source
DynamicObjects.mem_cache_entries Function
julia
mem_cache_entries(root)

Iterate the settled in-memory cache entries of root and of every @dynamicstruct object it derived, without computing anything. Each element is a DynamicObjects.MemCacheEntry (; object, property, key, value, path, role):

  • object: the object holding the entry, property its property name, value the memoized value;

  • key: nothing for a bare property, (args, kwargs) for an indexed-property entry (as cached_entries reports it);

  • path: how the walk reached object from root, one (property, key) step per entry that held the next object; () for root's own entries;

  • role, what the entry is to its object:

    • :derived: a memoized derivation, which prune_mem_caches! may evict;

    • :input: a constructor input (__parent__ wiring, an inline child's index arguments, a constructor or remake override, a remount view's request context);

    • :state: an @state value;

    • :internal: DO's own __…__ entries (progress root, hash, cache path, @options domains, …) and computed @versioned properties, from which the disk cache path derives.

An indexed property is listed entry by entry, never as its wrapper.

Which objects are walked: root, then every @dynamicstruct object held by a :derived or :state entry, recursively. An entry holds an object directly, as a memoized TrackedDirectory value, or as an element of an array, tuple or dict (one level; deep data is never walked). Constructor inputs and fixed fields are not followed, so neither __parent__ back-references nor objects an object was merely given are walked. Each object is listed once, so aliases and cycles terminate. root's own entries come first, then breadth-first.

A remount view lists its own entries and walks its retained object, which also lists the opaque work its views share.

The walk is lazy: each object's entries are read under that object's cache lock when the walk reaches it, so first, Iterators.take or a break stop it early. A computation in flight is not an entry.

source
DynamicObjects.memo_retention_stats Function
julia
memo_retention_stats()
memo_retention_stats(queue)

Report this process's heap hint, Julia's current live-heap estimate, the process-memory budget and current footprint (nothing when unavailable), and cumulative automatic memo releases in the disk and memory tiers. estimated_payload_bytes counts shallow payloads dropped from slots and mapped_payload_bytes counts known explicit mappings separately. Aliases can contribute to several slots and other owners may still hold the value. estimated_native_bytes sums producer estimates, and unknown_native_slots counts released native results for which the producer supplied no estimate. For a queue configured with zero or one worker, the result is (; requester, worker). worker is nothing when the process is absent. For a pool, the result is (; requester, workers) with a snapshot per configured slot, in slot order. A slot without a live process contains nothing. Reading statistics leaves idle workers idle.

source
DynamicObjects.memo_native_bytes Function
julia
DynamicObjects.memo_native_bytes(owner_type, ::Val{property}, value::T)
DynamicObjects.memo_native_bytes(value::T)

Declare that a native result can be rebuilt after its cache slot is released. Return an estimated native byte count (a nonnegative Int), or missing when the size is unknown. The default nothing preserves native-handle pinning.

The three-argument method declares one property: specialize on the owner type, the property and the result type T. The one-argument method declares a type that your package owns, for every property that returns it in any owner, inline @struct children included. A property declaration takes precedence over the declaration of its result type, also when it returns nothing.

A property without either declaration that returns the same mutable object as a declared slot is released with that object's estimate. A kept copy would retain the resource while a later read of its producer builds a second one.

The method runs at publication and should only inspect the result. The producer is responsible for replaying the correct inputs, including any seed or file. A disk-cached producer must also support restoring a valid live resource. DynamicObjects drops its reference and leaves resource finalization to the owner.

source
DynamicObjects.MemCacheEntry Type
julia
DynamicObjects.MemCacheEntry

The element type of mem_cache_entries: a NamedTuple (; object, property, key, value, path, role).

source

Invalidation ​

DynamicObjects.@clear_cache! Macro
julia
@clear_cache! object.property
@clear_cache! object.property(arguments...)

The dot form clears the whole property and its transitive declared dependents, including memory values and disk files. The call form clears only the selected indexed entry, as invalidate! does. Inside a @dynamicstruct body the object prefix may be omitted.

A clear retracts in-flight entries without cancelling their running bodies. Their original callers may still receive a result, but those computations cannot publish into the cleared cache; waiters resolve against the current entry. Clearing an indexed property retains its wrapper and empties its subcache in place.

An explicit whole-property clear also resets state or constructor-seeded values for that property. By contrast, clear_mem_caches! retains instance state and restores constructor inputs. Use prune_mem_caches! for memory reclamation that does not invalidate dependents.

source
DynamicObjects.clear_cache! Function
julia
DynamicObjects.clear_cache!(o, name::Symbol) -> Vector{Symbol}
DynamicObjects.clear_cache!(o, name::Symbol, indices...; kwargs...)

The function behind @clear_cache!, for a property name only known at run time (DynamicObjects.clear_cache!(prep, stage_root)). Not exported.

With a name alone it drops the whole property and everything derived from it: name and its transitive dependents — the memory value (every entry of an indexed property), every disk entry of a @cached / @mmap one (including entries an earlier process wrote), and shared remount work — so the next read of any of them recomputes. Every other property keeps its value. Returns the names that held a value in memory or on disk, sorted.

With indices or kwargs it drops exactly that one entry, as invalidate! does, and returns nothing.

source
DynamicObjects.invalidate! Function
julia
invalidate!(ip::IndexableProperty, indices...; kwargs...)

Drop exactly one indexed-property cache entry — the in-memory value (plus any in-flight latch, recorded error, and status node) and the on-disk payload (@cached / @mmap / auto-materialized) — for the key (indices, (;kwargs...)). Sibling entries are untouched. The next access recomputes and re-caches.

This is the same primitive fetchindex(...; force=true) runs before recomputing, also reachable as @clear_cache! obj.prop(indices...).

In-flight semantics (there is no cancellation — DynamicObjects retains no compute handle): invalidating while a compute runs does not stop it, and its caller gets its value. But the value may derive from what was invalidated, so the compute stores nothing — no memory value, no @cached/@mmap entry, no automatic entry. Blocking waiters and a Pending handle taken before re-resolve: they wait for a compute started since, or start one. They do so at the invalidation, not when the invalidated compute ends, so one that never finishes holds up nobody but its own caller. So a re-access after invalidate!, and force=true, always serve a post-invalidation value. This holds wherever the invalidation is issued from, including the body of a computation of the same object.

source
julia
invalidate!(c::BackgroundCache, key)

Drop the settled value (and any failure/backoff record) for key; the next read serves the cache's unbuilt value and kicks a fresh background build. A refresh already in flight is not stopped — its value still lands.

source
DynamicObjects.clear_mem_caches! Function
julia
clear_mem_caches!(object)

Remove derived in-memory values while keeping disk files, constructor inputs, and settled or in-flight @state values. A later read recomputes a derived value or reloads its disk entry. Constructor overrides and mounted request context are restored, so clearing does not change the object's inputs.

Indexed wrappers remain attached and their subcaches are emptied in place. Held handles and remount views therefore observe subsequent computations and clears. Derived child objects are dropped and recreated on demand.

Dropping derived values advances the object's version. Holders invalidate what they derived from it on their next sync!. To free memory without that invalidation, use prune_mem_caches!.

In-flight computations that were retracted cannot publish a value; their original callers may still receive it and waiters resolve against the current entry. The progress root is also dropped unless supplied as a constructor input. Inside a computation, prefer a narrower property clear or sync!.

source
DynamicObjects.clear_disk_caches! Function
julia
clear_disk_caches!(obj)

Delete all on-disk cache files for @cached properties on a @dynamicstruct instance. In-memory values are left intact (they'll be stale until clear_mem_caches! is also called, or until the process restarts).

source
DynamicObjects.clear_all_caches! Function
julia
clear_all_caches!(obj)

Clear all @cached properties on a @dynamicstruct instance — both in-memory and on disk. Equivalent to clear_mem_caches! + clear_disk_caches!.

source
DynamicObjects.prune_mem_caches! Function
julia
prune_mem_caches!(keep, root) -> (objects, kept, evicted)

Walk already materialized memory entries and evict derived entries for which keep(entry) is false. The entry record is the same as in mem_cache_entries. Inputs, state, progress roots and in-flight work are kept. The traversal computes nothing and does not force disk or lazy loads.

Eviction leaves disk files and dependency versions unchanged: this is memory reclamation, not semantic invalidation. Values may still be referenced elsewhere, so eviction does not guarantee an immediate reduction in process memory. Removing an indexed value leaves its wrapper attached. Use @clear_cache! when dependents must also be invalidated.

source
DynamicObjects.prune_worker_mem_caches! Function
julia
prune_worker_mem_caches!(keep, root; queue=DynamicObjects.job_queue())

Prune each live worker's copy of root and return the summed counts (; objects, kept, evicted). A stopped worker or absent root returns zero counts. This never starts a worker or builds the object. The predicate travels to the worker and executes there; use a callable available in its environment, such as Returns(false) or an application package function. Predicate and transport failures are reported to the caller. To prune the calling process as well, call prune_mem_caches! there.

source

Scoped computations ​

DynamicObjects.with_compute_scope Function
julia
with_compute_scope(f)

Run f() and return its result. Newly memoized derived values are shared across its reads, including joined tasks and queued worker computations. On return or exception, release this scope's entries in each process. Other open scopes keep entries they have read until their own last use. A reader outside a scope adopts an entry into the ordinary cache. Pre-existing cache entries, inputs, state, disk files and the values returned to callers keep their usual lifetime.

Use one scope around targets which might reuse a result, such as the table and figure in a report. A nested scope marks a known earlier last use. Join tasks and fetch pending targets inside their scope to include their whole computation. An unfinished computation continues and can still deliver its result.

source
DynamicObjects.compute_targets Function
julia
compute_targets(root, targets)

Compute the given properties in order and return their values in a vector. Use a symbol for a bare property or a named tuple such as (; property=:fit, args=(2,), kwargs=(; draws=500)) for an indexed call.

This form knows the remaining targets. For simple, declared sibling reads it releases derived entries at their last possible target. An arbitrary Julia call or an unresolved dependency can read other entries, so such a target keeps earlier results available through its execution. Indexed keys of the same declaration are treated conservatively. For a dynamic set of requests or application callbacks use with_compute_scope.

source

Persistence ​

DynamicObjects.@persist Macro
julia
@persist o.prop
@persist o.prop(indices...)

Write the in-memory value of o.prop (or the indexed entry o.prop(indices...)) back to its disk cache. Use after mutating a value in place when the property was declared with @cached and the on-disk copy is now stale relative to the in-memory copy.

The legacy bracket form (@persist o.prop[indices...]) still works but is discouraged in new code — prefer call syntax.

source
DynamicObjects.PersistentSet Type
julia
PersistentSet(path)

A thread-safe Set that persists to disk via Serialization. Loads existing data from path on construction, or starts empty if the file doesn't exist.

source
DynamicObjects.LazyPersistentDict Type
julia
LazyPersistentDict{D<:AbstractDict}(path[, empty_data]; seed!)

Threadsafe dict backed by Serialization.serialize/deserialize. The backing file path is resolved lazily via a callable path so the constructor itself is precompile-safe (no mkpath, no file I/O). The on-disk file is loaded on the first operation (double-checked under the lock), and the optional seed!(data) callback runs once after load if the dict is empty. Mutations persist to disk synchronously under the lock.

path may be an AbstractString (fixed path) or a 0-arg function returning a String. Pass an ordered backing dict (e.g. OrderedDict{K,V}()) to preserve insertion order.

source
DynamicObjects.canonical_hash Function
julia
DynamicObjects.canonical_hash(x)::String

The content digest DynamicObjects uses for cache identity: a SHA-1 hex string of x, serialized after supported nested @dynamicstruct values are replaced by their own __hash__ (and, with DataFrames and Arrow loaded, every DataFrame by its column names and columns). It names an object's cache directory and keys its disk-cache entries, so equal content gives the same digest in every process, however much an object has memoized.

Every default __hash__ is canonical_hash((typeof(o), o.__hash_fields__)), and the default __hash_fields__ is what the object was constructed from: its fixed fields, plus (as a trailing NamedTuple) the constructor keywords its properties read — the __parent__ it is mounted under and overrides of computed defaults. To choose what an object's identity covers, override __hash_fields__; to also mix in constants such as a cache-format version, override __hash__ through canonical_hash:

julia
@dynamicstruct struct Draws
    stan_code
    draws
    stripped_code = replace(stan_code, r"\s+" => "")
    __hash__ = DynamicObjects.canonical_hash((typeof(__self__), REPLAY_VERSION, (stripped_code, draws)))
end

Replacement recurses through Tuple, NamedTuple, Pair, dense Array, Dict and Set. Dict entries and Set elements are order-independent; their concrete types and scalar value types remain part of identity. Other containers, array wrappers and arbitrary structs are serialized as written; sparse or lazy arrays are never densified here. Repeated references are retained, so alias structure can affect a digest. Order-independent hashing of cyclic container graphs is not promised.

A digest is the same on every Julia version from 1.10 on: on 1.10 it is the digest DynamicObjects computed before it made this promise, and later Julia versions compute that same digest (see CHANGELOG.md). This holds for strings, numbers, symbols, chars, nothing, missing, arrays, ranges, tuples, named tuples, pairs, Dicts, Sets, types, structs defined in packages, @dynamicstruct objects and DataFrames, and for containers of these. Two kinds of value are excluded: anonymous functions and closures, whose serialized form holds their code, and a Dict or Set inside a value that is serialized as written (an arbitrary struct, an array wrapper), because its iteration order changed in Julia 1.13.

Since 0.5.9, identities containing Dicts/Sets or newly replaced nested values change once: their old disk entries miss and remain on disk until explicitly cleared. Plain scalar and numeric array values keep their existing digests. This also lets a worker reconstruct a Dict-bearing object and publish at the same cache path its requester reads.

source

Key tracking ​

DynamicObjects.KeyTracker Type
julia
KeyTracker

Abstract type for pluggable accessed-keys persistence strategies. Implement record!(tracker, key) and load_keys(tracker) for custom strategies.

Override key_tracker(o, ::Val{name}) on your object type to select a strategy.

source
DynamicObjects.SharedFileTracker Type
julia
SharedFileTracker(path)

Default strategy: all pods/processes share a single _keys.sjl file. Simple, but not safe for concurrent multi-process writes to NFS.

source
DynamicObjects.NoKeyTracker Type
julia
NoKeyTracker()

No-op strategy: never records or loads keys. Use when tracking is unwanted.

source
DynamicObjects.key_tracker Function
julia
key_tracker(object, ::Val{property}) -> KeyTracker

Select the strategy for explicitly recorded disk-cache keys. The default is SharedFileTracker at the property's _keys.sjl path. Override this method for an object type and property to return NoKeyTracker or a custom tracker. Automatic property access does not currently record keys; record! remains available for explicit recording.

source
DynamicObjects.record! Function
julia
record!(tracker::KeyTracker, key)

Record that key was accessed, persisting according to the tracker's strategy.

source
DynamicObjects.load_keys Function
julia
load_keys(tracker::KeyTracker) -> Set

Load the full set of recorded keys according to the tracker's strategy.

source

Refresh ​

DynamicObjects.BackgroundCache Type
julia
BackgroundCache{K,V}(build; ttl, unbuilt, maxsize=0, backoff_base=1.0, backoff_max=60.0, on_settle=(key, old, new) -> nothing)
BackgroundCache{K,V}(build_many; batch, ttl, unbuilt, maxsize=0, backoff_base=1.0, backoff_max=60.0, on_settle=(key, old, new) -> nothing)

Keyed stale-while-revalidate cache.

Reads (c[key]) never block and never throw for cache reasons:

  • a fresh value (settled less than ttl seconds ago) is returned as is;

  • a stale value is returned immediately while a background refresh is kicked off — at most one refresh per key is ever in flight, so concurrent readers of a stale key share it;

  • a key with no settled value reads as unbuilt (declared at construction — there is no default) while its first build runs in the background.

A refresh that throws keeps the previous value (or unbuilt), logs an error with a backtrace, and gates the key behind an exponential backoff (backoff_base * 2^(n-1) seconds after the nth consecutive failure, capped at backoff_max): reads during the gate serve the old value without kicking another refresh. A success clears the failure count.

With maxsize > 0 the cache holds at most maxsize settled entries; storing past the bound evicts settled keys with the oldest settle time first (an O(n) scan — this is a small policy cache, not a store). ttl=Inf never goes stale; ttl=0 revalidates on every idle read.

By default build(key)::V builds one key per background task. Pass batch=N (a positive integer) to refresh up to N wanted keys with one call instead: the first positional argument is then build_many(keys::Vector{K})::AbstractDict, one background drain task per cache feeds it batches of at most N keys, and each key in a batch settles (or fails with backoff) individually. A thrown batch call fails every key in that batch; a key missing from the returned dict — or holding a value that is not a V — fails that key alone while present keys still settle. Extra keys in the result are ignored.

After each successful store — once per settled key in batch mode too — the cache invokes on_settle(key, old, new) outside the lock, so a re-entrant read inside the callback observes the new value. old is the previously settled value, or unbuilt when the key had none (first build, post-invalidate!, or eviction). Failures never invoke it. It fires even when new == old — compare them to skip unchanged values. A throwing callback is logged with its key and backtrace and never breaks the refresh or the drain. The refresh stays in flight until the callback returns: reads of that key meanwhile, the callback's own included, serve the new value without kicking another refresh, even at ttl=0. Callbacks for one key therefore never overlap.

Every background refresh task, and the batch drain before each claim, yields to the scheduler, so a refresh storm (say, other tasks that re-request each key as it settles at ttl=0) wastes builds but never starves the other tasks, timers or I/O on its thread.

Timestamps use the monotonic clock. Treat returned values (including unbuilt) as read-only, and likewise the old/new values handed to on_settle. See also invalidate!.

source