Execution
The polling and progress guide introduces nonblocking reads and queued work. Queue and worker controls use the DynamicObjects. prefix.
Polling
DynamicObjects.Pending Type
PendingCheap, non-Task handle a poller (fetchindex / fetchproperty / get!(…; fetch=identity)) gets back while a value is still being computed. It points at where the value will land — a Slot (bare props) or the backing (cache, key) — plus the in-flight latch, so a caller can fetch(p) to BLOCK for the value (rethrowing if the compute failed) or ignore it and poll again later. Replaces the former "rv is a Task while in-flight" poll contract: callers now branch on rv isa Pending (still computing) vs. the value (done). The progress/status node stays optional and is never relied on for readiness.
A handle for a computation started through an executor (a Deferred selector, or the property's DynamicObjects.property_executor) carries that executor, and a blocking fetch on it waits through DynamicObjects.await_deferred.
If the computation is invalidated while in flight (clear_mem_caches!, clear_cache!, sync!, invalidate!, force=true), its value is not stored, and fetch re-resolves the access: it waits for a computation started since, or starts one. A fetch already waiting re-resolves at the invalidation, not when the invalidated computation ends.
DynamicObjects.fetchindex Function
fetchindex(callback, ip, indices...; force=false, retry_failed=force, kwargs...)Request an indexed property without blocking. The callback receives (result, status): result is a Pending handle while work is in flight, or the completed value; status is its progress node or nothing. Calling fetch on the handle blocks and rethrows a computation failure.
force=true first calls invalidate! for the requested entry, removing its memory and disk value. See that function for in-flight behavior.
DynamicObjects.fetchindex! Function
fetchindex!(callback, ip, indices...; fetch=Base.fetch, kwargs...)In-place variant of fetchindex. When callback is nothing, falls through to a plain memoize!(ip, indices...; fetch, kwargs...) — useful for sites that opt out of the two-phase fetch dance without changing call shape.
When callback is a Treebars.ProgressNode, the call blocks for the value. It computes inline on the caller's task, as a plain call does, and attaches the computation's node under callback, where it stays once finished; a documented cache hit attaches the entry's node noted "(cached)". With fetch=identity it polls instead and returns a Pending while the computation runs. fetchproperty! with a progress node is the blocking form for a bare property; @fetch! and @progress thread their reads through both.
DynamicObjects.fetchproperty Function
fetchproperty(fetch, o, name::Symbol)Like fetchindex but for bare (non-indexed) properties. Triggers computation via the PropertyCache and calls fetch(rv, status) where rv is a Pending handle (the compute is still in flight — fetch it to block for the value) or the already-computed result, and status is the substatus object or nothing.
For Dict-backed caches (serial), falls through to getproperty (synchronous, no status). The two-phase dance only applies to ThreadsafeDict-backed caches.
DynamicObjects.fetchproperty! Function
fetchproperty!(callback, o, name::Symbol)In-place variant of fetchproperty. When callback is nothing, falls through to getproperty(o, name).
DynamicObjects.maybefetchindex! Function
maybefetchindex!(progress, f, args...; kwargs...)Dispatch helper used by @fetch! for call sites. The default just calls f(args...; kwargs...); the specialization for IndexableProperty preserves the property's declaration-site cache policy while attaching progress: ordinary properties route through fetchindex! (memoized + progress), while @fresh properties route through maybeprogress! (fresh + progress, with no cache read or write).
DynamicObjects.maybefetchproperty! Function
maybefetchproperty!(progress, o, name::Symbol)Dispatch helper used by @fetch! for property accesses. For @dynamicstruct instances, routes through fetchproperty! (cached + progress-tree attachment). For indexed properties (IPs) and non-DO objects, falls through to getproperty(o, name).
Progress
DynamicObjects.getstatus Function
getstatus(ip::IndexableProperty, indices...; kwargs...)Return the status object associated with an in-flight computation for the given key, or nothing if no status exists (computation not started, already finished, or no __substatus__ defined).
Only meaningful for IndexableProperty backed by a ThreadsafeDict.
DynamicObjects.@fetch! Macro
@fetch! progress expressionThread property reads in expression through the progress-aware fetch helpers. Indexed reads use fetchindex!, scalar reads use fetchproperty!, and declaration-marked fresh properties retain their uncached policy through maybeprogress!. Non-property functions keep their ordinary call behavior.
With a Treebars progress node these reads block and attach the computation's node beneath it. With nothing they use the ordinary access path. Property bodies already attach their source-visible reads automatically.
DynamicObjects.@dynamic_progress Macro
@dynamic_progress progress_var bodyRewrite every :call inside body as maybeprogress!(progress_var, callee, args…). Returns the rewritten body unchanged otherwise. The caller is responsible for binding progress_var — e.g. via Treebars.@progress progress_var body — and for keeping DO free of a hard Treebars dependency.
maybeprogress! dispatches on progress_var's runtime type: a Treebars.ProgressNode (when the caller has wrapped in Tb.@progress) opens per-call substatuses; noprogress opts out; anything else collapses to a plain f(args…). The macro itself doesn't care which.
In @dynamicstruct, a property marker @dynamic_progress lowers to
prop() = @dynamic_progress __status__ bodywhere __status__ is the IP caller's bound progress context (or nothing).
Standalone:
Treebars.@progress my_status begin
@dynamic_progress my_status begin
a = foo(x) # → maybeprogress!(my_status, foo, x)
b = @memo! bar(y) # cached + progress (see `maybememoize!`)
a + b
end
endDynamicObjects.maybeprogress! Function
maybeprogress!(progress, callee, args…; kwargs...)Runtime dispatch arm for @dynamic_progress-rewritten call sites. The rewriter wraps every call as maybeprogress!(__progress__, callee, args…), where __progress__ resolves to the current Treebars progress context (the enclosing IP's __status__ at top level; a nested @progress block re-binds it to that block's node). Dispatch on callee:
callee::IndexableProperty— open a per-call substatus rooted atprogress, run the IP body inside it (no caching).callee::typeof(noprogress)— opt-out, calls through (noprogress(f, args…)).anything else — plain
callee(args…; kwargs…).
The caching stack — @memo! foo(x) inside a @dynamic_progress body — lands at maybememoize!(maybeprogress!, progress, callee, args…) after natural macro expansion order, and is handled by the corresponding maybememoize! dispatch arms (see above).
progress === nothing is fine throughout — the _default_substatus / fetchindex! paths have explicit ::Nothing fallbacks.
DynamicObjects.noprogress Function
noprogress(f, args...; kwargs...)Opt out of dynamic progress wrapping at a specific call site. Inside an IP body annotated with @dynamic_progress, every call is rewritten to maybeprogress!(__progress__, callee, args…). Writing noprogress(f, args…) makes the rewriter emit maybeprogress!(__progress__, noprogress, f, args…), which dispatches to a method that just runs f(args…) without any progress attachment.
Note the argument shape: noprogress(f, args…) (comma-separated callee and its args), not noprogress(f(args…)) — the latter would still wrap f(args…) under the body-wide rewrite before noprogress ever sees it.
Outside a @dynamic_progress body, noprogress(f, args…) is just f(args…).
DynamicObjects.progress_notes Constant
DynamicObjects.progress_notesThe words DynamicObjects writes into progress nodes, in English and German: from_disk, the running message of an explicit @cached/@mmap value read back from disk; cached, the note on a documented property's node when a reader finds its value already in memory; and, for a computation sent to the job queue's worker process (configure_queue!(; workers=1)), the two phases it waits on before the worker runs it: starting_worker while the worker process starts, and loading_packages while the worker loads the packages the computation needs ({packages}, their names). A node is shared by every viewer, and a computation often runs on a background task, so DynamicObjects writes a Treebars.TreebarNote and each page renders it in its own language (__lang__, see Treebars' treebar_texts). An app rewords them by passing this table to Treebars.treebar_texts, e.g. treebar_texts(:de, DynamicObjects.progress_notes => (from_disk = "von der Festplatte ({size})",)).
Deferred work
DynamicObjects.Deferred Type
Deferred(executor)A nonblocking fetch selector that schedules work through executor(work::DeferredCompute). The first caller receives a Pending handle while the work waits or runs. Use it where fetch=identity is accepted.
The executor is called after registering the in-flight entry, with no cache lock held. It should enqueue promptly, then eventually run or abandon the work under the DeferredCompute contract. A deliberately inline executor may run it immediately. Declaration-level scheduling uses DynamicObjects.property_executor; blocking waits cooperate through DynamicObjects.await_deferred.
DynamicObjects.DeferredCompute Type
DeferredComputeOne first-arriving compute, handed to a Deferred executor. Its in-flight latch is already registered, so concurrent accessors of the same key already dedupe onto it — blocking callers wait for it, pollers receive a Pending — for as long as it sits in the executor's queue. Its progress node stays pending (·, no elapsed time) until run! starts it.
The executor must eventually call exactly one of:
run!(d)— run the compute on the calling task. Call it from a worker to run in the background; calling it synchronously inside the executor makes the originatingget!behave like a blocking accessor — the value, not aPending, comes back (the escape hatch for a compute started from inside one of the executor's own workers, where queueing behind yourself would deadlock).abandon!(d, reason)— never run it; the key fails withComputeAbandoned.
Only the first of the two takes effect. Dropping a DeferredCompute without calling either leaves the key in flight forever.
Whichever task calls run!, the compute runs as an undeferred compute would where it was started: under the logger current there, and with every ScopedValue set there (a layer's own request context, a with_compute_trace scope). Only the job queue's slot is the running task's own.
DynamicObjects.ComputeAbandoned Type
ComputeAbandoned(reason)Recorded as a key's failure when an executor abandon!s a queued compute instead of running it, or when the worker process running it (see configure_queue!) exited or was restarted (started is then true). Waiters and pollers see it like any other failure; with the default retry_failed=true the next access starts a fresh compute.
A worker process's end is named at the end of reason: killed by signal 9 (SIGKILL) (a kill -9, or a system memory killer), another signal such as SIGSEGV or SIGABRT for a crash, or with exit code N for an exit, as in the worker process (pid 14783) exited while computing it, killed by signal 9 (SIGKILL). worker_stderr contains the last lines of that process's standard error (up to 100 lines and 64 KiB), or an empty string when there is none. Printing the exception includes this excerpt below the reason. The excerpt can contain output from any computation on that worker.
DynamicObjects.run! Function
run!(d::DeferredCompute) -> BoolRun a deferred compute on the calling task, publishing its value (or recording its failure) exactly as an undeferred compute would. Returns false without running if d was already run or abandoned. Failures are recorded for waiters/pollers, not rethrown.
DynamicObjects.run!(produce, d::DeferredCompute) -> BoolRun d with produce(status) in place of its own computation: whatever produce returns is published for d's key, and whatever it throws is recorded as the key's failure, exactly as run!(d) publishes or records its own computation's outcome. So the in-flight fence (a computation invalidated meanwhile publishes nothing), property_settled, the waiters and Pending handles behave as for a local computation. produce runs on the calling task, under the requester's logger and ScopedValues; status is d's progress node, started before produce is called. Returns false without calling produce if d was already run or abandoned. An executor that computes elsewhere — DynamicObjects' worker process — publishes through it.
DynamicObjects.abandon! Function
abandon!(d::DeferredCompute, reason="abandoned") -> BoolFail a queued compute without running it: records ComputeAbandoned for the key, releases its latch (waking blocked accessors) and fails its substatus. Returns false if d was already run or abandoned.
DynamicObjects.property_executor Function
DynamicObjects.property_executor(o, ::Val{name}) -> executor or nothingDeclaration-site executor of indexed property name. When it returns an executor, every memoized computation of the property starts through executor(d::DeferredCompute), whichever task triggers it and however it is called: a blocking call o.name(args...), a progress-threaded call under @progress / @fetch! (both computed inline otherwise), or a poll (fetchindex, fetch=identity). It is fetch=Deferred(executor) chosen by the declaration instead of by each caller; a caller's own fetch=Deferred(other) takes precedence. The default, nothing, keeps the per-call behavior.
A macro layered on @dynamicstruct declares it next to the property:
DynamicObjects.property_executor(::Jobs, ::Val{:item}) = JOB_QUEUEMemoization is unchanged: a cached value never reaches the executor, and concurrent callers with the same arguments share one DeferredCompute, whether it is queued or running. A blocking caller waits for it through await_deferred; when the executor runs the compute synchronously, the call returns the value without waiting. @fresh calls (declaration- or call-site) bypass the cache, its in-flight latch and hence the executor — except a job queue's QueueExecutor (@queued), which admits each fresh computation too, as a QueuedCall the caller waits for. See DeferredCompute for the executor contract.
DynamicObjects.await_deferred Function
DynamicObjects.await_deferred(wait, executor)Wraps every blocking wait of a call that carries executor (any call of a property whose property_executor returns it, or a call with fetch=Deferred(executor)), including a blocking fetch of a Pending such a call returned. For a property with a declared executor that is every blocking wait on it: a caller waiting for the compute it handed to the executor, and a caller that finds the computation already queued or running. Waits that would not block (the value or failure is already recorded) do not call it.
wait() blocks the calling task until the computation settles and returns its value or throws its failure. The default just calls wait(). An executor's owner overloads it for its executor type to learn when a task starts and stops blocking, for example to give a job's runner slot back while that job waits:
function DynamicObjects.await_deferred(wait, q::JobQueue)
release_slot!(q)
try
wait()
finally
reacquire_slot!(q)
end
endAn overload must call wait() exactly once, on the calling task, and return its result.
DynamicObjects.property_settled Function
DynamicObjects.property_settled(o, ::Val{name}, value, args...; kwargs...)Settlement hook of memoized property name. DO calls it each time a computation of the property stores its result in memory: the body ran, or an explicit @cached / @mmap entry was read from disk. value is the stored value; for an indexed property, args and kwargs are the call's. The default does nothing.
Define it as an ordinary method, or as a member method in the struct body, where sibling names read as they do in a property body:
@dynamicstruct struct Table
root::String
subscriptions::KeySubscriptions
runs = TrackedDirectory(root)
snapshot = build_snapshot(runs)
DynamicObjects.property_settled(__self__, ::Val{:snapshot}, value) =
foreach(key -> invalidate_key!(subscriptions, key), value.changed_keys)
endIt runs once per stored value: after the store, after every caller waiting for that computation has been released, outside every cache lock, on the task that ran the computation, which returns only after the hook does. Reading the property inside the hook returns value unless something dropped it meanwhile. It does not run for a cache hit, for a caller that waited for the computation, for a failed computation, for a @fresh call (it stores nothing), for a computation an invalidation retracted while it ran (it stores nothing either), or for a value seeded by a constructor, remake or clear_mem_caches!. A governed host's automatic storage, which may swap the stored value for its persisted copy or reload it later, does not call it either. A throwing hook is logged with its backtrace; the value stays stored and is returned to the caller.
o is the object whose read ran the computation: a remount view when one did. A view whose computation reads request context reports its own value.
Notify from here, not from the property's body: inside the body the value is not stored yet, the computation can still fail, and reading the property waits for itself. Keep the hook short and start heavy work on another task. Unlike BackgroundCache's on_settle there is no old value, because a dropped value is gone before its replacement is computed: carry whatever a consumer compares in the value itself.
Queue configuration
DynamicObjects.configure_queue! Function
DynamicObjects.configure_queue!(q=job_queue(); max_running=nothing, workers=nothing,
worker_start=nothing, worker_exeflags=nothing,
worker_preload=nothing, worker_idle_timeout=nothing,
worker_reply_warn_bytes=nothing) -> NamedTupleBound how many queued computations run at once. Off by default (max_running=0): a @queued computation starts on :default at once. With max_running=n at most n run at a time and the rest wait in FIFO order, their progress node pending (·, no clock) and reading "queued · #k"; they start as earlier ones finish or give their slot back. Raising the cap starts more of what waits; max_running=0 starts everything still waiting. Running computations are never interrupted.
With a positive worker count every computation the queue admits — each memoized or fresh computation of a @queued property — runs in a child Julia process instead of on a :default task of this one, so a compile, a GC pause or a deadlock there never stalls this process. Slots, FIFO order and the "queued · #k" note are unchanged; an admitted computation holds its slot while the worker runs it. The worker builds the same object from the same inputs (the root object's type must be defined in a package, which the worker loads), computes the property through its own memoized path, and hands the value back: a @cached / @mmap value through its disk entry, which this process then loads; any other value serialized. The queue selects the worker with the fewest assigned requests, including ones starting or loading packages. Ties favor a worker that recently computed from the same root. Nested reads run in the same process as their caller. Workers have independent memory caches. A computation whose body reads the request (__req__) stays in this process, with one warning per property. A worker's exception arrives as a PropertyComputationError caused by a RemoteComputationError that holds the worker's printout, and unwrap_error returns the exception itself wherever it can cross; a worker that exits fails every computation it ran with ComputeAbandoned. workers=0 (the default) runs everything here; switching to it stops the worker. When this process exits, its exit hooks kill the worker at once instead of waiting for it, so a stuck worker never holds the exit up.
The worker runs this process's Julia with its code-generation flags, active project, LOAD_PATH and DEPOT_PATH. By default the pool divides this process's default threads among its configured workers (at least one each), plus one interactive thread each, so its message loop keeps answering on the interactive thread while computations run on the default ones; worker_exeflags replaces that thread flag (pass e.g. ["--threads=8,1"]). The worker also inherits an equal share of this process's --heap-size-hint, when set, unless worker_exeflags supplies one explicitly. This is a per-process garbage-collection hint, not a shared memory cap: the parent, worker and other processes still need their own headroom. Flags apply at process startup. After resizing a live pool, restart existing processes to apply the new per-process budgets. worker_start=:lazy (the default) starts the worker on demand, including after an exit. worker_start=:now starts it in the background and replaces it after an unexpected exit, even while idle. Repeated startup failures or short-lived workers trigger up to three background retries with increasing delays. A worker ready for 30 seconds resets this limit. After retries are exhausted, a computation assigned to that slot can still start a worker. Reapply worker_start=:now to resume background recovery. In a single-worker queue, restart_worker!() also starts a new attempt. Set worker_preload=[AppModule] to also load the application's packages at startup, before any computation is submitted. The list accepts package modules (a nested module selects its root package) or Base.PkgIds, and is reapplied after a restart. With :now and a nonempty list, cold configuration returns after launching the child with its preload list. Its connection and package initialization continue in the background, including while the parent imports the same package. Repeating the configuration with the corresponding module reuses the worker and any preload in progress. Additional workers exit after worker_idle_timeout seconds idle (default 300, Inf keeps them warm) and start again on demand. Open compute scopes keep the workers they use. With :lazy, packages load with the first worker-bound computation. Changing the list under :now also loads its packages into an already-running worker; worker_preload=[] clears the list for future starts but cannot unload packages. An omitted list stays unchanged. Preload failures are logged during background startup and fail a computation that still needs the preload; they are never treated as successful loads. Packages outside the list load when a computation first needs them. Preloading runs package initializers; it does not run properties or compile their first calls. A computation that waits for the worker to start, or for it to load packages, shows each wait as a phase of its progress node ("Starting the worker process", "Loading packages: …", from DynamicObjects.progress_notes), kept there ahead of the worker's own phases. See worker_status and restart_worker!.
worker_reply_warn_bytes defaults to 64 MiB. A worker emits one warning before sending a result whose serialized size exceeds this many bytes. It includes the owning type, property, abbreviated arguments, worker PID, request ID and exact byte count. Set a nonnegative integer to change the threshold for subsequent submissions on this queue.
Returns queue_settings(q); an omitted setting is unchanged.
DynamicObjects.queue_settings Function
DynamicObjects.queue_settings(q=job_queue()) -> (; max_running, queued, running, workers)q's cap, the number of items waiting, the number of slots held, and the number of worker processes configured (see configure_queue!).
DynamicObjects.job_queue Function
DynamicObjects.job_queue() -> JobQueueThe process-wide queue that @queued properties admit their computations through.
DynamicObjects.JobQueue Type
DynamicObjects.JobQueue(; max_running=0)FIFO admission under max_running slots. Each admitted item runs on its own :default task and holds one slot until it finishes, or until it — or a task it spawned — blocks on another queued computation, which gives the slot back for good. max_running=0 means unbounded: every item starts at once, holding no slot. @queued properties admit through the process-wide job_queue(); see configure_queue!.
Queue observation and admission
DynamicObjects.QueuedItem Type
DynamicObjects.QueuedItemOne entry of a JobQueue, as enqueue! creates it and queue observers receive it:
work— what runs: aDeferredCompute, aQueuedCall, or any value withrun!/abandon!methods;property— the name of the@queuedproperty it computes,nothingotherwise;tag— whatever the enqueuer attached (aQueueExecutor'stag);enqueued_ns—time_ns()when it was enqueued.
DynamicObjects.observe_queue! Function
DynamicObjects.observe_queue!(f, q=job_queue()) -> fCall f(item::QueuedItem) for every item enqueued on q from now on: on the enqueuing task, before the item can start, with no queue lock held. A layer on top records each queued computation here, e.g. as a job named after item.property. A throwing observer is logged and the item is queued regardless: an enqueue runs inside a property access, and failing it would leave the computation in flight forever. Remove it with unobserve_queue!.
DynamicObjects.unobserve_queue! Function
DynamicObjects.unobserve_queue!(f, q=job_queue())Stop calling f for items enqueued on q.
DynamicObjects.queued_items Function
DynamicObjects.queued_items(q=job_queue()) -> Vector{QueuedItem}The items waiting in q, oldest first: an item's index is its queue position. Admitted items are not listed.
DynamicObjects.queue_position Function
DynamicObjects.queue_position(handle, q=job_queue()) -> Int or nothingThe 1-based position in q of the waiting computation behind handle — a Pending (matched by its cache and key), a DeferredCompute, a QueuedCall or a QueuedItem; nothing when it is not waiting (admitted, finished, or never queued).
DynamicObjects.abandon_queued! Function
DynamicObjects.abandon_queued!(q, items, reason="abandoned") -> IntTake those of items (QueuedItems) that still wait in q out of it and abandon! each: a DeferredCompute's key fails with ComputeAbandoned, and so does a QueuedCall's fetch. Items already admitted are left alone. Returns how many were abandoned. Which waiting items to give up on — say, those nobody has polled for a while — is the caller's decision.
DynamicObjects.QueuedCall Type
DynamicObjects.QueuedCall(f)A queueable call with no cache cell behind it: enqueue! it, then fetch it for f()'s value (rethrowing its failure, or ComputeAbandoned if it was abandoned before it started) and isready it to poll. It follows the DeferredCompute contract: exactly one of run!(call) and abandon!(call, reason) takes effect. A blocking fetch from inside a queued computation first gives that computation's slot back, as a wait on a @queued property does. status, a progress node, reads "queued · #k" while the call waits and is started when the call runs: create it with Treebars.prepare_progress! to show the call as waiting rather than running. Whichever task runs the call, f runs under the logger and with the ScopedValues current where the call was created; only the job queue's slot is the running task's own.
A fresh computation of a @queued property (declaration-site @fresh, or a call-site fresh) runs as one: the caller waits for its turn and its value.
DynamicObjects.enqueue! Function
DynamicObjects.enqueue!(q::JobQueue, work; property=nothing, tag=nothing) -> QueuedItemQueue work — a DeferredCompute, a QueuedCall, or any value with run!(work) / abandon!(work, reason) methods (exactly one of which takes effect) — behind what already waits in q. It starts on a :default task as soon as a slot is free, at once while q is off. Observers see the item before it can start.
DynamicObjects.QueueExecutor Type
DynamicObjects.QueueExecutor(queue=job_queue(); property=nothing, tag=nothing)A Deferred executor that enqueue!s each DeferredCompute on queue, carrying property and tag to its QueuedItem. A @queued property's declared property_executor is one, with its own name as property; pass one as fetch=Deferred(QueueExecutor(...)) to queue a single call. Every blocking wait on a computation it started gives back the slot of the queued computation the waiting task works for (see await_deferred).
Worker lifecycle
DynamicObjects.worker_status Function
DynamicObjects.worker_status(q=job_queue()) -> NamedTupleFor zero or one worker, returns (; workers, running, pid, started_at, in_flight, last_message_at). For a pool, running reports whether any process is up and in_flight counts all assigned requests, including startup. The process-specific fields are nothing. The additional processes vector gives each slot's pid, running, started_at, last_message_at and in_flight, in slot order. Timestamps are seconds since the epoch.
DynamicObjects.restart_worker! Function
DynamicObjects.restart_worker!(q=job_queue(); pid=nothing) -> NamedTupleStop the process with the observed pid, failing its requests with ComputeAbandoned. For work running on that process, the reason says was stopped followed by its exit code or signal. A replacement starts on demand, or immediately under worker_start=:now. A pool requires an explicit PID from worker_status().processes. A PID that has already exited leaves its replacement alone. With zero or one worker the argument can be omitted. Returns worker_status.
DynamicObjects.RemoteComputationError Type
DynamicObjects.RemoteComputationError(pid, message, exception=nothing)The failure of a computation that ran in the worker process pid. message holds the exception and its backtrace as the worker printed them; exception holds the exception itself, rebuilt in this process, or nothing when it could not cross (message then says why). It arrives wrapped in a PropertyComputationError for the property this process asked for. unwrap_error returns exception when there is one, as it returns the original exception of a failure in this process, and this error otherwise.
Worker request context
DynamicObjects.carry_to_worker! Function
DynamicObjects.carry_to_worker!(owner::Module, name::Symbol; wire=identity, unwire=identity)Carry the ScopedValue bound to owner.name into worker computations. Register it in the owning package's __init__, so both processes register their own variable and conversion functions. owner may be a nested module of that package. Returns the scoped variable; registering the same binding again replaces its converters for subsequent computations.
Before submitting a computation, wire(variable[]) runs in the initiating requester's scope. The result must be serializable data. The worker loads the owning package and binds its registered variable to unwire(value) while reconstructing the addressed object and running its computation. Default values travel too. Each computation has its own scope; bindings do not persist into later requests, including after an error or worker restart. Conversions must not mutate their inputs. Register before starting computations.
This applies to memoized and fresh @queued property computations with a positive worker count. In-process computations already inherit every requester scoped value and do not call these converters. A shared memoized computation still uses the scope of its first caller; this does not add context to cache keys. Unregistered scoped values are not transported. Missing worker registrations and conversion failures fail the computation instead of silently running it with a default value.
DynamicObjects.on_requester_message! Function
DynamicObjects.on_requester_message!(f, tag::Symbol) -> fHandle the messages a computation sends with send_to_requester(tag, payload): f(payload) runs in this process, as whoever requested the computation — under its logger and with its ScopedValues — on the task waiting for the computation's result, before that result is published and in order with its other messages and log records. One handler per tag; registering again replaces it. A throwing handler is logged and the computation continues.
DynamicObjects.send_to_requester Function
DynamicObjects.send_to_requester(tag::Symbol, payload)Send payload from a running computation to whoever requested it, where the handler registered with on_requester_message! for tag receives it. In a worker process the payload is serialized to the process that sent the computation and handled there; anywhere else the handler is called at once, in the current scope. A computation that several callers share sends to the one that started it. Without a handler for tag, the message is dropped.
Computation traces
DynamicObjects.with_compute_trace Function
with_compute_trace(f; events=0, invalidations=1000) -> (value, trace)
with_compute_trace(f, trace::ComputeTrace)Run f() and record property reads in a ComputeTrace. The scope follows spawned tasks and deferred work. Nested scopes also record in the outer trace. An existing trace can collect several calls and remains available if f throws.
compute_trace_rows reports counts and times by type and property. Outcomes distinguish memory hits, memoized computations, fresh computations, disk reads, waits, pending polls and errors. Dunder-property reads and a direct fetch of a Pending handle are not recorded separately.
total_s includes nested reads; self_s subtracts reads nested on the computing task. It does not subtract time spent waiting for separately spawned tasks. hit_s includes key hashing. These are measured durations, not estimates of execution time with compilation excluded.
events retains at most that many individual reads in trace.events, holding arguments by reference. invalidations bounds the invalidation log, which records clears, entry invalidations and synchronization that drops values. The trace stops changing when all its scopes have ended.
DynamicObjects.ComputeTrace Type
ComputeTrace(; events=0, invalidations=1000)What property reads did while a with_compute_trace scope using it was active. Show it for a per-property table and the invalidation log; compute_trace_rows returns the table as data. Fields:
events::Vector{ComputeTraceEvent}: the firsteventsreads (none by default), andevents_dropped, how many more were not kept;invalidations::Vector{ComputeTraceInvalidation}: the firstinvalidationsinvalidations, andinvalidations_dropped.
A trace records only while one of its scopes is active, so a trace whose scopes have all ended never changes, even when a task spawned inside one of them outlives it.
sourceDynamicObjects.compute_trace_rows Function
compute_trace_rows(trace::ComputeTrace) -> Vector{NamedTuple}The per-property table of a ComputeTrace as data, one row per (type, property) with type, property, calls, hits, computed, fresh, disk, waits, pending, errors and the times in seconds self_s, total_s, max_s, hit_s, wait_s (see with_compute_trace). Sorted by own time, self_s + hit_s, then by calls.
DynamicObjects.ComputeTraceEvent Type
ComputeTraceEventOne read a ComputeTrace kept (with_compute_trace(f; events=n)): at (seconds since the trace started), type, property, args (the (indices, kwargs) of an indexed read, held by reference, or nothing for a bare read), outcome (:hit, :wait, :pending, :computed, :disk, :fresh, :error or :failed) and duration (seconds).
DynamicObjects.ComputeTraceInvalidation Type
ComputeTraceInvalidationOne invalidation a ComputeTrace logged: at (seconds since the trace started), verb (:clear_mem_caches!, :clear_cache!, :invalidate!, :sync! or :clear_disk_caches!), the object's type, the property names it dropped (that held a value), the entry key (indices, kwargs) of a per-entry invalidate! (else nothing), and issued_from: (type, property) of the traced computation running on the issuing task, or nothing when it was issued outside one.