hal/tracy-capture.lisp
luv_TRACY_CAPTURE
luv_TRACY_PROFILER
The platform edge of a tracy-capture-controller.
Applications normally use native-tracy-capture-runtime. Tests and unusual
hosts can specialize this protocol without replacing the controller's state
machine.
The exact SBCL and luv Tracy process implementation.
Return the current universal time for names and diagnostics.
Whether pathname names an existing capture output.
Ensure the in-process Tracy client is running for application-name.
Whether a Tracy consumer is already attached.
Return the exact executable pathname for role.
role is one of :CAPTURE, :PROFILER, or :REVEAL. Implementations must not
silently fall back to a different tool version through PATH lookup.
Launch program for role with exact string arguments and return a handle.
Whether process is still alive.
Request process's graceful Tracy capture stop without waiting for it.
Forcibly terminate process after graceful capture shutdown failed.
This is the terminal orphan-prevention edge. A native implementation may discard the unfinished trace, but must make eventual process exit more likely than another graceful request would.
Wait for process on a controller-owned worker thread.
Return process's exit code after wait-tracy-process.
Release the Lisp-side handle for a finished process.
start-tracy initially calls its caller "main". This caller is a
deliberately separate control lane; applications name their actual
canvas lane when they next observe a connected viewer.
SIGINT is tracy-capture's graceful disconnect-and-save operation.
One contained asynchronous failure, suitable for an inspector or HUD.
One concurrent Tracy capture owner.
The public state sequence is :IDLE -> :STARTING -> :RECORDING -> :STOPPING -> :FINALIZING -> :IDLE, with :RELEASED terminal. A single generation owns at most one capture subprocess. No public operation waits for a subprocess.
Make an idle controller whose trace files live beneath directory.
Return controller's semantic state without exposing its lock.
Whether a capture is starting, recording, stopping, or finalizing.
Return the current generation's reserved output pathname, if any.
Return the most recent successfully frozen trace pathname, if any.
Return an oldest-first snapshot of contained asynchronous failures.
Return controller's newest contained asynchronous failure.
Record a diagnostic while controller's lock is already held.
Reserve a unique semantic name while controller's lock is held.
Clear generation's ownership while controller's lock is already held.
Spawn function, containing thread creation and unhandled worker failures.
Launch, reap, and close one non-capture helper on this worker thread.
Open pathname, or the last completed trace, without waiting for its GUI.
Reveal pathname, or the last completed trace, without waiting for Finder.
Claim the next stop action for generation while its owner remains alive.
Perform action on the generation-owning worker, retrying contained errors.
A failed terminal signal remains owned and is retried on the next bounded observation rather than becoming an orphan.
Let the capture owner service one published stop intent without a new thread.
Observe process on its owner worker, servicing stop and escalation intents.
Reap exactly once after the nonblocking observations report exit.
Wait, validate, publish, and close one exact capture generation.
Closing a live Lisp process handle does not terminate its OS child. A finalizer failure therefore makes one terminal attempt before the handle becomes unreachable.
Launch and own generation entirely on its background worker.
A stale launch is never allowed to become an orphan.
When STOP-NOW-P is true, the generation owner observes the already-published intent immediately in its bounded wait loop. A second worker is neither needed nor able to lose that signal.
Publish a new generation and return its pathname and worker closure.
Start one capture asynchronously, or return the current capture pathname.
Publish the first stop timestamp while controller's lock is held.
Atomically publish stop intent for the generation-owning worker.
Terminal idempotence needs no public retry call: the generation owner retains the controller and automatically retries itself.
Request one graceful stop and return immediately.
Concurrent and repeated calls publish only one interrupt for a generation.
Atomically start from idle or stop the one busy generation.
Detach controller immediately and asynchronously stop its owned capture.
This operation is terminal and idempotent. It never waits for capture finalization or for a profiler window.
LUV_TRACY_CAPTURE
LUV_TRACY_PROFILER
How often the capture owner observes process exit and stop intent.
Graceful-stop failures allowed before the owner forcibly terminates.
The platform edge of a TRACY-CAPTURE-CONTROLLER. Applications normally use NATIVE-TRACY-CAPTURE-RUNTIME. Tests and unusual hosts can specialize this protocol without replacing the controller's state machine.
One concurrent Tracy capture owner. The public state sequence is :IDLE -> :STARTING -> :RECORDING -> :STOPPING -> :FINALIZING -> :IDLE, with :RELEASED terminal. A single generation owns at most one capture subprocess. No public operation waits for a subprocess.
The exact SBCL and luv Tracy process implementation.
(runtime application-name)Ensure the in-process Tracy client is running for APPLICATION-NAME.
(runtime role)Return the exact executable pathname for ROLE. ROLE is one of :CAPTURE, :PROFILER, or :REVEAL. Implementations must not silently fall back to a different tool version through PATH lookup.
(runtime role program arguments)Launch PROGRAM for ROLE with exact string ARGUMENTS and return a handle.
(runtime process)Request PROCESS's graceful Tracy capture stop without waiting for it.
(runtime process)Forcibly terminate PROCESS after graceful capture shutdown failed. This is the terminal orphan-prevention edge. A native implementation may discard the unfinished trace, but must make eventual process exit more likely than another graceful request would.
(runtime process)Return PROCESS's exit code after WAIT-TRACY-PROCESS.
Logical negation of one test or raw truth value.
(&key (application-name "luv"))Load the Tracy client, start the profiler, and answer whether it is running. The client collects on demand, so starting it does not begin a capture: it makes this image discoverable, and zones start recording when a viewer connects. Leaving it started is the intended state for a durable image.
(name)Name the calling thread in Tracy's timeline, if the profiler is running. Worker threads are worth naming as they start: an unnamed thread still gets a lane, but the lane is a thread id rather than a job. A thread that starts before START-TRACY keeps the anonymous lane, so start Tracy before the session whose threads…
(variable description)Logical conjunction of tests and raw truth values.
Logical disjunction of tests and raw truth values.
(&key application-name directory
(runtime (make-instance 'native-tracy-capture-runtime))
(open-on-completion-p t)
(graceful-stop-seconds 5.0d0))(controller)((call tool-call) stream)(controller)(controller)(controller)(controller)(controller)(controller)(controller)(controller operation condition &optional pathname state)(controller operation condition &optional pathname state)(name)(controller)Test whether two compatible scalars are equal.
(controller generation)(controller generation)(controller operation pathname function)(pathname)(role pathname)(controller operation role pathname)(controller operation role pathname)(controller &optional pathname)(controller &optional pathname)(controller)Division of two represented quantities.
Subtraction or unary negation.
(controller generation process)Test whether one compatible scalar is at least another.
(controller generation process pathname action)One named verb over a session.
(controller generation process pathname)(controller generation pathname process)(controller generation pathname process)(controller generation pathname)(controller)(controller)(controller)(controller release-p)(controller)Request one graceful stop and return immediately. Concurrent and repeated calls publish only one interrupt for a generation.
(controller)(controller)Detach CONTROLLER immediately and asynchronously stop its owned capture. This operation is terminal and idempotent. It never waits for capture finalization or for a profiler window.
Concurrent, application-neutral ownership of Tracy capture subprocesses.
Public operations only publish intent and return. Program lookup, launch, graceful interruption, process waiting, trace validation, GUI launch, and process-handle close all happen on explicitly owned background threads.