Add sequence diagrams for debug API

Author: object-Object

plantuml/debug_api/_base.puml

@@ -0,0 +1,29 @@
+skinparam style strictuml
+skinparam stereotypePosition bottom
+skinparam actorStyle awesome
+
+actor User
+
+!if $debuggee != %false()
+participant Debuggee [
+    Debuggee
+    //(eg. spell circle)//
+]
+!endif
+
+participant DebugEnv << DebugEnvironment >> [
+    ""debugEnv""
+]
+
+participant API [
+    ""HexDebugCoreAPI""
+]
+
+participant Adapter [
+    Debug Adapter
+]
+
+participant Debugger [
+    Debugger
+    //("debug thread")//
+]

plantuml/debug_api/initialization.puml

@@ -0,0 +1,47 @@
+@startuml
+
+!include ./_base.puml
+
+title Initialization
+
+User ->> Debuggee **: start debugging
+activate Debuggee
+    Debuggee -> DebugEnv **: create
+    activate DebugEnv
+    return
+
+    Debuggee -> API ++: ""createDebugThread(debugEnv, threadId)""
+        API -> Adapter ++: create thread
+            Adapter -> Debugger **: create
+            activate Debugger
+            return
+
+            Adapter ->> User: event: thread started
+        return
+    return
+
+    Debuggee ->> Debuggee: start
+
+    ...
+
+    Debuggee -> Debuggee: pause
+
+    Debuggee -> API ++: ""startDebuggingIotas(debugEnv, ...)""
+    note left
+        this can happen immediately,
+        or after a delay; eg. a circle
+        would create the thread when
+        the impetus is activated, but
+        wait to call this method until
+        a slate is reached
+    end note
+        API -> Adapter ++: start executing
+            Adapter -> Debugger ++: start executing
+            return stopped on entry
+
+            Adapter ->> User: event: stopped on entry
+        return
+    return
+deactivate Debuggee
+
+@enduml

plantuml/debug_api/nested.puml

@@ -0,0 +1,56 @@
+@startuml
+
+!$debuggee = %false()
+!include ./_base.puml
+
+title Nested Debugging
+
+participant Debuggee2 [
+    Debuggee #2
+    //(eg. cassette)//
+]
+
+participant Debugger2 [
+    Debugger #2
+]
+
+User ->> Adapter ++: request: step
+    Adapter -> DebugEnv ++: ""isCasterInRange()""
+    return true
+
+    Adapter -> Debugger ++: step
+        Debugger -> Debugger ++: execute next iota
+            Debugger -> Debuggee2 **: create
+            activate Debuggee2
+                Debuggee2 -> API ++: ""createDebugThread(debugEnv, threadId)""
+                    API -> Adapter ++: create thread
+                        Adapter -> Debugger2 **: create
+                        activate Debugger2
+                        return
+
+                        Adapter ->> User: event: thread started
+                    return
+                return
+
+                Debuggee2 ->> Debuggee2: start
+            return
+        return
+    return stopped on step
+
+    Adapter ->> User: event: stopped on step
+deactivate Adapter
+
+...
+
+Debuggee2 -> Debuggee2 ++: pause
+    Debuggee2 -> API ++: ""startDebuggingIotas(debugEnv, ...)""
+        API -> Adapter ++: start executing
+            Adapter -> Debugger2 ++: start executing
+            return stopped on entry
+
+            Adapter ->> User: event: stopped on entry
+        return
+    return
+deactivate Debuggee2
+
+@enduml

plantuml/debug_api/stepping.puml

@@ -0,0 +1,62 @@
+@startuml
+
+!include ./_base.puml
+
+title Stepping
+
+==Step within current iota list==
+
+User ->> Adapter ++: request: step forward
+    Adapter -> DebugEnv ++: ""isCasterInRange()""
+    return whether the caster is close\nenough to the debuggee
+
+    alt caster in range
+        Adapter -> Debugger ++: step
+            Debugger -> Debugger ++: execute next iota
+                opt pattern prints a message
+                    Debugger -> DebugEnv ++: ""printDebugMessage(...)""
+                        DebugEnv -> API ++: ""printDebugMessage(...)""
+                            API ->> User: event: print to output
+                        return
+                    return
+                end
+            return
+        return stopped on step
+        Adapter ->> User: event: stopped on step
+    else caster out of range
+        Adapter ->> User: error: out of range
+    end
+deactivate Adapter
+
+==Step out of current iota list==
+
+User ->> Adapter ++: request: step over final iota
+    Adapter -> DebugEnv ++: ""isCasterInRange()""
+    return ""true""
+
+    Adapter -> Debugger ++: step
+        Debugger -> Debugger: execute next (final) iota
+
+        Debugger -> DebugEnv ++: ""resume(env, image, resolutionType)""
+            DebugEnv ->> Debuggee ++: unpause
+        DebugEnv --> Debugger --: ""true""
+    Debugger --> Adapter --: resumed
+
+    Adapter ->> User: event: continued
+deactivate Adapter
+
+...
+
+Debuggee -> Debuggee: pause
+
+Debuggee -> API ++: ""startDebuggingIotas(...)""
+    API -> Adapter ++: start executing
+        Adapter -> Debugger ++: start executing
+        return stopped on step
+
+        Adapter ->> User: event: stopped on step
+    return
+return
+deactivate Debuggee
+
+@enduml

plantuml/debug_api/stopping.puml

@@ -0,0 +1,44 @@
+@startuml
+
+!include ./_base.puml
+
+title Stopping/Restarting
+
+==Stopping==
+
+User ->> Adapter ++: request: stop
+    Adapter -> DebugEnv ++: ""isCasterInRange()""
+    return true
+
+    Adapter ->> User: event: thread exited
+
+    Adapter -> Debugger !!: remove
+
+    Adapter -> DebugEnv ++: ""terminate()""
+        DebugEnv ->> Debuggee !!: terminate
+    return
+deactivate Adapter
+
+==Restarting==
+
+User ->> Adapter ++: request: restart
+    Adapter -> DebugEnv ++: ""isCasterInRange()""
+    return true
+
+    Adapter -> Debugger !!: remove
+
+    Adapter -> DebugEnv ++: ""restart(threadId)""
+        DebugEnv ->> Debuggee: restart
+
+        DebugEnv -> API ++: ""createDebugThread(debugEnv, threadId)""
+            API -> Adapter ++: create thread
+                Adapter -> Debugger ++: create
+                return
+
+                Adapter ->> User: event: thread started
+            return
+        return
+    return
+deactivate Adapter
+
+@enduml

plantuml/debug_api/terminating.puml

@@ -0,0 +1,58 @@
+@startuml
+
+!include ./_base.puml
+
+title Terminating
+
+==Terminating via ""resume()""==
+
+User ->> Adapter ++: request: continue
+    Adapter -> DebugEnv ++: ""isCasterInRange()""
+    return true
+
+    Adapter -> Debugger ++: continue
+        Debugger -> Debugger: execute all iotas
+
+        Debugger -> DebugEnv ++: ""resume(env, image, resolutionType)""
+        return ""false""
+    return unable to resume
+
+    Adapter ->> User: event: thread exited
+
+    Adapter -> Debugger !!: remove
+
+    Adapter -> DebugEnv ++: ""terminate()""
+        DebugEnv ->> Debuggee !!: terminate
+    return
+deactivate Adapter
+
+==Terminating via API==
+
+Debuggee -> API ++: ""terminateDebugThread(debugEnv)""
+activate Debuggee
+    API -> Adapter ++: terminate thread
+        Adapter ->> User: event: thread exited
+
+        Adapter -> Debugger !!: remove
+
+        Adapter -> DebugEnv ++: ""terminate()""
+            DebugEnv ->> Debuggee !!: terminate
+        return
+    return
+return
+deactivate Debuggee
+
+==Removing via API==
+
+Debuggee -> API ++: ""removeDebugThread(debugEnv)""
+activate Debuggee
+    API -> Adapter ++: terminate thread
+        Adapter ->> User: event: thread exited
+
+        Adapter -> Debugger !!: remove
+    return
+return
+
+Debuggee -> Debuggee !!: terminate
+
+@enduml