help: add implementation section

hpi-swa-lab · Dec 28, 2023 · 682b6a4 · 682b6a4 · github-actions · Dec 28, 2023
1 parent a5c2073
commit 682b6a4
Show file tree

Hide file tree

Showing 4 changed files with 29 additions and 5 deletions.
diff --git a/packages/TraceDebugger.package/TraceDebuggerHelp.class/class/basicImplementation.st b/packages/TraceDebugger.package/TraceDebuggerHelp.class/class/basicImplementation.st
@@ -0,0 +1,23 @@
+pages - private
+basicImplementation
+	"This method was automatically generated. Edit it using:"
+	"TraceDebuggerHelp edit: #basicImplementation"
+	<generated>
+	^(HelpTopic
+		title: 'Implementation'
+		contents: 
+'How does the TraceDebugger work?
+
+For program tracing, the program is executed in a specialized code simulator that overrides instructions for sending messages (e.g., send, superSend) and for performing side-effects (e.g., popIntoRcvr, primitiveAtPut, push). All message sends are recorded in a tree and all changed object slots are stored in a sparse time-dependent memory structure before they are overwritten. For time-traveling, the tree is traversed using a cursor. For accessing historic objects, a proxy evaluates all messages sent to an object in another specialized simulator (retracing simulator) that emulates historic states for the requested point in time by forwarding read primitives (e.g., pushRcvr, primitiveAt) to the recorded memory. For gathering state changes in the History Explorer efficiently, the query is evaluated in a range retracing simulator with vectorization and fork semantics.
+
+To dive into the implementation details, in addition to the package overview on GitHub, some good starting points might be the class comments in TraceDebugger and TDBCursor.
+
+Current Limitations:
+* High performance. While (sufficiently) fast enough for most small to medium workloads, tracing very compute- or mem-intensive operations may require more time (ex.: Compiler/decompiler invocation: <1s, HTTPS request: <10s, tool building: <5m, complex rendering: minutes up to hours).
+* Not a dataflow analyzer: The TraceDebugger does not track dataflow events (e.g., argument passing) but only state changes.
+* No tracing of external states/events for FFI/OSProcess or custom VM modules.
+* No support for advanced language concepts such as identity forwarding/write barriers.!
+]style[(32 1 879 80 6 55 1 3 13 1 4 9 1 25 17 269 24 101 36 43 41 44)a0b,a0,,a0,Rhttps://github.com/hpi-swa-lab/squeak-tracedebugger;,a0,LTraceDebugger Comment;,,LTraceDebugger Comment;,a0,,LTDBCursor Comment;,a0,,b,,b,,b,,b,!' readStream nextChunkText)
+			key: #basicImplementation;
+			shouldStyle: false;
+			yourself
diff --git a/packages/TraceDebugger.package/TraceDebuggerHelp.class/class/basicLearnMore.st b/packages/TraceDebugger.package/TraceDebuggerHelp.class/class/basicLearnMore.st
@@ -16,12 +16,12 @@ In particular, there are many open issues for further ideas, bugs etc.:
 
 https://github.com/hpi-swa-lab/squeak-tracedebugger/issues
 
-To dive into the implementation details, in addition to the package overview on GitHub, some good starting points might be the class comments in TraceDebugger and TDBCursor.
+To understand the implementation, please read the previous section of this chapter.
 
 If you have any feedback or ideas, please let me know and drop an issue!! You can also do this directly via the window menu of the TraceDebugger. By the way, it is also possible from there to update your installed version or perform some special process-related operations. Last not least, you can also check out some experimental preferences from there.
 
 <#figureWindowMenu>!
-]style[(10 106 51 74 1 58 143 1 3 13 1 4 9 373 4)a0b,a0,Rhttps://github.com/hpi-swa-lab/squeak-tracedebugger;I1,a0,,Rhttps://github.com/hpi-swa-lab/squeak-tracedebugger/issues;I1,a0,LTraceDebugger Comment;,,LTraceDebugger Comment;,a0,,LTDBCursor Comment;,a0,!' readStream nextChunkText)
+]style[(10 106 51 74 1 58 457 4)a0b,a0,Rhttps://github.com/hpi-swa-lab/squeak-tracedebugger;I1,a0,,Rhttps://github.com/hpi-swa-lab/squeak-tracedebugger/issues;I1,a0,!' readStream nextChunkText)
 			key: #basicLearnMore;
 			shouldStyle: false;
 			yourself
diff --git a/packages/TraceDebugger.package/TraceDebuggerHelp.class/class/pages.st b/packages/TraceDebugger.package/TraceDebuggerHelp.class/class/pages.st
@@ -1,4 +1,4 @@
 accessing
 pages
 
-	^ {#introduction. #entryPoints. #structure. #basicNavigation. #advancedNavigation. #findingContexts. #contextFilters. TDBHistoryExplorerHelp asHelpTopic. #scriptingAPIs. #learnMore}
+	^ {#introduction. #entryPoints. #structure. #basicNavigation. #advancedNavigation. #findingContexts. #contextFilters. TDBHistoryExplorerHelp asHelpTopic. #scriptingAPIs. #implementation. #learnMore}
diff --git a/packages/TraceDebugger.package/TraceDebuggerHelp.class/methodProperties.json b/packages/TraceDebugger.package/TraceDebuggerHelp.class/methodProperties.json
@@ -6,8 +6,9 @@
 		"basicContextFilters" : "ct 3/18/2022 20:43",
 		"basicEntryPoints" : "ct 5/11/2022 22:54",
 		"basicFindingContexts" : "ct 3/18/2022 20:32",
+		"basicImplementation" : "ct 12/28/2023 23:49",
 		"basicIntroduction" : "ct 7/31/2022 01:13",
-		"basicLearnMore" : "ct 12/28/2023 21:30",
+		"basicLearnMore" : "ct 12/28/2023 23:51",
 		"basicScriptingAPIs" : "ct 12/28/2023 21:30",
 		"basicSelectorFor:" : "ct 3/18/2022 16:16",
 		"basicStructure" : "ct 12/28/2023 21:29",
@@ -45,7 +46,7 @@
 		"openHelpBrowser" : "ct 3/18/2022 16:17",
 		"openHelpBrowserForEdit" : "ct 3/18/2022 16:15",
 		"openScriptingAPIWorkspace" : "ct 7/31/2022 01:24",
-		"pages" : "ct 7/30/2022 23:07",
+		"pages" : "ct 12/26/2023 20:48",
 		"remoteFigureNamed:" : "ct 4/29/2022 18:25",
 		"resizeWindow:" : "ct 8/1/2022 17:26",
 		"takeScreenshotWithContextMenu:" : "ct 3/18/2022 21:16",