Documentation for pathnode provider optimization in inherit graph

Author: Col-E

recaf-core/src/main/java/software/coley/recaf/services/inheritance/ClassPathNodeProvider.java

@@ -9,12 +9,30 @@
 import java.util.Map;
 import java.util.stream.Stream;
 
+/**
+ * Provider of class path nodes.
+ *
+ * @author xDark
+ */
 sealed interface ClassPathNodeProvider {
-
+	/**
+	 * @param name
+	 * 		Class name to look up.
+	 *
+	 * @return Path node for the class with the given name, or {@code null} if no such class exists in the provider.
+	 */
 	@Nullable
 	ClassPathNode getNode(@Nonnull String name);
 
-	static ClassPathNodeProvider.Cached cache(Workspace workspace) {
+	/**
+	 * Create a cached provider that contains all nodes from the workspace at the time of creation.
+	 *
+	 * @param workspace
+	 * 		Workspace to cache nodes from.
+	 *
+	 * @return Provider that caches all nodes from the workspace at the time of creation.
+	 */
+	static ClassPathNodeProvider.Cached cache(@Nonnull Workspace workspace) {
 		Stream<ClassPathNode> stream = workspace.classesStream();
 		Map<String, ClassPathNode> nodes = new HashMap<>(4096);
 		stream.forEach(classPathNode -> {
@@ -23,15 +41,31 @@ static ClassPathNodeProvider.Cached cache(Workspace workspace) {
 		return new Cached(Map.copyOf(nodes));
 	}
 
-	record FromWorkspace(@Nonnull Workspace workspace) implements ClassPathNodeProvider {
+	/**
+	 * Provider that looks up nodes directly from the workspace.
+	 * This is not recommended for repeated lookups, but it is useful for one-off lookups or when the workspace is expected to be changing frequently.
+	 *
+	 * @param workspace
+	 * 		Workspace to look up nodes from.
+	 */
+	record Live(@Nonnull Workspace workspace) implements ClassPathNodeProvider {
 		@Nullable
 		@Override
 		public ClassPathNode getNode(@Nonnull String name) {
 			return workspace.findClass(name);
 		}
 	}
 
-	record Cached(Map<String, ClassPathNode> nodes) implements ClassPathNodeProvider {
+	/**
+	 * Provider that caches all nodes from the workspace at the time of creation.
+	 * This is recommended for repeated lookups, but it is not suitable for workspaces that are expected to be changing frequently.
+	 *
+	 * @param nodes
+	 * 		Map of class names to their corresponding path nodes. This map is expected to be immutable.
+	 *
+	 * @see #cache(Workspace)
+	 */
+	record Cached(@Nonnull Map<String, ClassPathNode> nodes) implements ClassPathNodeProvider {
 		int size() {
 			return nodes.size();
 		}

recaf-core/src/main/java/software/coley/recaf/services/inheritance/InheritanceGraph.java

@@ -59,7 +59,7 @@ public class InheritanceGraph {
 	 */
 	public InheritanceGraph(@Nonnull Workspace workspace) {
 		this.workspace = workspace;
-		this.workspaceNodeProvider = new ClassPathNodeProvider.FromWorkspace(workspace);
+		this.workspaceNodeProvider = new ClassPathNodeProvider.Live(workspace);
 
 		// Populate map lookups with the initial capacity of the number of classes in the workspace plus a buffer.
 		int classesInWorkspace = workspace.allResourcesStream(false /* dont count internal resource classes */)
@@ -115,9 +115,7 @@ private void refreshChildLookup() {
 		// Repopulate
 		ClassPathNodeProvider.Cached nodeProvider = ClassPathNodeProvider.cache(workspace);
 		Set<ClassInfo> visited = Collections.newSetFromMap(new IdentityHashMap<>(nodeProvider.size() + 1024 /* leeway */));
-		workspace.forEachClass(false, cls -> {
-			populateParentToChildLookup(cls, visited, nodeProvider);
-		});
+		workspace.forEachClass(false, cls -> populateParentToChildLookup(cls, visited, nodeProvider));
 	}
 
 	/**

recaf-core/src/main/java/software/coley/recaf/workspace/model/resource/AgentServerRemoteVmResource.java

@@ -86,14 +86,14 @@ public Map<Integer, JvmClassBundle> getJvmClassloaderBundles() {
 
 	@Nonnull
 	@Override
-	public Stream<JvmClassBundle> jvmClassBundleStream() {
-		return Stream.concat(super.jvmClassBundleStream(), new ArrayList<>(remoteBundleMap.values()).stream());
+	public Iterable<JvmClassBundle> jvmClassBundles() {
+		return Iterables.concat(super.jvmClassBundles(), new ArrayList<>(remoteBundleMap.values()));
 	}
 
 	@Nonnull
 	@Override
-	public Iterable<JvmClassBundle> jvmClassBundles() {
-		return Iterables.concat(super.jvmClassBundles(), new ArrayList<>(remoteBundleMap.values()));
+	public Stream<JvmClassBundle> jvmClassBundleStream() {
+		return Stream.concat(super.jvmClassBundleStream(), new ArrayList<>(remoteBundleMap.values()).stream());
 	}
 
 	@Override

recaf-core/src/main/java/software/coley/recaf/workspace/model/resource/WorkspaceResource.java

@@ -135,19 +135,19 @@ default boolean isEmbeddedResource() {
 	}
 
 	/**
-	 * @return Stream of all immediate JVM class bundles in the resource.
+	 * @return Iterable of all immediate JVM class bundles in the resource.
 	 */
 	@Nonnull
-	default Stream<JvmClassBundle> jvmClassBundleStream() {
-		return of(getJvmClassBundle());
+	default Iterable<JvmClassBundle> jvmClassBundles() {
+		return List.of(getJvmClassBundle());
 	}
 
 	/**
-	 * @return Iterable of all immediate JVM class bundles in the resource.
+	 * @return Stream of all immediate JVM class bundles in the resource.
 	 */
 	@Nonnull
-	default Iterable<JvmClassBundle> jvmClassBundles() {
-		return List.of(getJvmClassBundle());
+	default Stream<JvmClassBundle> jvmClassBundleStream() {
+		return of(getJvmClassBundle());
 	}
 
 	/**