Skip to content

Objects ​

Definitions and construction ​

DynamicObjects Module
julia
DynamicObjects

Define objects with lazily computed properties using @dynamicstruct. Scalar and indexed properties share dependency tracking, memory caching, and optional disk storage.

source
DynamicObjects.@dynamicstruct Macro
julia
@dynamicstruct struct Name ... end

Define a struct whose fields are constructor inputs and whose properties compute lazily. A declaration without = is a fixed field; name = expression is a scalar property; name(arguments...; keywords...) = expression is an indexed property. Property bodies may read sibling fields and properties by bare name. Constructor keywords override defaults and seed the instance cache.

Ordinary reads memoize. Indexed calls match argument values with isequal. Treat inputs, arguments and cached results as immutable; use remake for changed inputs and @clear_cache! for explicit invalidation.

Markers inside the struct body select additional behavior:

MarkerMeaning
@struct child = begin ... endNested object, with parent properties in scope.
@struct child(arguments...) = begin ... endNested object per argument tuple.
@cached [v"N"] name = expressionSerialized disk storage, optionally versioned.
@mmap name = expressionDisk storage using a supported memory-mapped format.
@fresh name(arguments...) = expressionUncached indexed computation.
@state name = expressionInstance state retained by memory clears and synchronization.
@versioned name = expressionObject-wide disk-cache version dimension.
@queued name(arguments...) = expressionIndexed work submitted through the job queue.
@options(parameter) = expressionDeclared domain for an input name.

An indexed declaration may take no arguments. Disk storage is independent of indexing and polling. Both scalar and indexed properties support polling via fetchproperty and fetchindex. Ordinary blocking reads compute inline unless an executor changes that policy; polling can start background work.

The default progress root is a Treebars node. Property docstrings label child nodes. Pass __status__ = nothing at construction to disable progress. __cache_base__ selects the disk-cache directory. Use __hash_fields__ only when the application needs an explicit content identity.

A state initializer may read fixed fields and other state properties only. It cannot combine with disk, fresh, version or queue markers. Reset state with @clear_cache!.

source
DynamicObjects.remake Function
julia
remake(object; changes...)

Construct a new object of the same type with replaced fields or property overrides. Settled scalar values whose declared dependencies are unaffected may be carried over. Changed inputs invalidate their transitive dependents. In-flight computations and indexed-property caches are not copied.

Constructor overrides remain inputs unless replaced. A scalar @state value is carried unless a fixed field its initializer reads changed. An opaque property that passes __self__ to uninspected code is carried only when no keyword changes were supplied.

The original object remains available. Pass new input values rather than mutating fields, arguments or cached outputs. Use remount to bind request context while sharing retained work instead of constructing a new value.

source
DynamicObjects.remount Function
julia
remount(obj; context...)

Return an immutable, same-type view of obj with fresh context properties while retaining the cache identity of unrelated model work. This is the request/job counterpart to remake: remake constructs a new value and copies only settled dependency-safe results, whereas remount keeps the retained cache's settled values, in-flight latches/Pending handles, mmap values, version identity, and indexed subcaches for every property proven independent of the rebound context.

The keyword names are existing non-fixed properties such as __parent__, __req__, or __prefix__. They, every transitive dependent in meta(T), progress state, and nested child are routed to a fresh mount-local cache. Each mounted IndexableProperty wrapper is recreated with the mounted owner; its per-argument cache is shared only when the property is context-independent. Context-dependent @cached/@mmap properties bypass their intrinsic disk entry because the rebound context is intentionally not part of the retained disk identity.

A keyword obj was constructed with is an input, not a computed value, and a view keeps it: remount(T(; a=0.4); ctx=1).a is 0.4, also when the declared default of a reads ctx, hands __self__ to other code, copies a parent property or builds a nested child. A name the call rebinds takes the rebound value, and the request-scoped __status__, __req__ and __prefix__ are always the view's own. A kept keyword cuts the dependency on its declared default: if b = 10a and the retained object was constructed with a=0.4, the object and its views share b. A view that rebinds a computes its own b.

What reads a nested child is decided by the read. Reading a member of a memoized inline @struct child, pins.ap3, makes a property per view only when that member reaches rebound context, directly, through a forwarded parent name, or through a nested child; otherwise the property is shared like any other. Holding the child itself (f(pins)) is per view, because the instance holds its view, and so is reading an opaque member.

An opaque property — one that hands a bare __self__ to code the dependency scan cannot follow, such as fit(key) = run(__self__, key) — and its dependents are decided by what they actually read. Views that rebind the same context names share one computation of each such key, including an in-flight one, so a poll from a later view awaits the first view's work. That computation receives a guarded __self__: reading rebound context through it (or anything derived from that context) makes the key context-dependent, so the requesting view keeps the value it computed and every other view, now and later, computes the key itself. A shared value that retained its __self__ cannot read request context through it afterwards (RemountSharedContextError). The retained object's own computations stay separate from its views'.

A nested child instance is view-local because it holds its parent, but its own cache is shared: the view's child is the retained source's child remounted onto the view. A memoized inline @struct child read first through a view is realized on the retained source, so later views reuse it and its settled and in-flight work; a @fresh child stays a fresh view-local child per call. An external @include child is what its constructor call builds under the view: the view runs that call on first access and reuses the retained source's settled child only when both calls passed the same arguments (the parent and request-scoped __status__, __req__ and __prefix__ aside), so a constructor argument derived from rebound context gives the view its own child. Inside the remounted child, a __parent__.<name> alias (every bare parent name an inline child reads) of a parent property the view shares is still shared, so child work built on context-independent parent state is reused too.

Fixed fields, @versioned properties, and cache/hash/path dunders are rejected: changing any of those means the object identity changed, so use remake.

source

Access policy ​

DynamicObjects.@fresh Macro
julia
@fresh expression

Rewrite calls in expression through maybefresh. An indexed property computes without reading or writing its cache; other callables are called normally. Quoted code is left unchanged. This does not recursively bypass the caches of dependencies read inside the selected property's body.

A declaration marked @fresh uses uncached access on every call. The function form fresh selects one indexed property explicitly.

source
DynamicObjects.fresh Function
julia
fresh(ip::IndexableProperty, args...; kwargs...)

Uncached call into an IndexableProperty: computes the value fresh on every call, never reading or writing the per-key cache. This is the public, exported opt-out from the now-default memoized call form — the mirror of memoize!.

The bare call form o.prop(args...; kwargs...) caches by default; use fresh(o.prop, args...; kwargs...) (or the call-site macro @fresh) when you specifically need to recompute and bypass the cache entirely (no read, no store).

source
DynamicObjects.@memo! Macro
julia
@memo! expression

Rewrite calls in expression through maybememoize!: indexed properties use their memoized path and other callables keep ordinary call behavior. This is redundant for ordinary indexed calls, which already memoize. Quoted code is left unchanged. Use @fresh to bypass the selected cache.

source
DynamicObjects.memoize! Function
julia
memoize!(ip::IndexableProperty, args...; kwargs...)

Cached call into an IndexableProperty's per-key dict. Returns the cached value if (args, kwargs) was seen before; otherwise computes the value (via _computeproperty), stores the result, and returns it.

Calls share an entry when their arguments are isequal. A mutable argument is content-hashed once per object and remembered by identity, so repeated calls passing the same large container do not re-hash it; never mutate an argument after passing it.

The bare call form o.prop(args...; kwargs...) now routes through memoize! (caching by default), so memoize! is the explicit, exported equivalent of a bare indexed-property call — and the form to use whenever you'd previously have written ip[args...], especially in kwargs-only call sites (memoize!(ip; k=v)) which the legacy bracket syntax couldn't express at all (ip[; k=v] doesn't parse as Julia). For the uncached (fresh) call, use fresh / @fresh.

For two-phase access (returning a Pending handle while computing) on ThreadsafeDict-backed IPs, see fetchindex. Inside a @dynamicstruct body, the convenience macro @memo! wraps every call-site in maybememoize!(callee, args...; kwargs...) so cached IPs and plain functions can share the same syntax.

source
DynamicObjects.maybememoize! Function
julia
maybememoize!(f, args...; kwargs...)

Dispatch helper used by @memo!. The default just calls f(args...; kwargs...), so non-IP callees (functions, types, callable structs) behave like normal calls. The specialization for IndexableProperty routes through memoize!, hitting the in-memory cache.

source
DynamicObjects.maybefresh Function
julia
maybefresh(f, args...; kwargs...)

Dispatch helper used by @fresh. The default just calls f(args...; kwargs...), so non-IP callees (functions, types, callable structs) behave like normal calls. The specialization for IndexableProperty routes through fresh — the uncached call — so the indexed property is recomputed and the cache is bypassed. The dual of maybememoize!.

source

Errors ​

DynamicObjects.PropertyComputationError Type
julia
PropertyComputationError <: Exception

Wraps an error that occurred during lazy property computation, adding context about which property failed (property name, type, indices/kwargs). The original exception and backtrace are stored in the cause field.

source
DynamicObjects.unwrap_error Function
julia
unwrap_error(e)

Recursively unwrap TaskFailedException, CompositeException, and PropertyComputationError wrappers to find the root cause exception. For a computation that ran in a worker process (configure_queue!(; workers=1)) that is the worker's exception itself, of its type and with its fields. An exception that could not cross returns a DynamicObjects.RemoteComputationError holding the worker's printout, which says why.

source
DynamicObjects.RemountSharedContextError Type
julia
RemountSharedContextError(property, context)

Thrown when request context context is read through the __self__ that a remount-shared opaque property retained after it finished computing. The property read no request context while computing, so its value is shared by every remount view; the retained __self__ belongs to no request.

source