From 8ac38578ef24fa92bb94cb41362168b3e42a3375 Mon Sep 17 00:00:00 2001
From: Grigorii Kirgizov <grigorii.kirgizov@jetbrains.com>
Date: Fri, 30 Oct 2020 14:35:14 +0300
Subject: [PATCH] minor: add docs to incremental stages

---
 .../reactor/core/internal/IncrementalStage.kt |  5 ++
 .../core/internal/ProcessingStrategy.kt       | 53 ++++++++++++++++++-
 .../reactor/core/internal/RuleOrdering.kt     |  2 +-
 3 files changed, 58 insertions(+), 2 deletions(-)

diff --git a/reactor/Core/src/jetbrains/mps/logic/reactor/core/internal/IncrementalStage.kt b/reactor/Core/src/jetbrains/mps/logic/reactor/core/internal/IncrementalStage.kt
index 48f6e367..9dffb368 100644
--- a/reactor/Core/src/jetbrains/mps/logic/reactor/core/internal/IncrementalStage.kt
+++ b/reactor/Core/src/jetbrains/mps/logic/reactor/core/internal/IncrementalStage.kt
@@ -60,6 +60,11 @@ internal class InvalidationStage(
 
     fun receive(invalid: Iterable<Justified>) { invalidJustifications.addAll(invalid) }
 
+    /**
+     * Invalidates next chunk, if needed.
+     * Doesn't remove the [Chunk] from the [Journal].
+     * Returns [true] if chunk is invalidated and must be removed.
+     */
     fun onNext(reader: ChunkReader): Boolean {
         val chunk = reader.next
         if (chunk is MatchJournal.MatchChunk && chunk.dependsOnAny(invalidRuleIds)) {
diff --git a/reactor/Core/src/jetbrains/mps/logic/reactor/core/internal/ProcessingStrategy.kt b/reactor/Core/src/jetbrains/mps/logic/reactor/core/internal/ProcessingStrategy.kt
index 5b011a97..dd3debc5 100644
--- a/reactor/Core/src/jetbrains/mps/logic/reactor/core/internal/ProcessingStrategy.kt
+++ b/reactor/Core/src/jetbrains/mps/logic/reactor/core/internal/ProcessingStrategy.kt
@@ -22,24 +22,45 @@ import jetbrains.mps.logic.reactor.program.Constraint
 import jetbrains.mps.logic.reactor.program.IncrementalSpec
 
 /**
- * Facade for incremental processing
+ * Facade interface for incremental processing.
+ * Designates points in program evaluation where incremental processing
+ * must be injected. It also provides an entry point for evaluation.
  */
 internal interface ProcessingStrategy {
 
+    /**
+     * Information returned back from incremental processing session.
+     */
     fun invalidatedFeedback(): FeedbackKeySet
 
+    /**
+     * Entry point for processing session.
+     */
     fun run(processing: ConstraintsProcessing, controller: Controller, main: Constraint): FeedbackStatus
 
+    /**
+     * Pre-process accepted match before general processing in [Controller.processBody].
+     */
     fun processMatch(match: RuleMatchEx)
 
+    /**
+     * Processes list of matches on active [Occurrence].
+     * Should return a filtered [matches] list.
+     */
     fun processOccurrenceMatches(active: Occurrence, matches: List<RuleMatchEx>): List<RuleMatchEx>
 }
 
 
+/**
+ * Default non-incremental processing with stubs.
+ */
 internal class NonIncrementalProcessing: ProcessingStrategy {
 
     override fun invalidatedFeedback(): FeedbackKeySet = emptySet()
 
+    /**
+     * Simply redirects evaluation to [Controller].
+     */
     override fun run(processing: ConstraintsProcessing, controller: Controller, main: Constraint) =
         controller.activate(main)
 
@@ -49,6 +70,24 @@ internal class NonIncrementalProcessing: ProcessingStrategy {
 }
 
 
+/**
+ * Facade implementation for incremental processing algorithm.
+ *
+ * It includes 4 stages that operate on [MatchJournalImpl.Cursor].
+ * Stages are:
+ *  - [InvalidationStage]
+ *  - [AdditionStage]
+ *  - [PostponeMatchesStage]
+ *  - [ContinueOccurrencesStage]
+ *
+ * Main loop [run] defines relations between stages.
+ * After invalidation and addition control flow is passed to
+ * general processing in [Controller] & [ConstraintsProcessing].
+ *
+ * Methods [processMatch] & [processOccurrenceMatches] serve as
+ * a bridge back from [ConstraintsProcessing] to specific stages
+ * in [IncrementalProcessing].
+ */
 internal class IncrementalProcessing(
     override val ispec: IncrementalSpec,
     val journal: MatchJournal,
@@ -127,6 +166,17 @@ internal class IncrementalProcessing(
 }
 
 
+/**
+ * Very restricted incremental strategy for processing program preamble.
+ *
+ * Includes 2 stages:
+ * - [AdditionStage] which adds potential matches given occurrences from preamble
+ * - [ContinueOccurrencesStage] which actually evaluates them
+ *
+ * Journal invalidation and injected intermediate processing with
+ * [processMatch] & [processOccurrenceMatches] are not needed for this.
+ * So this strategy is very close to the default [NonIncrementalProcessing].
+ */
 internal class PreambleProcessing(
     override val ispec: IncrementalSpec,
     val journal: MatchJournal,
@@ -165,6 +215,7 @@ internal class PreambleProcessing(
     }
 }
 
+
 private fun ContinueOccurrencesStage.runContinued(processing: ConstraintsProcessing, controller: Controller, chunkReader: ChunkReader): FeedbackStatus {
     var status: FeedbackStatus = FeedbackStatus.NORMAL()
     val parentChunk = processing.parentChunk()
diff --git a/reactor/Core/src/jetbrains/mps/logic/reactor/core/internal/RuleOrdering.kt b/reactor/Core/src/jetbrains/mps/logic/reactor/core/internal/RuleOrdering.kt
index 5ee2cf60..94ff4afb 100644
--- a/reactor/Core/src/jetbrains/mps/logic/reactor/core/internal/RuleOrdering.kt
+++ b/reactor/Core/src/jetbrains/mps/logic/reactor/core/internal/RuleOrdering.kt
@@ -39,7 +39,7 @@ internal class RuleOrdering(order: Iterable<Rule>): ComparatorExt<Rule> {
     private fun orderOf(rule: Rule): Int? = ruleOrder[rule.uniqueTag()]
 
     private fun orderOfThrow(rule: Rule): Int = when (val res = orderOf(rule)) {
-        null -> throw IllegalStateException("Compared rule ($rule) must be present in rule index!")
+        null -> throw IllegalStateException("Compared rule (${rule.uniqueTag()}) must be present in rule index!")
         else -> res
     }
 }