Normative Rules: Host Object Ontology and Lifecycles

← Prev | ↑ Chapter | Next → | Index | Symbols

Normative Rules: Host Object Ontology and Lifecycles

Statement

The reactor catalogue is interpretable only against the host's object ontology. Each reactor type subscribes to lifecycle transitions of one specific class of host object; the published reaction names are systematic transition labels in those classes' finite-state machines.

This section pins down: the host object graph, the lifecycle of each class, the canonical event vocabulary, and the scope rule (per-document vs per-application).

Host Object Graph

The graph is small and stable; it has been the same shape since AutoCAD R14's Visual LISP merger.

Application                       (one per process)
+--__ DocumentManager               (the documents collection)
_    ___ Document  (_N)           (one per open drawing)
_         +--__ ModelSpace, PaperSpace, Blocks, Layers, Linetypes,
_         _   TextStyles, DimStyles, Views, UCSs, Viewports,
_         _   RegisteredApplications, NamedObjectsDictionary,
_         _   SystemVariables (per-document), ActiveSelectionSet,
_         _   Picksets, Entities, PendingCommand, UndoStack
+--__ Preferences, ARXModules, LispEnvironment,
_   ApplicationReactors,
___ PromptHistory / CommandLine

Per-Class Lifecycles

Class	States	Notes
`application`	`:running` → `:quitting` → `:quit`	One per process
`document-manager`	always `:running`	The collection itself never opens or closes; only its members do.
`document`	`:loading` → `:loaded` _ `:active` _ `:inactive` → `:closing` → `:closed` (transient `:saving` during write)	The dominant lifecycle.
`command`	`:pending` → `:started` → `:running` → (`:ended` _ `:cancelled` _ `:failed`)	One state machine per invocation.
`entity`	`:created` → `:committed` _ `:modified` → (`:erased` _ `:unerased`) → `:purged`	The "modified" loop dominates. `:erased` is reversible; `:purged` is terminal.
`selection-set`	`:created` → `:populated` _ `:mutated` → `:released`	Non-graphical; usually short-lived.
`dictionary-entry`	`:added` → `:present` → (`:renamed` _ `:mutated`) → `:removed`	Persistence-domain object.
`sysvar`	always `:bound`; transitions `value-will-change` / `value-changed`	Atomic; no construction/destruction.
`xref`	`:unresolved` → `:resolved` _ `:unloaded` _ `:reloaded` → `:detached`	Drives `vlr-xref-reactor`.
`wblock-op`	`:started` → (`:completed` _ `:cancelled`)	Transient.
`undo-op`	`:begin` → (`:commit` _ `:rollback`)	Transient.
`mouse-event`	`:down` → (`:drag*`) → `:up`	Transient.
`vlx-app`	`:loading` → `:loaded` → `:unloaded`	Drives `vlr-linker-reactor`.
`lisp-eval`	`:loading-source` → `:running` → `:idle`	Drives `vlr-lisp-reactor`.
`reactor`	`:armed` _ `:disabled` → `:removed`	Reactors themselves have a lifecycle.

Event-Naming Convention

Reactor reactions are systematic names for transitions in the table above. The convention has two halves:

A *WillChange / *ToBeFooed reaction fires before the transition; the world is still in the old state. The callback may sometimes veto the transition.
A *Changed / *BecameFoo / *Fooed reaction fires after the transition; the world is in the new state.

Most documented transitions emit a pair of reactions; this is why the vendor reactor reactions look so verbose.

Event Scope Rule

Every event has a single canonical scope — application or document — and a single canonical reactor type:

Event	Scope	Reactor type
`:vlr-documentCreated`	application	`vlr-docmanager-reactor`
`:vlr-documentToBeDestroyed`	application	`vlr-docmanager-reactor`
`:vlr-beginDocumentClose`	document	`vlr-document-reactor`
`:vlr-objectModified`	document	`vlr-acdb-reactor` / `vlr-object-reactor`
`:vlr-sysVarChanged`	document	`vlr-sysvar-reactor`
`:vlr-commandWillStart`	document	`vlr-command-reactor`
`:vlr-beginQuit`	application	`vlr-editor-reactor`
`:vlr-beginARXLoad`	application	`vlr-linker-reactor`

Some events have both an application-scope and a document-scope reactor type subscribed to the same transition. Document-activation is the canonical case: vlr-docmanager-reactor subscribers see every document's :vlr-documentBecameCurrent; vlr-document-reactor subscribers on document X see only X's. The runtime fires both.

Vetoing

A few *WillChange events let the callback veto the transition. clautolisp models this through the callback's return value:

A non-nil return permits the transition.
The keyword :veto rejects it; the runtime aborts the transition and signals :transition-vetoed to the caller that initiated it.

Only events documented as vetoable by the vendor honour this: :vlr-documentLockModeWillChange, :vlr-aboutToBeDeactivated, and the *WillStart family of command reactions.

Persistence

A persistent reactor (registered through vlr-pers) is stored in the document's named-object dictionary, traditionally under the key ACAD_REACTORS. Its callback is referenced by symbol name, not by closure: closures cannot survive serialisation, but symbol names re-resolve when the document is opened.

On document open the host walks ACAD_REACTORS and reconstructs each persistent reactor before user code executes. If the callback's symbol is undefined at fire time, dispatch records the failure and continues; the reactor is not removed.

Vendor Evidence

Autodesk reference for the Visual LISP reactor family — the per-class reaction tables in AutoCAD-AutoLISP-Reference/files/GUID-... pages — define the reactor types, the reaction names per type, and the per-event argument shape.
Bricsys Lisp - BricsCAD help page documents the same taxonomy with no functional divergence on per-document vs per-application scope.
The reactor data model (callback by symbol name, persistence in ACAD_REACTORS) is documented in the AutoCAD ObjectARX guide and surfaced through Visual LISP's vlr-pers family.

Strict / Lax Policy

The ontology is strict in every supported dialect; the only behaviour that varies between hosts is the set of reactor types recognised. The clautolisp strict, autocad-2026, and bricscad-v26 dialects accept the union of reactor types documented by either vendor.

Cross-references

Reactor type entries (this chapter) — each lists the reactions it subscribes to.
Function Entry: vlr-pers, vlr-pers-release, vlr-pers-list — the persistence interface.
Function Entry: vlr-set-notification — the notification-mode toggle (:all-documents / :current-document-only).