API Reference

Everything exported by DynamicObjects. For usage and worked examples see the manual.

The struct macro

julia

@dynamicstruct [docstring] struct Name
    field                     # fixed field (constructor argument)
    prop = expr               # lazily computed property
    @cached prop = expr       # lazily computed + disk-cached property
    prop(idx) = expr          # indexable property (cached per args; `@fresh` to bypass)
    prop(args...; kw...) = expr  # indexable property (cached per args; `@fresh` to bypass)
    @cached prop(idx) = expr  # indexable + disk-cached property (cached per index)
end

Define a struct whose fixed fields are set at construction time and whose derived properties are computed lazily on first access and then stored in an in-memory cache.

Derived properties may reference any other field or property by name; the reference is automatically rewritten to __self__.<name>. Order of definition does not matter — cycles will result in a stack overflow at runtime.

The in-memory cache is always a ThreadsafeDict — safe to access from multiple tasks simultaneously; duplicate work is avoided by sharing in-flight Tasks.

Properties marked @cached are additionally persisted to disk under __self__.__cache_path__ (which itself defaults to joinpath(__self__.__cache_base__, __self__.__hash__)).

Keyword arguments passed to the constructor pre-populate the cache, so they act as overrides for any computed property.

Examples

julia

using DynamicObjects

@dynamicstruct struct Point
    x::Float64
    y::Float64
    r     = sqrt(x^2 + y^2)
    theta = atan(y, x)
end

p = Point(3.0, 4.0)
p.r      # 5.0
p.theta  # atan(4, 3)

julia

# Disk-cached expensive computation.
# cache_path defaults to joinpath("cache", hash(n)), so two Experiment(n)
# instances with the same n share the same cache directory.
@dynamicstruct struct Experiment
    n::Int
    @cached result = sum(rand(n))   # computed once, then loaded from disk
end

e = Experiment(1_000_000)
e.result   # computed on first access, cached to disk
e2 = Experiment(1_000_000)
e2.result  # loaded from disk (same n → same hash → same cache path)

julia

# Indexed properties. `obj.prop(args)` caches by default; `@fresh obj.prop(args)` recomputes.
# Properties reference each other by bare name (auto-rewritten to __self__.<name>).
@dynamicstruct struct DataSet
    items = ["apple", "banana", "cherry"]
    matches(query)   = filter(x -> occursin(query, x), items)   # call: cached per query
    top(query; n=1)  = first(matches(query), n)                 # call with kwargs
end

ds = DataSet()
ds.matches("an")        # ["banana"] — cached in the per-property dict (keyed by args)
@fresh ds.matches("an")  # ["banana"] — recomputed fresh, bypassing the cache
fresh(ds.matches, "an")  # ["banana"] — explicit uncached call (outside a @dynamicstruct body)
ds.top("a"; n=2)        # ["apple", "banana"] — kwargs supported

Async progress with __status__

Indexed properties spawn background Tasks, and progress is wired into them automatically: __status__ defaults to a Treebars.initialize_progress!(:state; description="") root, and the default __substatus__ hangs a child node under it per property compute. Declare __status__ only to label the root (an empty description makes it a structural node that renders nothing and hoists its children), or set it to nothing to switch progress off.

Like any x = y in a struct body, that declaration is an overrideable default: a constructor kwarg seeds the cache and wins. @include kid = Child() therefore mounts the child under the parent's tree whatever Child declares; pass @include kid = Child(; __status__ = nothing) to silence that subtree instead.

julia

@dynamicstruct struct MyApp
    __status__ = initialize_progress!(:state; description="MyApp")  # optional: labels the root
    results(key) = expensive_computation(__status__)  # __status__ is the substatus
end
app = MyApp()

# Non-blocking access with progress:
fetchindex(app.results, key) do rv, status
    rv isa Pending ? render_progress(status) : render_result(rv)
end

__substatus__ is called before each compute begins. name is the property symbol, args/kwargs are the indices. The returned object is stored in ThreadsafeDict.status (accessible via getstatus) and passed to the computation body as the local __status__.

__substatus__ fires on every generated-property compute — indexed (memoize!) and bare scalar (_bare_substatus_f) alike. It is skipped for dunder properties (__hash__, __status__, …) and for fixed struct fields, which have no body.

An undocumented property gets description="", i.e. a structural node that renders nothing and hoists its children; add a docstring to make it a labelled row in the tree.

Marker	Effect
`@cached prop = expr`	Persist to disk under `cache_path`. Per-key for indexed properties.
`@cached v"N" prop = expr`	Versioned disk cache; bumping `N` invalidates files without changing inputs.
`@persist prop = expr`	Write the in-memory value back to disk on demand (see `@persist`).
`@lru N prop(idx) = expr`	Bound the per-property in-memory dict to `N` entries (LRU eviction).
`@memo prop = expr`	Inside a struct: rewrite call → bracket access. Outside: process-wide function memoize.

API Reference ​

The struct macro ​

In-struct property markers ​

Cache inspection ​

Functions ​

Cache maintenance ​

Cancellation ​

Error handling ​

Persistent / bounded collections ​

Pluggable key tracking ​

API Reference

The struct macro

In-struct property markers

Cache inspection

Functions

Cache maintenance

Cancellation

Error handling

Persistent / bounded collections

Pluggable key tracking