From 2f726cddf0a5130f303a4a8c3ec91bf1117b570d Mon Sep 17 00:00:00 2001
From: Adrien Piquerez <adrien.piquerez@gmail.com>
Date: Tue, 5 Nov 2024 11:36:18 +0100
Subject: [PATCH] Add comments

---
 main-settings/src/main/scala/sbt/Project.scala | 2 ++
 main-settings/src/main/scala/sbt/Scope.scala   | 5 +++++
 main/src/main/scala/sbt/internal/Load.scala    | 2 ++
 3 files changed, 9 insertions(+)

diff --git a/main-settings/src/main/scala/sbt/Project.scala b/main-settings/src/main/scala/sbt/Project.scala
index 3a6a60815..73f455378 100644
--- a/main-settings/src/main/scala/sbt/Project.scala
+++ b/main-settings/src/main/scala/sbt/Project.scala
@@ -337,6 +337,8 @@ object Project:
     [a] => (k: ScopedKey[a]) => ScopedKey(f(k.scope), k.key)
 
   def transform(g: Scope => Scope, ss: Seq[Def.Setting[?]]): Seq[Def.Setting[?]] =
+    // We use caching to avoid creating new Scope instances too many times
+    // Creating a new Scope is CPU expensive because of the uniqueness cache
     val f = mapScope(Util.withCaching(g))
     ss.map(_.mapKey(f).mapReferenced(f))
 
diff --git a/main-settings/src/main/scala/sbt/Scope.scala b/main-settings/src/main/scala/sbt/Scope.scala
index 2dafb4a3f..fb855ef92 100644
--- a/main-settings/src/main/scala/sbt/Scope.scala
+++ b/main-settings/src/main/scala/sbt/Scope.scala
@@ -23,6 +23,8 @@ final case class Scope private (
     task: ScopeAxis[AttributeKey[?]],
     extra: ScopeAxis[AttributeMap]
 ):
+  // Since we use a uniqueness cache we can pre-compute the hashCode for free
+  // It is always going to be used at least once
   override val hashCode = ScalaRunTime._hashCode(this)
 
   def rescope(project: Reference): Scope = copy(project = Select(project))
@@ -43,6 +45,9 @@ final case class Scope private (
 end Scope
 
 object Scope:
+  // We use a global uniqueness cache to avoid duplicating Scope.
+  // At the time of writing, it divides the number of long-living instances by 15
+  // reducing the pressure on the heap, and speed up the loading.
   private val uniquenessCache = TrieMap.empty[Scope, Scope]
 
   def apply(
diff --git a/main/src/main/scala/sbt/internal/Load.scala b/main/src/main/scala/sbt/internal/Load.scala
index d010d233f..7878dd305 100755
--- a/main/src/main/scala/sbt/internal/Load.scala
+++ b/main/src/main/scala/sbt/internal/Load.scala
@@ -274,6 +274,8 @@ private[sbt] object Load {
       finalTransforms(settings0)
     }
     val delegates = timed("Load.apply: config.delegates", log) {
+      // We use caching to avoid creating new Scope instances too many times
+      // Creating a new Scope is CPU expensive because of the uniqueness cache
       Util.withCaching(config.delegates(loaded))
     }
     val (cMap, data) = timed("Load.apply: Def.make(settings)...", log) {