Inside the Attribute Graph

The code, the app, the debugger

Start here. This is one view, the app it makes, and a debugger stopped inside SwiftUI while that app runs. The numbers in the comments are attributes: the ids AttributeGraph gave the nodes it built for this view. The pages after this one explain what they are and what happens to them.

 1  struct Trip: View { 2      // node 800 · your struct, as SwiftUI stores it (96 bytes) 3      @State private var nights = 3        // signal 3032 4      @State private var city = "Lisbon"   // signal 3096 5      @State private var favorite = false  // signal 3124 6   7      // node 3152 · runs body; reads 624, 800, 3032, 3096, 3124 8      var body: some View { 9          VStack(spacing: 16) {10              // 3216 and 3256 read what body returns, then11              // 7 more nodes down to 4456, the root display list12              Text("\(city), \(nights) nights, \(favorite)")13              // a tap ends in AGGraphInvalidateValue(the signal)14              Text("+1 night").onTapGesture { nights += 1 }15              Text("favorite").onTapGesture { favorite.toggle() }16              Text("nights = 3").onTapGesture { nights = 3 }17          }18      }19  }

Where the top row comes from

The five nodes on top have no inputs: nothing in the graph feeds them. They are the graph's inputs, external nodes that SwiftUI writes from outside. In this window there are 26 of them, among them the environment (576), the time (536), the root origin and size (856, 904) and the safe-area insets (1080). Trip is the root view in these dumps, so its struct, 800, is one of those: NSHostingView writes it with the struct it was given, and no node sits above it.

A view inside a parent looks different, and this is the real graph of one. Planner is the root; two Editor children get $nights. The parent's body node, 3096, holds the children's structs inside its value, the VStack's tuple. Each child's body node reads 3096 directly. That is what sits above a nested view: its parent's body node, not a node of its own.

struct Planner: View {
    @State private var nights = 3          // signal 3032, read by all three bodies
    var body: some View {                  // node 3096 · its value holds both Editor structs
        VStack {
            Text("\(nights) nights")
            Editor(name: "A", nights: $nights)   // body node 3256 reads 3096
            Editor(name: "B", nights: $nights)   // body node 3336 reads 3096
        }
    }
}
struct Editor: View {
    let name: String
    @Binding var nights: Int
    var body: some View {
        Text("\(name): \(nights)")
    }
}

Below, the app on the left is running. Tap something in it and the debugger on the right stops at each breakpoint in the real call order, with the stack, the variables and the graph's flags at that moment. The six breakpoints that are on are the ones in the Xcode project; switch on the others to stop everywhere.

Tap something in the app.

What's real and what's tidied. The stops, their order and the call stacks are the ones lldb recorded; the values are cleaned up for reading. The node numbers and flags are from the dumps of the one-Text Trip on page 3; the three tap targets are the only addition, and the nodes SwiftUI makes for them are left out. Tap gestures are used instead of Buttons because a Button keeps @State of its own and one click writes it five more times.

An attribute is a number

AttributeGraph is the private C++ engine under SwiftUI. Everything it tracks is an attribute, and in code an attribute is nothing but a 32-bit integer, AGAttribute. The node is the record that integer leads to: a rule to run, a value, some flags, and edges.

Attribute and node are two views of one thing. The number is the handle your code holds; the node is the record AttributeGraph keeps for it. The handle is an offset: AttributeGraph keeps all its nodes in one block of memory, in 512-byte pages, and the node lives at start of block + id. The open-source reimplementation spells it out as base + _offset; Apple's AGGraphInvalidateValue passes the id straight through as the node pointer.

Inspect a real attribute

These are the ids from one small window on this Mac. Click one, or type any number.

Where the nodes sit in memory

Each row is one 512-byte page of AttributeGraph's block. A tick marks the first byte of a node; the id is that byte's distance from the start of the block. Click a tick to inspect it. The pages in between hold SwiftUI's other 44 nodes for this window, left out here.

The three kinds

Nodes are aligned, so a real node's offset always ends in binary 00. AttributeGraph uses those two free bits as a tag. The reimplementation's AttributeID.hpp names them, and the first instruction of AGGraphInvalidateValue tests them.

What AGGraphInvalidateValue does with the number

Trimmed from Apple's binary. Three checks, then a jump into the C++ engine with the id passed through as a node pointer.

tst    w0, #0x3                       ; low 2 bits must be 00, else "non-direct attribute id: %u"
adrp   x8, AG::data::_shared_table_bytes
ldr    w9, [x8, #0x18] ; cmp w9, w0   ; id must be inside the block, else "invalid data offset: %u"
and    x9, x0, #0xfffffe00             ; clear the low 9 bits: the start of its 512-byte page
ldr    x8, [x8] ; ldr x8, [x8, x9]     ; the page's record …
ldr    x8, [x8, #0x28]                 ; … which names the graph that owns it, else "no graph: %u"
mov    w1, w0 ; mov x0, x8
b      AG::Graph::value_mark(AG::data::ptr<AG::Node>)   ; a jump, not a call: the id is now the node pointer

What Swift wraps around it

Same trick as key paths. A key path stores a property as a byte offset from the start of its struct. AttributeGraph stores a node as a byte offset from the start of its block. Both get a small, stable number instead of a 64-bit address.

One view, five nodes

A view with three @State properties becomes five nodes: one for the struct, one for the body, and one empty node per @State. Here is the view, and then the graph AttributeGraph wrote out for it.

struct Trip: View {
    @State private var nights = 3
    @State private var city = "Lisbon"
    @State private var favorite = false

    var body: some View {
        Text("\(city), \(nights) nights, \(favorite)")
    }
}

The graph, from AGGraphArchiveJSON

An arrow means "is read by". Click a node for its record. Dashed nodes have no rule: SwiftUI sets their values from outside. Blue nodes are the signals.

Where 3, "Lisbon" and false actually live

Not in any of these nodes. Node 800 holds the struct as the parent built it, so each field is still a .thunk, the closure the @State macro wrapped around your initial value, with no location. The values live in three StoredLocation objects that SwiftUI keeps on the body node's rule. Before it calls your body, SwiftUI copies the struct out of 800 and writes those locations into the copy. A Mirror of self taken inside body shows the result:

__nights: LazyState<Int>
├ _storage: .value(3)                       ← the thunk has run
└ _location: StoredLocation<Int>            ← a class: the reference
   ├ host: GraphHost (a ViewGraph)          ← owns this window's graph
   └ _signal: WeakAttribute<()> = #3032
      └ _details
         ├ identifier: AGAttribute = #3032   ← the zero-byte signal node
         └ seed: 2
__city     … _signal = #3096
__favorite … _signal = #3124

So a @State holds a reference to its location object, and that object holds a weak handle to its own signal node. The struct never holds the body node's number.

struct DynamicBody<Accessor, ThreadFlags> {
    let accessor: Accessor        // knows how to call body
    @Attribute var container     // 800, the Trip struct
    @Attribute var phase         // 624
    var links: _DynamicPropertyBuffer  // 3 boxes, one per @State
    var resetSeed: UInt32
}

private var __nights = State._makeStorage({
    3
})

Node 624, the phase

A 32-bit number SwiftUI sets from outside. Bit 0 is isBeingRemoved; bits 1–31 are resetSeed, a counter. When the counter changes, the body node drops every @State location and starts fresh, which is how SwiftUI can reuse a row's nodes for a different row without leaking its state. _printChanges labels this input @identity and the struct node @self, so ContentView: @self, @identity, __favoritesOnly changed. names three of the inputs you see above.

Modifiers in the graph

A modifier doesn't change a view. It wraps it: each call returns a new value, ModifiedContent<Content, Modifier>, with the view inside and the modifier beside it. The nesting is written out in the type, and AttributeGraph turns every layer into nodes of its own. Here is a chain of four, in a view with nothing else in it, so that Card is the root of the graph.

struct Card: View {
    var body: some View {
        Image(systemName: "photo")
            .resizable()
            .scaledToFill()
            .frame(height: 120)
            .clipShape(RoundedRectangle(cornerRadius: 8))
    }
}

The type after each step, printed with type(of:):

Image("photo")                                    Image
  .resizable()                                    Image   ← no wrapper: a setting inside Image
  .scaledToFill()                                 ModifiedContent<Image, _AspectRatioLayout>
  .frame(height: 120)                             ModifiedContent<ModifiedContent<Image, _AspectRatioLayout>, _FrameLayout>
  .clipShape(RoundedRectangle(cornerRadius: 8))   ModifiedContent<ModifiedContent<ModifiedContent<Image, _AspectRatioLayout>, _FrameLayout>, _ClipEffect<RoundedRectangle>>

Three things to read off that:

• .resizable() is the exception. It's a method on Image that returns another Image, with the setting stored inside. Four modifiers, three ModifiedContent layers.
• Each layer is a struct with two fields, content (everything inside) and modifier. The whole expression is one value, nested like Russian dolls, built from the inside out.
• Order is part of the type. The same four with the clip before the frame give ModifiedContent<ModifiedContent<ModifiedContent<Image, _AspectRatioLayout>, _ClipEffect<…>>, _FrameLayout>, and draw differently: the clip is applied to the image before the frame sizes it.

The graph, from AGGraphArchiveJSON

Card is the root, 800. The window's graph has 64 nodes; these are the 16 the body and its four layers produce. Tap a node: the arrows into it are what it reads, the arrows out of it are who reads it, and everything else fades. The layout column is on the left, the drawing column on the right.

Each layer, inside out

The same nesting runs three ways

• Sizes flow outward, through the layout computers. The frame's (3392) reads the aspect ratio's (3684), which reads the image's (4752). Each asks its child how big it wants to be.
• Positions flow inward, through the geometry nodes. The frame is 300 × 120, centered in the 200-point window at y = 40 (1400). The filled image is 300 × 240, so the frame places it at y = −60 inside itself (3488), which is y = −20 in the window (4120). Those numbers are in the nodes' values.
• Drawing wraps outward, through the display lists. The image's list (4712) goes inside the clip effect's (4980), which RootDisplayList (5184) reads. The clip cuts the 240-point image down to the 120-point frame with rounded corners; its path starts at (300, 60), the first rounded corner.

StaticBody, not DynamicBody. Card has no @State, so its body node is a StaticBody: no signals, no property buffer, nothing to write into the struct before body runs. Add one @State and it becomes the DynamicBody from page 3, with a signal node beside 800.

Edges come from reads

Nobody declares that the body node depends on nights. The edge appears the first time the body node's rule reads the signal, because every read goes through AttributeGraph, and AttributeGraph knows which node is running.

The read function names only the node being read. There's no "reader" parameter:

// OpenAttributeGraph's header for Apple's C call
const AGValue AGGraphGetValue(AGAttribute attribute, AGValueOptions options, AGTypeID type);
AGAttribute   AGGraphGetCurrentAttribute(void);   // "which node is running right now?"

So when 3152 reads 3032, 3152's own code doesn't touch 3032's lists. AttributeGraph does, inside the read: it looks up the current attribute, records the input on the reader and the output on the node read, and returns the value. Both directions are stored, as AG::InputEdge on the reader and AG::OutputEdge on the node read.

Watch the edges form

This is the first run of the Trip body node, in the order lldb saw the calls. Each step is one event; the console shows the trace line and the lists show what each node now records.

Why the edge isn't made when the signal is created

Three reasons, all visible in the trace order:

Two lists on every node

The same trick, by hand, for @Observable

An @Observable property is not a node, so reading it cannot make an edge. SwiftUI gets the same effect around the body. Before the body node's rule runs, it asks AGGraphGetCurrentAttribute for the node's number and opens a list on the thread; the getter the macro wrote adds the observable object's registrar and the key path to that list; and when the body ends, SwiftUI gives each observable object's registrar in the list a closure holding the number, to call AGGraphInvalidateValue on it when the property changes. The six steps, drawn in order, are in the guide:

One write, start to finish

nights += 1 changes nothing in the graph. It stores the value and leaves a note. Later, in the window's layout pass, SwiftUI drains the notes, invalidates one zero-byte node, and AttributeGraph marks everything downstream. Then the marked nodes rerun, inputs first.

The graph was dumped four times during one write: before, right after the write, right after AGGraphInvalidateValue returned, and after body ran. The flags below are those dumps. Step through it.

Two variations

Both were run under the same breakpoints. Press a button to see the trace.

Choose a variation above.

Invalidated, dirty, marked

Push, then pull

Two targeted walks, not a tour of every view. The push starts from the changed signal and follows read-by edges outward; it only sets bits. The pull starts from what the window needs and follows input edges inward; only marked nodes run. A simplified model, not Apple's code:

// push: once per invalidated signal
func mark(_ node: Node) {
    for reader in node.readBy where !reader.isMarked {
        reader.isMarked = true
        mark(reader)
    }
}

// pull: whenever anyone needs a node's value
func value(of node: Node) -> Value {
    if node.isMarked {
        node.isMarked = false
        node.runRule()          // the rule calls value(of:) on each input it reads
    }
    return node.storedValue
}

The counts bear it out. AG::Graph::update_attribute ran 196 times while a small window first opened, when every node had to be computed once. After one tap changed one @State in a one-Text window, it ran 6 times.

Sharing a signal

A Binding owns no storage. It's a reference to a StoredLocation that some other view owns, and that location carries one signal. So every view holding a binding to it ends up reading the same signal, and the signal's read-by list grows.

struct Planner: View {
    @State private var nights = 3
    var body: some View {
        VStack {
            Editor(name: "A", nights: $nights)   // a Binding to Planner's location
            Editor(name: "B", nights: $nights)
            Summary(nights: nights)              // a copy of the Int (optional below)
        }
    }
}
struct Editor: View {
    let name: String
    @Binding var nights: Int
    var body: some View {
        Text("\(name): \(nights)")
    }
}
struct Summary: View {
    let nights: Int
    var body: some View {
        Text("\(nights) nights")
    }
}

Try it

The node ids and the printed lines are from the real run. Untick the box to make Planner's own body stop reading nights.

What a Binding contains

Three fields: transaction, location and _value. The one that matters is location. Inside Editor, SwiftUI wraps the parent's location once more so the child can track its own wasRead, but it wraps the same object:

Planner's $nights:   location is StoredLocation<Int>            0x…c500
Editor's  _nights:   location is LocationBox<ScopedLocation>    0x…0200
                       which wraps StoredLocation<Int>          0x…c500   ← the same object

Reading nights in Editor calls location.get(). Writing it calls location.set(…), the same StoredLocationBase.set path as page 4: queue, flush, invalidate 3032. And when Editor's body node runs, its @Binding box asks the shared location to update, which reads the signal, and AttributeGraph records the reader as whichever node is running: Editor's.

Three ways to receive a value

Marked is not the same as rerun

With the box unticked, a write still marks Planner's body node, because its @State box reads the signal every run. But SwiftUI then skips calling body. The rule, from OpenSwiftUI's StatePropertyBox.update:

let signalChanged = signal.changedValue()?.changed ?? false
if signalChanged {
    changed = oldLocation == nil || newLocation.wasRead   // only counts if body read it last time
}

wasRead is set by the getter. Reading the storage some other way, through a Mirror for example, doesn't set it, and body doesn't rerun.

Phase, appear and task

body can run as often as it likes; onAppear and .task run once, when the view is inserted, and .task(id:) once per value. The thing that decides is a four-byte input every node reads, the phase, and a rule that queues an action instead of running your closure. This page is a second small program, measured the same way: a window on this Mac, its graph dumped, and breakpoints on SwiftUICore's own functions printing in order with the program's lines.

What a rule is

Three answers, from the loose to the literal.

The protocols

AttributeGraph is a private framework, and no interface for it ships: lldb finds no declaration for either protocol. What the binaries do export is every requirement, as the witness symbols of SwiftUICore's conformances, and every default member, as extension symbols. The declarations below are assembled from those names. Two lines come only from the OpenSwiftUI reimplementation and say so.

// The base both rules refine. All static: these describe the type to the C side,
// and are what the graph's type table entry is built from.
public protocol _AttributeBody {
    static func _destroySelf(_ body: UnsafeMutableRawPointer)
    static var _hasDestroySelf: Bool { get }
    static func _updateDefault(_ body: UnsafeMutableRawPointer)
    static var comparisonMode: AGComparisonMode { get }
    static var flags: AGAttributeTypeFlags { get }
}

// A rule that is a pure function of its inputs: you give it a value getter.
public protocol Rule: _AttributeBody {
    associatedtype Value
    static var initialValue: Value? { get }
    var value: Value { get }
}

extension Rule {
    public var attribute: Attribute<Value> { get }      // the node this rule is running in
    public var context: RuleContext<Value> { get }
    public func updateValue()                           // reimplementation: let v = value; Graph.setOutputValue(v)
    public static var initialValue: Value? { get }      // reimplementation: nil
}

// A rule that keeps state between runs and writes its own value.
public protocol StatefulRule: _AttributeBody {
    associatedtype Value
    static var initialValue: Value? { get }
    mutating func updateValue()
}

extension StatefulRule {
    public var attribute: Attribute<Value> { get }
    public var context: RuleContext<Value> { get }
    public var hasValue: Bool { get }
    public var value: Value { get nonmutating set }     // reads and writes the node's value bytes directly
}

// SwiftUICore adds one member to each, for @Observable tracking during a run:
extension Rule {
    func withObservation<T>(observationCenter: ObservationCenter, do body: () throws -> T) rethrows -> T
}
extension StatefulRule {
    func withObservation<T>(observationCenter: ObservationCenter, do body: () throws -> T) rethrows -> T
}

How the two map onto the nodes on these pages:

• ResolvedTextFilter is a Rule: its value getter computes the resolved text, and the default updateValue() stores it. The body stack further down shows that default being called by the thunk from Attribute.init.
• AppearanceEffect and DynamicBody are StatefulRules: they keep state across runs, such as the phase seed they last saw, and their updateValue() writes through value only when there is something to store, which for AppearanceEffect is never, its value being ().
• The five _AttributeBody statics are what the dump's type entries hold: flags is the flags field of each type, comparisonMode decides how the graph tells "changed" from "same" after a run, and _updateDefault is what runs when a node is pulled with no rule of its own.

The dump shows the bytes. Each type entry carries a size, and it is the rule plus the value: node 3096, the body below, is 180 bytes, and MemoryLayout of its value type says 152, so the DynamicBody rule is 28. The Trip body on page 3 was 60: the same 28 and a 32-byte Text. An AppearanceEffect node is 52 bytes with a value of (): all rule, no value. An input node like the phase is the other way round: 4 bytes of value, no rule.

// the dump's type entries for three of this page's nodes
3096  DynamicBody<ViewBodyAccessor<Inner>, MainThreadFlags>   value ModifiedContent<…>   size 180
3320  AppearanceEffect                                        value ()                   size 52
 624  _External                                               value Phase                size 4

Running a rule, then, is AG::Graph::update_attribute finding the node at its offset, reading its type entry, and calling the thunk with a pointer to the struct. The struct reads its inputs through its handles, each read an edge, and writes its result into the value bytes behind it. That is the whole of it: no callbacks, no observers, no list of things to run. A node runs when it is marked and something pulls it.

Phase: one value, two parts

Attribute 624 on every page of this guide is _GraphInputs.Phase: four bytes, read by almost every node of a view. It is not a list of named stages. SwiftUICore's exported symbols for it are init(value:), isBeingRemoved, isInserted, resetSeed, merge(_:), invalid and ==.

In the dumps on these pages its value is always Phase(value: 0): seed zero, not being removed. Writing nights never touched it. That is why page 6's write re-ran body and queued nothing.

onAppear and .task are modifiers

From the SDK's interfaces. onAppear is one line, and .task is a sibling with no body of its own: its node, like the appear node, is built by _makeView.

// SwiftUICore.swiftinterface
public func onAppear(perform action: (() -> Void)? = nil) -> some View {
    return modifier(_AppearanceActionModifier(appear: action, disappear: nil))
}

// SwiftUI.swiftinterface: a modifier with no body(content:)
public struct _TaskModifier: ViewModifier {
    public var action: @Sendable () async -> Void
    public var priority: TaskPriority
}

The program for this page is a view with all three, and one @State:

struct Inner: View {
    @State private var state = 0
    var body: some View {
        Text("state \(state)")
            .onAppear { print("onAppear") }
            .onDisappear { print("onDisappear") }
            .task { print("task") }
    }
}

Its graph, dumped right after the first insertion. The numbers are the dump's. Three AppearanceEffect nodes, one per modifier, and each has exactly two inputs: the phase and the node that carries its modifier. The task's is one step further down, because .task is implemented as a modifier whose own body applies an _AppearanceActionModifier: node 3240 is that body, with a signal of its own, 3208, for the @State that holds the running Task. The two under the body carry onAppear and onDisappear; the dump does not say which is which, so they are labelled in the order they were made.

Hover a node to see its edges. 3736 is the text's resolver, the one node here whose value the window needs: it is what pulls the body.

Four changes, one window

The same program, run under lldb with breakpoints on AppearanceEffect.updateValue, UpdateGroup.enqueueAction and AppearanceEffect.willRemove, each auto-continuing and printing a line. Timers changed the view four ways. Step through: the console is the real trace, lightly trimmed; the graph shows which rules ran.

What is on the stack

The stack under each piece of a view with .onAppear and .task, printed from inside it and demangled. body runs inside a rule, pulled by another rule. The appear closure runs from the queue, after the graph update, inside the host's layout pass. The task closure runs from Swift concurrency, with no graph code above it at all.

Screen.body.getter
ViewBodyAccessor.updateBody(of:changed:)
StaticBody.updateValue()
AG::Graph::UpdateStack::update
AG::Graph::update_attribute
AG::Graph::input_value_ref_slow
AGGraphGetValue
ResolvedTextFilter.updateValue()      ← the pull

closure #1 in Screen.body.getter
UpdateGroup.Action.callAsFunction()
UpdateGroup.dispatchActions()
ViewGraphRootValueUpdater.render(…)
NSHostingView.layout()
AppKit: the layout pass

the task closure
closure #2 in Screen.body.getter
libswift_Concurrency: completeTaskWithClosure

Does body re-run them?

A third program: a root view re-rendered by timers, counters in every closure, and a ScrollView of a thousand lazy cards with an onAppear each, removed before its .task had finished sleeping.

The scroll view's own .task started before any card had appeared, since the lazy rows are made in the next layout pass. And when the cards were removed before its second was up, SwiftUI cancelled the task, Task.sleep threw at once, try? swallowed that, and the print ran early with Task.isCancelled true. Check it after the sleep if the print should only happen for a view still on screen.

The phase changes, and what they run

Why the closure runs from a queue and never inside the rule: it may change state. Changing state while the graph is half-way through computing would invalidate values it is in the middle of using. Run afterwards, any state it changes marks nodes, and the next pass picks them up.