hal/live-artifact.lisp
Application-level protocol ------------------------------------------------
Return application's live artifacts as a fresh list.
The list is an enumeration, not a transfer of ownership. Applications with no live artifacts inherit the empty default. An artifact may represent one GPU pipeline, a complete renderer cohort, or another transactionally replaced application derivative; the protocol does not impose a resource grain.
Return a concise human-readable label for artifact.
Return artifact's lifecycle status.
Concrete artifacts normally use :BUILDING, :INSTALLED, :FAILED, :releasing,
and :RELEASED. :FAILED means that the last attempt failed while the previous
installed artifact, when any, remains usable.
Return artifact's newest build or retirement diagnostic, or NIL.
Return artifact's monotonically increasing installed revision.
Attempt pending source for artifact at its owning application boundary.
Implementations must build away from installed state, publish only a complete candidate, preserve the last-known-good artifact on failure, and coalesce newer invalidations without performing GPU work in definition callbacks. Explicitly released artifacts must not be resurrected.
Explicitly and idempotently release artifact and its subscriptions.
Release is terminal. Application owners remain responsible for calling this at a boundary where no new encoding can borrow the installed GPU resources.
Refresh the current live-artifact enumeration of application.
Mathematical shader pipelines -------------------------------------------
The live named values folded into the installed and most recently attempted sources, as (NAME . VALUE). Failed attempts deliberately replace ATTEMPTED-SOURCE-VALUES so a value which repairs the failed source requests another attempt without disturbing the installed value.
Source notifications never acquire this lock. It serializes only the owner-side build/install/release transition, preventing concurrent refresh or teardown from publishing or retiring the same resources twice.
A last-known-good GPU render pipeline following live shader definitions.
The owning application calls refresh-live-artifact at a frame boundary.
Definition callbacks only advance thread-safe revision sources; compilation,
GPU creation, publication, and retirement happen here, outside MOP locks.
A complete unpublished shader-pipeline candidate and its owned resources.
Release candidate resources which have not transferred to an artifact.
Preserve the primary build condition while still giving each resource an independent retirement attempt. GPU backends retain failed native retirements in their durable queue-owned ledgers.
Build and return a complete candidate without replacing artifact's state.
Record dependencies even when parsing, lowering, or GPU creation fails. A live value which changes after the failed attempt can then request a retry without waiting for an unrelated source edit.
Publish candidate into artifact and retire the previous complete artifact.
Publish the complete replacement as one owner-side state transition. The application calls at a frame boundary, so command encoding before this transition observes the old cohort and encoding after it the new.
Ownership has crossed to artifact. Detach before retirement so cleanup
after any future change to this function cannot destroy installed state.
Backends retire resources across their actual submission-completion frontier. Do not retire an object a backend deliberately reused for the new cohort, and try every distinct old owner even if one retirement errs.
The replacement remains installed. Preserve the exceptional native retirement as diagnostic state; backend ledgers retain retry custody.
Create and install a live mathematical render pipeline.
vertex-module is borrowed when vertex-role is NIL and stage is not :VERTEX.
Every module compiled from role or vertex-role is owned by the returned
artifact and retired on replacement or explicit release.
Begin the cleanup boundary before subscribing: failed initialization must never leave an invisible dependent attached to the shader generic.
Owner-side implementation; caller holds artifact's mutation lock.
A failed edit is diagnostic state, not a rendering outage.
A definition which races this attempt remains pending because acknowledgement is capped at the snapshots taken above.
Compatibility spelling for refresh-live-artifact.
Owner-side implementation; caller holds artifact's mutation lock.
Relinquish every application-visible ownership claim before native retirement. A backend keeps custody when destruction reports an error; retaining the wrappers here would permit resurrection or a second retirement attempt by a later RELEASE call.
RELEASED is terminal even when reporting retirement failure.
Compatibility spelling for release-live-artifact.
(application)Return APPLICATION's live artifacts as a fresh list. The list is an enumeration, not a transfer of ownership. Applications with no live artifacts inherit the empty default. An artifact may represent one GPU pipeline, a complete renderer cohort, or another transactionally replaced application derivative; the…
(artifact)Return ARTIFACT's lifecycle status. Concrete artifacts normally use :BUILDING, :INSTALLED, :FAILED, :RELEASING, and :RELEASED. :FAILED means that the last attempt failed while the previous installed artifact, when any, remains usable.
(name &body body)(artifact)Return ARTIFACT's newest build or retirement diagnostic, or NIL.
(artifact)Return ARTIFACT's monotonically increasing installed revision.
(artifact)Attempt pending source for ARTIFACT at its owning application boundary. Implementations must build away from installed state, publish only a complete candidate, preserve the last-known-good artifact on failure, and coalesce newer invalidations without performing GPU work in definition callbacks. Explicitly released…
(artifact)Explicitly and idempotently release ARTIFACT and its subscriptions. Release is terminal. Application owners remain responsible for calling this at a boundary where no new encoding can borrow the installed GPU resources.
(application)A last-known-good GPU render pipeline following live shader definitions. The owning application calls REFRESH-LIVE-ARTIFACT at a frame boundary. Definition callbacks only advance thread-safe revision sources; compilation, GPU creation, publication, and retirement happen here, outside MOP locks.
How the children of a list are arranged.
(candidate)Logical conjunction of tests and raw truth values.
(handle)Logically invalidate HANDLE immediately. Native teardown may be deferred until submitted work which captured HANDLE has completed.
When bound to a cons cell, its car collects (NAME . VALUE) for every live named value folded while parsing, so the parser's caller can remember what its artifact depends on.
(role stage)Return the current durable shader specification for ROLE and STAGE.
(specification)(device descriptor)Asks the DEVICE for a handle to newly created instance of some object fulfilling the DESCRIPTOR.
Logical negation of one test or raw truth value.
(artifact revision source-revision candidate)Logical disjunction of tests and raw truth values.
(&key role (stage :fragment) vertex-role label device layout vertex-module
vertex-buffers target-format target-blend primitive depth-stencil)Create and install a live mathematical render pipeline. VERTEX-MODULE is borrowed when VERTEX-ROLE is NIL and STAGE is not :VERTEX. Every module compiled from ROLE or VERTEX-ROLE is owned by the returned artifact and retired on replacement or explicit release.
(generic-function arguments)(dependent)(artifact source-revision)(dependent)Test whether one compatible scalar is greater than another.
(references)(artifact)(dependent)(dependent revision)Record that the consumer finished attempting REVISION. A newer concurrent notification remains pending.
(artifact)(artifact)(&body body)(artifact)
Live application artifacts and shader pipelines.
A live artifact is an application-owned derivative of redefinable source. The protocol deliberately says nothing about the artifact's internal grain: a Luvcraft render pipeline and a
luftrenderer cohort can both be one artifact. Each implementation builds its candidate away from the installed state, publishes only a complete replacement at its owning application boundary, and keeps the last-known-good value on failure.