Anvil
Explanation

How macros run

A macro is an Activity a modeller drew, and Anvil interprets it without a UML execution engine. This page states what one run does, in what order, and why the design settled where it did. The how-to covers drawing a macro; this page covers what happens after the modeller clicks.

Compile, then walk

A run has two halves. MacroCompiler reads the Activity and answers either a MacroPlan or a list of problems; PlanExecutor then walks the plan once, from the initial node to a final node. The plan holds one entry per node the runner may reach, keyed by the model node it interprets, so the walk looks nothing up in the model a second time.

The split is what makes an interpreter possible at this size. Everything a UML execution engine would decide at run time — which parameter carries the selection, where each pin's value comes from, which branch a guard selects — is decided once, against the drawn model, before any element changes. The walk that follows has no analysis left to do, so Anvil needs no simulation toolkit and takes no dependency on one.

Why compilation is separate from the run

A shortcut menu has to know whether an item can run before the modeller clicks it. Enablement therefore reads the same compilation the launch reads: an item whose macro has problems is offered and disabled, with the problems in its tooltip, and one whose macro compiles is enabled when the selection fits.

One predicate with two readers is the reason MacroCompiler answers a Compilation — a plan or a list of problems — rather than throwing. The alternative, discovering a defect at launch, would make every menu item look runnable and fail after the modeller committed to it.

One session, one undo entry

The runner opens one session named after the item, runs the whole walk inside it, and closes it once. A modeller who dislikes the result presses undo once, and the model returns to where the run started, however many elements the macro touched.

A failure or a cancelled dialog rolls that session back rather than committing what the run had managed so far. An earlier design stopped a failing automation and committed the partial result, so a modeller was left with half a copied structure and no way back. Four outcomes exist, and each says what the model looks like afterwards:

OutcomeThe modelThe modeller sees
Completedcommittedeach queued notice as an information balloon
Rejecteduntouched, no session openedan error balloon listing the compile problems
Cancelledrolled backnothing
Failedrolled backone error balloon naming the item, the action and the cause

What the expression engine hides

Every step and every automation is a behavior the tool's own expression engine evaluates, which buys one calling convention for Kotlin, Groovy, a query operation and a built-in operation alike. It costs one thing, and the failure design is built around it: ExpressionHelper.call swallows whatever a body throws, logs it, and answers null.

A runner therefore cannot tell a step that failed from a step that returned nothing by catching an exception, because no exception arrives. Anvil closes that gap from the other side. StepFailure and RunCancelled record themselves on the current run when they are constructed, and the step wrapper converts every other exception into a StepFailure naming the step. After each call the runner reads the run's context: a failure recorded there ends the run, and a null with no failure recorded is a step that returned nothing.

StepsLibraryTest proves the whole path in the tool, by calling the Fail step through the engine and reading the failure back off the run.

Values travel, tokens do not

UML's activity semantics move tokens; a token is consumed when it is read. Anvil copies a value to every outgoing object flow instead, which makes a fan-out ordinary: Copy.copy feeding both a rename and a diagram lookup needs no fork node, and a modeller draws two flows out of one pin.

The compiler pays for that convenience by proving something a token machine would discover at run time. A value consumed after a merge must be produced on every path that reaches the merge, or the walk would read a pin nothing wrote. That proof is why Control flow is acyclic and complete looks at dominance rather than only at reachability.

Control flow orders the actions and object flow carries the values, and the two jobs stay separate. Ordering by data flow alone was considered and set aside: a macro that mixes both reads two ways, and the modeller cannot see which one the interpreter believes.

Copies and counterparts

copyPasteElement answers the copied root and no mapping, so "open the diagram inside the copy of this template" has nothing to resolve against. The run carries the mapping instead: Copy walks the source and the copy in parallel immediately after the paste, while the two trees are still identical in shape, and records every original-to-copy pair on the run's context. Counterpart reads that map.

Recording the pairs on the run, rather than marking the template, is what survives a rename. An earlier design marked its templates with a stereotype and a key and stripped them afterwards; a rename between the copy and the lookup broke it, and a failed strip left the marker in the modeller's model. A macro that copies the same template twice in one run keeps both copies, and Counterpart answers the one inside the copy it is given.

What is deliberately absent

AbsentWhy
Loops and expansion regionsA collection travels on one pin, so the common case needs no loop; a loop needs a token machine
Fork and joinValues travel to every outgoing flow already, and nothing here runs concurrently
Macros calling macrosA recursive runner, and a second place for a failure to originate
Guards as expressionsCode scattered across edges, and the token context exposed to the expression engine
Rebuilding the menu on every commitTracing every transaction costs more than the F7 a modeller presses after editing a menu
A validation suiteParked: the runner already reports every problem at launch, and Anvil has one macro author

Each row is a decision the design record in the repository argues, and the record states what was set aside beside it.

On this page