From 2bcde67e1851e4bfd9767a76b3adcde850972b53 Mon Sep 17 00:00:00 2001 From: Daan Vanden Bosch Date: Tue, 1 Nov 2022 14:58:15 +0100 Subject: [PATCH] Renamed LeafDependent.pull to LeafDependent.dependenciesChanged and added some documentation. --- .../phantasmal/cell/CallbackChangeObserver.kt | 4 ++-- .../world/phantasmal/cell/CallbackObserver.kt | 4 ++-- .../world/phantasmal/cell/Dependency.kt | 8 +++++++- .../kotlin/world/phantasmal/cell/Dependent.kt | 20 +++++++++++++------ .../world/phantasmal/cell/MutationManager.kt | 18 ++++++++++------- 5 files changed, 36 insertions(+), 18 deletions(-) diff --git a/cell/src/commonMain/kotlin/world/phantasmal/cell/CallbackChangeObserver.kt b/cell/src/commonMain/kotlin/world/phantasmal/cell/CallbackChangeObserver.kt index cd1b34ff..258ec491 100644 --- a/cell/src/commonMain/kotlin/world/phantasmal/cell/CallbackChangeObserver.kt +++ b/cell/src/commonMain/kotlin/world/phantasmal/cell/CallbackChangeObserver.kt @@ -11,7 +11,7 @@ class CallbackChangeObserver>( // We don't use ChangeObserver because of type system limitations. It would break e.g. // AbstractListCell.observeListChange. private val callback: (E) -> Unit, -) : TrackedDisposable(), Dependent, LeafDependent { +) : TrackedDisposable(), LeafDependent { init { dependency.addDependent(this) @@ -26,7 +26,7 @@ class CallbackChangeObserver>( MutationManager.invalidated(this) } - override fun pull() { + override fun dependenciesChanged() { // See comment above callback property to understand why this is safe. dependency.changeEvent?.let(unsafeCast<(ChangeEvent) -> Unit>(callback)) } diff --git a/cell/src/commonMain/kotlin/world/phantasmal/cell/CallbackObserver.kt b/cell/src/commonMain/kotlin/world/phantasmal/cell/CallbackObserver.kt index a2a403c1..bec61280 100644 --- a/cell/src/commonMain/kotlin/world/phantasmal/cell/CallbackObserver.kt +++ b/cell/src/commonMain/kotlin/world/phantasmal/cell/CallbackObserver.kt @@ -8,7 +8,7 @@ import world.phantasmal.core.disposable.TrackedDisposable class CallbackObserver( private vararg val dependencies: Cell<*>, private val callback: () -> Unit, -) : TrackedDisposable(), Dependent, LeafDependent { +) : TrackedDisposable(), LeafDependent { init { for (dependency in dependencies) { @@ -28,7 +28,7 @@ class CallbackObserver( MutationManager.invalidated(this) } - override fun pull() { + override fun dependenciesChanged() { var changed = false // We loop through all dependencies to ensure they're valid again. diff --git a/cell/src/commonMain/kotlin/world/phantasmal/cell/Dependency.kt b/cell/src/commonMain/kotlin/world/phantasmal/cell/Dependency.kt index 280c9463..03bbe07e 100644 --- a/cell/src/commonMain/kotlin/world/phantasmal/cell/Dependency.kt +++ b/cell/src/commonMain/kotlin/world/phantasmal/cell/Dependency.kt @@ -1,7 +1,13 @@ package world.phantasmal.cell +/** + * This interface is not meant to be implemented by typical application code. + */ interface Dependency { - // TODO: Docs. + /** + * This property is not meant to be accessed from typical application code. The current change + * event for this dependency. Only valid during a mutation. + */ val changeEvent: ChangeEvent? /** diff --git a/cell/src/commonMain/kotlin/world/phantasmal/cell/Dependent.kt b/cell/src/commonMain/kotlin/world/phantasmal/cell/Dependent.kt index ae2f4e96..c185a162 100644 --- a/cell/src/commonMain/kotlin/world/phantasmal/cell/Dependent.kt +++ b/cell/src/commonMain/kotlin/world/phantasmal/cell/Dependent.kt @@ -1,13 +1,14 @@ package world.phantasmal.cell +/** + * This interface is not meant to be implemented by typical application code. + */ interface Dependent { /** - * TODO: Fix documentation. * This method is not meant to be called from typical application code. * * Called whenever a dependency of this dependent might change. Sometimes a dependency doesn't - * know that it will actually change, just that it might change. Always call [dependencyChanged] - * after calling this method. + * know that it will actually change, just that it might change. * * E.g. C depends on B and B depends on A. A is about to change, so it calls * [dependencyInvalidated] on B. At this point B doesn't know whether it will actually change @@ -17,7 +18,14 @@ interface Dependent { fun dependencyInvalidated(dependency: Dependency<*>) } -interface LeafDependent { - // TODO: Sensible name for `pull`. - fun pull() +/** + * This interface is not meant to be implemented by typical application code. + */ +interface LeafDependent : Dependent { + /** + * This method is not meant to be called from typical application code. Called by + * [MutationManager] when invalidation notifications have finished propagating, the current + * outer mutation is ending and leaves should be updated. + */ + fun dependenciesChanged() } diff --git a/cell/src/commonMain/kotlin/world/phantasmal/cell/MutationManager.kt b/cell/src/commonMain/kotlin/world/phantasmal/cell/MutationManager.kt index f9e9b5ae..23488bf3 100644 --- a/cell/src/commonMain/kotlin/world/phantasmal/cell/MutationManager.kt +++ b/cell/src/commonMain/kotlin/world/phantasmal/cell/MutationManager.kt @@ -24,7 +24,7 @@ object MutationManager { private var artificialMutation = false private var dependencyChanging = false - private var pulling = false + private var notifyingLeavesOfChanges = false private val deferredMutations: MutableList<() -> Unit> = mutableListOf() private var applyingDeferredMutations = false @@ -53,7 +53,9 @@ object MutationManager { fun mutationStart() { assert(!dependencyChanging) { "Can't start a mutation while a dependency is changing." } - assert(!pulling) { "Can't start a mutation while pulling." } + assert(!notifyingLeavesOfChanges) { + "Can't start a mutation while notifying leaf dependents of changes." + } if (mutationNestingLevel == 0) { currentMutationId++ @@ -66,17 +68,17 @@ object MutationManager { assert(mutationNestingLevel > 0) { "No mutation was started." } if (mutationNestingLevel == 1) { - assert(!pulling) { "Already pulling." } + assert(!notifyingLeavesOfChanges) { "Already notifying leaf dependents of changes." } try { - pulling = true + notifyingLeavesOfChanges = true for (dependent in invalidatedLeaves) { - dependent.pull() + dependent.dependenciesChanged() } } finally { dependencyChanging = false - pulling = false + notifyingLeavesOfChanges = false mutationNestingLevel-- invalidatedLeaves.clear() applyDeferredMutations() @@ -103,7 +105,9 @@ object MutationManager { fun dependencyChangeStart() { check(!dependencyChanging) { "A cell is already changing." } - assert(!pulling) { "Can't change a cell while pulling." } + assert(!notifyingLeavesOfChanges) { + "Can't change a cell while notifying leaf dependents of changes." + } if (mutationNestingLevel == 0) { mutationStart()