Topological order update (#122)

* Implement topological order update algorithm

* Refactoring

* Refactoring

* Track skipping atoms accurately

* Add test cases

* Refactoring

* Support for complex cases of when transitive update is skipped

* Refactoring

* Add more strict testing

* Show all diffs when validation fails

* Fix dev tool cache

* Refactoring

* Update test case to be more strict

* Refactoring

* Add test for topological sort function

Author: ra1028

.github/workflows/test.yml

@@ -51,14 +51,14 @@ jobs:
       - uses: actions/cache@v4
         with:
           path: Tools/bin
-          key: spm-${{ runner.os }}-${{env.DEVELOPER_DIR}}-${{ hashFiles('Package.swift') }}
+          key: spm-${{ runner.os }}-${{env.DEVELOPER_DIR}}-${{ hashFiles('Tools/Package.swift') }}
       - name: Validate lint
         run: make lint
       - name: Validate format
         run: |
           make format
-          if [ -n "$(git status --porcelain)" ]; then git diff --name-only && echo "Make sure that the code is formated by 'make format'."; exit 1; fi
+          if [ -n "$(git status --porcelain)" ]; then git diff && echo "Make sure that the code is formated by 'make format'."; exit 1; fi
       - name: Validate example project
         run: |
           make proj
-          if [ -n "$(git status --porcelain)" ]; then git diff --name-only && echo "Make sure that 'Examples/App.xcodeproj' is formated by 'make proj'."; exit 1; fi
+          if [ -n "$(git status --porcelain)" ]; then git diff && echo "Make sure that 'Examples/App.xcodeproj' is formated by 'make proj'."; exit 1; fi

Makefile

@@ -4,7 +4,7 @@ SWIFT_FILE_PATHS = Package.swift Tools/Package.swift Sources Tests Examples
 
 .PHONY: proj
 proj:
-	SWIFT_PACKAGE_RESOURCES=.build/checkouts/XcodeGen/SettingPresets $(TOOL) xcodegen -s Examples/project.yml
+	SWIFT_PACKAGE_RESOURCES=Tools/.build/checkouts/XcodeGen/SettingPresets $(TOOL) xcodegen -s Examples/project.yml
 
 .PHONY: format
 format:

Sources/Atoms/Core/Loader/AtomLoader.swift

@@ -18,18 +18,18 @@ public protocol AtomLoader {
 
     /// Returns a boolean value indicating whether it should notify updates downstream
     /// by checking the equivalence of the given old value and new value.
-    func shouldUpdate(newValue: Value, oldValue: Value) -> Bool
+    func shouldUpdateTransitively(newValue: Value, oldValue: Value) -> Bool
 
-    /// Performs atom update.
-    func performUpdate(_ body: () -> Void)
+    /// Performs transitive update for dependent atoms.
+    func performTransitiveUpdate(_ body: () -> Void)
 }
 
 public extension AtomLoader {
-    func shouldUpdate(newValue: Value, oldValue: Value) -> Bool {
+    func shouldUpdateTransitively(newValue: Value, oldValue: Value) -> Bool {
         true
     }
 
-    func performUpdate(_ body: () -> Void) {
+    func performTransitiveUpdate(_ body: () -> Void) {
         body()
     }
 }

Sources/Atoms/Core/Loader/ModifiedAtomLoader.swift

@@ -27,13 +27,13 @@ public struct ModifiedAtomLoader<Node: Atom, Modifier: AtomModifier>: AtomLoader
 
     /// Returns a boolean value indicating whether it should notify updates downstream
     /// by checking the equivalence of the given old value and new value.
-    public func shouldUpdate(newValue: Value, oldValue: Value) -> Bool {
-        modifier.shouldUpdate(newValue: newValue, oldValue: oldValue)
+    public func shouldUpdateTransitively(newValue: Value, oldValue: Value) -> Bool {
+        modifier.shouldUpdateTransitively(newValue: newValue, oldValue: oldValue)
     }
 
-    /// Performs atom update.
-    public func performUpdate(_ body: () -> Void) {
-        modifier.performUpdate(body)
+    /// Performs transitive update for dependent atoms.
+    public func performTransitiveUpdate(_ body: () -> Void) {
+        modifier.performTransitiveUpdate(body)
     }
 }
 

Sources/Atoms/Core/StoreContext.swift

@@ -83,7 +83,7 @@ internal struct StoreContext {
         let key = AtomKey(atom, scopeKey: scopeKey)
 
         if let cache = lookupCache(of: atom, for: key) {
-            update(atom: atom, for: key, newValue: value, cache: cache)
+            update(atom: atom, for: key, newValue: value, oldValue: cache.value)
         }
     }
 
@@ -95,7 +95,7 @@ internal struct StoreContext {
 
         if let cache = lookupCache(of: atom, for: key) {
             let newValue = mutating(cache.value, body)
-            update(atom: atom, for: key, newValue: newValue, cache: cache)
+            update(atom: atom, for: key, newValue: newValue, oldValue: cache.value)
         }
     }
 
@@ -127,9 +127,9 @@ internal struct StoreContext {
         let scopeKey = lookupScopeKey(of: atom, isScopedOverriden: override?.isScoped ?? false)
         let key = AtomKey(atom, scopeKey: scopeKey)
         let cache = getCache(of: atom, for: key, override: override)
-        let isNewSubscription = subscriber.subscribingKeys.insert(key).inserted
+        let isNewSubscription = subscriber.subscribing.insert(key).inserted
 
-        store.state.subscriptions[key, default: [:]].updateValue(subscription, forKey: subscriber.key)
+        store.state.subscriptions[key, default: [:]][subscriber.key] = subscription
         subscriber.unsubscribe = { keys in
             unsubscribe(keys, for: subscriber.key)
         }
@@ -164,7 +164,7 @@ internal struct StoreContext {
 
         // Notify update unless it's cancelled or terminated by other operations.
         if !Task.isCancelled && !context.isTerminated {
-            update(atom: atom, for: key, newValue: value, cache: cache)
+            update(atom: atom, for: key, newValue: value, oldValue: cache.value)
         }
 
         return value
@@ -186,7 +186,7 @@ internal struct StoreContext {
 
         // Notify update unless it's cancelled or terminated by other operations.
         if !Task.isCancelled && !transaction.isTerminated {
-            update(atom: atom, for: key, newValue: value, cache: cache)
+            update(atom: atom, for: key, newValue: value, oldValue: cache.value)
         }
 
         return value
@@ -201,7 +201,7 @@ internal struct StoreContext {
 
         if let cache = lookupCache(of: atom, for: key) {
             let newCache = makeCache(of: atom, for: key, override: override)
-            update(atom: atom, for: key, newValue: newCache.value, cache: cache)
+            update(atom: atom, for: key, newValue: newCache.value, oldValue: cache.value)
         }
     }
 
@@ -233,7 +233,7 @@ internal struct StoreContext {
         let scopeKey = lookupScopeKey(of: atom, isScopedOverriden: override?.isScoped ?? false)
         let key = AtomKey(atom, scopeKey: scopeKey)
 
-        subscriber.subscribingKeys.remove(key)
+        subscriber.subscribing.remove(key)
         unsubscribe([key], for: subscriber.key)
     }
 
@@ -327,7 +327,7 @@ private extension StoreContext {
             coordinator: state.coordinator
         ) { newValue in
             if let cache = lookupCache(of: atom, for: key) {
-                update(atom: atom, for: key, newValue: newValue, cache: cache)
+                update(atom: atom, for: key, newValue: newValue, oldValue: cache.value)
             }
         }
     }
@@ -336,43 +336,103 @@ private extension StoreContext {
         atom: Node,
         for key: AtomKey,
         newValue: Node.Loader.Value,
-        cache: AtomCache<Node>
+        oldValue: Node.Loader.Value
     ) {
-        let oldValue = cache.value
+        store.state.caches[key] = AtomCache(atom: atom, value: newValue)
 
-        store.state.caches[key] = mutating(cache) {
-            $0.value = newValue
+        // Check whether if the dependent atoms should be updated transitively.
+        guard atom._loader.shouldUpdateTransitively(newValue: newValue, oldValue: oldValue) else {
+            return
         }
 
-        guard atom._loader.shouldUpdate(newValue: newValue, oldValue: oldValue) else {
-            return
+        // Perform side effects first.
+        let state = getState(of: atom, for: key)
+        let context = AtomCurrentContext(store: self, coordinator: state.coordinator)
+        atom.updated(newValue: newValue, oldValue: oldValue, context: context)
+
+        // Calculate topological order for updating downstream efficiently.
+        let (edges, redundants) = topologicalSort(key: key, store: store)
+        var skippedDependencies = Set<AtomKey>()
+
+        // Updates the given atom.
+        func update(for key: AtomKey, cache: some AtomCacheProtocol) {
+            let override = lookupOverride(of: cache.atom)
+            let newCache = makeCache(of: cache.atom, for: key, override: override)
+
+            // Check whether if the dependent atoms should be updated transitively.
+            guard cache.atom._loader.shouldUpdateTransitively(newValue: newCache.value, oldValue: cache.value) else {
+                // Record the atom to avoid downstream from being update.
+                skippedDependencies.insert(key)
+                return
+            }
+
+            // Perform side effects before updating downstream.
+            let state = getState(of: cache.atom, for: key)
+            let context = AtomCurrentContext(store: self, coordinator: state.coordinator)
+            cache.atom.updated(newValue: newCache.value, oldValue: cache.value, context: context)
         }
 
-        atom._loader.performUpdate {
-            // Notifies update to view subscriptions first.
-            if let subscriptions = store.state.subscriptions[key] {
-                for subscription in ContiguousArray(subscriptions.values) {
-                    subscription.update()
-                }
+        // Performs update of the given atom with the dependency's context.
+        func performUpdate(for key: AtomKey, cache: some AtomCacheProtocol, dependency: some Atom) {
+            dependency._loader.performTransitiveUpdate {
+                update(for: key, cache: cache)
             }
+        }
 
-            // Notifies update to downstream atoms.
-            if let children = store.graph.children[key] {
-                for child in ContiguousArray(children) {
-                    // Reset the atom value and then notifies downstream atoms.
-                    if let cache = store.state.caches[child] {
-                        reset(cache.atom)
-                    }
-                }
+        // Performs update of the given subscription with the dependency's context.
+        func performUpdate(subscription: Subscription, dependency: some Atom) {
+            dependency._loader.performTransitiveUpdate(subscription.update)
+        }
+
+        func validEdge(_ edge: Edge) -> Edge? {
+            // Do not transitively update atoms that have dependency recorded not to update downstream.
+            guard skippedDependencies.contains(edge.from) else {
+                return edge
             }
 
-            // Notify value update to observers.
-            notifyUpdateToObservers()
+            // If the topological sorting has marked the vertex as a redundant, the update still performed.
+            guard let fromKey = redundants[edge.to]?.first(where: { !skippedDependencies.contains($0) }) else {
+                return nil
+            }
 
-            let state = getState(of: atom, for: key)
-            let context = AtomCurrentContext(store: self, coordinator: state.coordinator)
-            atom.updated(newValue: newValue, oldValue: oldValue, context: context)
+            // Convert edge's `from`, which represents a dependency atom, to a non-skipped one to
+            // change the update transaction context (e.g. animation).
+            return Edge(from: fromKey, to: edge.to)
+        }
+
+        // Perform transitive update for dependent atoms ahead of notifying updates to subscriptions.
+        for edge in edges {
+            switch edge.to {
+            case .atom(let key):
+                guard let edge = validEdge(edge) else {
+                    // Record the atom to avoid downstream from being update.
+                    skippedDependencies.insert(key)
+                    continue
+                }
+
+                let cache = store.state.caches[key]
+                let dependencyCache = store.state.caches[edge.from]
+
+                if let cache, let dependencyCache {
+                    performUpdate(for: key, cache: cache, dependency: dependencyCache.atom)
+                }
+
+            case .subscriber(let key):
+                guard let edge = validEdge(edge) else {
+                    continue
+                }
+
+                let subscription = store.state.subscriptions[edge.from]?[key]
+                let dependencyCache = store.state.caches[edge.from]
+
+                if let subscription, let dependencyCache {
+                    performUpdate(subscription: subscription, dependency: dependencyCache.atom)
+                }
+            }
         }
+
+        // Notify the observers after all updates are completed.
+        notifyUpdateToObservers()
     }
 
     func unsubscribe<Keys: Sequence<AtomKey>>(_ keys: Keys, for subscriberKey: SubscriberKey) {

Sources/Atoms/Core/Subscriber.swift

@@ -10,9 +10,9 @@ internal struct Subscriber {
         self.key = SubscriberKey(token: state.token)
     }
 
-    var subscribingKeys: Set<AtomKey> {
-        get { state?.subscribingKeys ?? [] }
-        nonmutating set { state?.subscribingKeys = newValue }
+    var subscribing: Set<AtomKey> {
+        get { state?.subscribing ?? [] }
+        nonmutating set { state?.subscribing = newValue }
     }
 
     var unsubscribe: ((Set<AtomKey>) -> Void)? {

Sources/Atoms/Core/SubscriberState.swift

@@ -1,12 +1,12 @@
 @MainActor
 final class SubscriberState {
     let token = SubscriberKey.Token()
-    var subscribingKeys = Set<AtomKey>()
+    var subscribing = Set<AtomKey>()
     var unsubscribe: ((Set<AtomKey>) -> Void)?
 
     init() {}
 
     deinit {
-        unsubscribe?(subscribingKeys)
+        unsubscribe?(subscribing)
     }
 }

Sources/Atoms/Core/TopologicalSort.swift

@@ -0,0 +1,72 @@
+internal enum Vertex: Hashable {
+    case atom(key: AtomKey)
+    case subscriber(key: SubscriberKey)
+}
+
+internal struct Edge: Hashable {
+    let from: AtomKey
+    let to: Vertex
+}
+
+/// DFS topological sorting.
+@MainActor
+internal func topologicalSort(key: AtomKey, store: AtomStore) -> (
+    edges: ReversedCollection<[Edge]>,
+    redundants: [Vertex: [AtomKey]]  // key = vertex, value = dependencies
+) {
+    var trace = Set<Vertex>()
+    var edges = [Edge]()
+    var redundants = [Vertex: [AtomKey]]()
+
+    func traverse(key: AtomKey, isRedundant: Bool) {
+        if let children = store.graph.children[key] {
+            for child in ContiguousArray(children) {
+                traverse(key: child, from: key, isRedundant: isRedundant)
+            }
+        }
+
+        if let subscriptions = store.state.subscriptions[key] {
+            for subscriberKey in ContiguousArray(subscriptions.keys) {
+                traverse(key: subscriberKey, from: key, isRedundant: isRedundant)
+            }
+        }
+    }
+
+    func traverse(key: AtomKey, from fromKey: AtomKey, isRedundant: Bool) {
+        let vertex = Vertex.atom(key: key)
+        let isRedundant = isRedundant || trace.contains(vertex)
+
+        trace.insert(vertex)
+
+        // Do not stop traversing downstream even when edges are already traced
+        // to analyze the redundant edges later.
+        traverse(key: key, isRedundant: isRedundant)
+
+        if isRedundant {
+            redundants[vertex, default: []].append(fromKey)
+        }
+        else {
+            let edge = Edge(from: fromKey, to: vertex)
+            edges.append(edge)
+        }
+    }
+
+    func traverse(key: SubscriberKey, from fromKey: AtomKey, isRedundant: Bool) {
+        let vertex = Vertex.subscriber(key: key)
+        let isRedundant = isRedundant || trace.contains(vertex)
+
+        trace.insert(vertex)
+
+        if isRedundant {
+            redundants[vertex, default: []].append(fromKey)
+        }
+        else {
+            let edge = Edge(from: fromKey, to: vertex)
+            edges.append(edge)
+        }
+    }
+
+    traverse(key: key, isRedundant: false)
+
+    return (edges: edges.reversed(), redundants: redundants)
+}

Sources/Atoms/Modifier/AnimationModifier.swift

@@ -70,8 +70,8 @@ public struct AnimationModifier<T>: AtomModifier {
         value
     }
 
-    /// Performs atom update.
-    public func performUpdate(_ body: () -> Void) {
+    /// Performs transitive update for dependent atoms.
+    public func performTransitiveUpdate(_ body: () -> Void) {
         withAnimation(animation, body)
     }
 }