Polling and progress
Request a property without blocking the caller, distinguish a pending result from a completed value, and inspect progress. Both scalar and indexed properties support polling. A normal blocking read computes inline on its caller's task unless an executor changes that policy.
Scalar polling
fetchproperty starts or observes a scalar computation and passes the result and status to a callback. This example holds the computation behind a channel, so the pending state is reproducible without timing assumptions.
using DynamicObjects
@dynamicstruct struct Work
gate::Channel{Nothing}
"A gated scalar computation."
value = (take!(gate); 42)
scaled(gain) = gain * value
end
work = Work(Channel{Nothing}(1))
pending = fetchproperty(work, :value) do result, status
result
end
pending isa PendingtrueThe callback runs with a Pending handle while work is in flight. It can render a waiting state without fetching the value. Calling fetch on that handle blocks until the computation completes or throws.
put!(work.gate, nothing)
fetch(pending)42Indexed polling
fetchindex is the corresponding operation for an argument-taking property. Its callback also receives (result, status). A completed entry returns its value immediately; an unfinished entry returns a handle.
result = fetchindex(work.scaled, 2) do value, status
value
end
value = result isa Pending ? fetch(result) : result
value84Polling does not require @cached. Disk persistence is a separate choice. Repeated requests for the same entry share its in-flight computation. force=true on fetchindex invalidates the requested entry before requesting it again; use the cache guide to choose the invalidation scope.
Progress
An object supplies a Treebars progress root by default. A property's docstring labels its progress node. Reads visible inside a property body attach under the reader; the status passed to a poll callback is the node for the observed computation, or nothing when progress is disabled.
status = getstatus(work.scaled, 2)
(root_exists = work.__status__ !== nothing,
entry_status_exists = status !== nothing)(root_exists = true, entry_status_exists = true)Pass __status__ = nothing when constructing an object to turn its progress off. To label a root, provide a Treebars node as that keyword. The fetchindex! and fetchproperty! overloads accept a progress node when a caller needs explicit attachment. @fetch! threads those reads through a block; ordinary property bodies already attach their visible reads.
Queued work
@queued on an indexed property routes its computations through the package's process-wide job_queue. configure_queue! sets its concurrency cap: max_running=0 admits work immediately; a positive cap makes later work wait in FIFO order. Cached values never queue, and callers with the same arguments share one memoized computation. A queued computation gives back its slot when it waits for another queued computation, allowing its child to run.
An application can also create a separate queue and submit a QueuedCall. This call returns its computed value through fetch without creating a property cache entry.
queue = DynamicObjects.JobQueue(max_running=2)
call = DynamicObjects.QueuedCall(() -> sum(abs2, [1, 2, 3]))
DynamicObjects.enqueue!(queue, call)
result = fetch(call)
result14Use queue_settings and queued_items to inspect admission. observe_queue! registers an enqueue observer; unobserve_queue! removes it. abandon_queued! withdraws waiting work without interrupting computations already admitted.
Worker processes
Use DynamicObjects.configure_queue!(; workers=2, max_running=2) to run two independently submitted @queued computations concurrently. For example, while a fit runs on one process, a figure from the same root can use the idle process. A nested read in the fit runs on the fit's process. Each process keeps its own memory cache. Workers send memory-only results in bounded pieces, so a result can exceed the size of a single socket read on macOS. The requester reassembles the result in memory. For @cached and @mmap results, the worker publishes the file and the requester loads it.
For a result larger than 64 MiB, look for DynamicObjects: large worker result in the forwarded worker stderr. It gives the worker PID, request ID, owning type, property, abbreviated arguments and serialized byte count before the first piece goes out. To inspect smaller results, run DynamicObjects.configure_queue!(; worker_reply_warn_bytes=1024^2). The next submissions to that queue use the 1 MiB threshold, including on already-running workers. Restore the default with worker_reply_warn_bytes=64 * 1024^2.
On disconnect, the requester logs a warning for each outstanding call assigned to that worker. Match the worker PID and request ID across the two logs. If a transfer was interrupted between pieces, the warning gives the event kind and its full serialized byte count. Before a header arrives, the size is unknown.
The queue counts requests from assignment through completion, including time spent starting a process or loading packages. When workers have equal loads, the queue prefers one that recently used the root. The root type must belong to a package each worker can load. workers=1 uses one child and workers=0 runs admitted work in the requester.
In a pool, DynamicObjects.worker_status().processes lists each process's PID and outstanding request count. Pass the observed PID to DynamicObjects.restart_worker!(; pid) to replace that process. The other processes continue their work. Surplus processes retire after five minutes idle by default. An open compute scope keeps the processes it used until it closes.
To overlap package loading in the parent and worker, configure the queue before importing the package. This example uses the TOML standard library. In an app entry script, use the name of the package that defines your queued computations.
import DynamicObjects
app_id = Base.identify_package("TOML")::Base.PkgId
DynamicObjects.configure_queue!(; workers=1, worker_start=:now, worker_preload=[app_id])
using TOML
settings = DynamicObjects.configure_queue!(; worker_preload=[TOML])
settings.workers1
Configuration returns after launching the child with its package list. The child can initialize the package during the parent's import. A later call that names the same package by module keeps the worker. If the first request arrives during preload, it waits for initialization.
With worker_start=:now, the queue starts a replacement after an unexpected exit and loads its worker_preload packages even while idle. Work already running in the lost process receives ComputeAbandoned. Other workers keep their PIDs and their work. A surplus worker stopped by its idle timeout starts again on demand. With the default :lazy setting, a request assigned to the vacant slot starts its replacement. The configuration reference describes retry limits and preload settings. Use worker_status to inspect the process and restart_worker! to replace it. carry_to_worker! registers named package scoped values for transport; unregistered scoped values do not travel. Worker computations can send messages through send_to_requester to a handler registered with on_requester_message!.
Executors and errors
Framework code can supply a Deferred executor, with property_executor selecting it for a declaration. await_deferred lets its blocking waits cooperate with the scheduler. Keep synchronous computations as ordinary properties unless the application needs a scheduling policy.
A failed body is reported through PropertyComputationError. unwrap_error retrieves the underlying exception for error reporting. Invalidation retracts a cached computation; it does not forcibly stop arbitrary Julia code already running. See ComputeAbandoned for work abandoned before execution.
Cached signal analysis uses with_compute_trace to distinguish work from cache reuse without relying on elapsed times.