[design-docs]

Rewriting design docs for inter process debugging and rd.
Completely new design doc go inter process logging

Author: Domonion

docs/RD for UnitTestBot.md

@@ -1,5 +1,31 @@
-# RD
-New child process communication involves 3 different things:
+# Multi-process architecture
+
+## Table of content
+- [Overview](#overview)
+- [Lifetimes](#lifetimes)
+	- [Lifetime](#lifetime)
+	- [LifetimeDefinition](#lifetimedefinition)
+- [Rd](#rd)
+- [Rdgen](#rdgen)
+  - [Model DSL](#model-dsl)
+  - [Gradle](#gradle)
+- [UtBot project](#utbot-project)
+  - [IDEA process](#idea-process)
+  - [Engine process](#engine-process)
+  - [Instrumented process](#instrumented-process)
+  - [Commons](#useful)
+
+## Overview
+UtBot consists of 3 different processes: 
+1. `IDEA process` - the one where plugin part executes. Also can be called `plugin process`, `IDE process`. 
+2. `Engine process` - process where unit test generation engine executes.
+3. `InstrumentedProces` - process where concrete execution takes place.
+
+These processes are built on top of [JetBrains.RD](https://github.com/JetBrains/rd). It is crucial to understand 
+this library, so it's better describing it first(as there are no documentation about it in repo;)).
+
+RD is mostly about 3 components:
+
 1. Lifetimes
 2. Rd entities
 3. Rdgen
@@ -21,7 +47,7 @@ And so Lifetime was introduced.
 ### Lifetime:
 ```Lifetime``` is a class, where you can register callbacks and which can be terminated once, thus executing all registered callbacks.
 
-```Lifetime``` is an abstract class, it's inheritor - ```LifetimeDefinition```. The only difference - only ```LifetimeDefinition``` can be terminated. Though all ```Lifetime``` are instances of ```LifetimeDefinition```, there are some conventions:
+```Lifetime``` is an abstract class, it's inheritor - ```LifetimeDefinition```. The only difference - ```LifetimeDefinition``` can be terminated. Though all ```Lifetime``` are instances of ```LifetimeDefinition```, there are some conventions:
 1. Do not cast ```Lifetime``` to ```LifetimeDefinion``` unless you are the one who created ```LifetimeDefinition```.
 2. If you introduce somewhere ```LifetimeDefinition``` - either attach it to another ```Lifetime``` or provide code that terminates it.
 
@@ -100,42 +126,67 @@ DSL:
 
 ## UtBot project
 
-There is another gradle project ```utbot-rd``` which contains model sources in ```rdgenModels``` sources. Look for ```org.utbot.rd.models.ProtocolRoot```.
+There is another gradle project ```utbot-rd``` which contains model sources in ```rdgenModels```.
+Look at [```utbot-rd/src/main/rdgen/org/utbot/rd/models```](../utbot-rd/src/main/rdgen/org/utbot/rd/models)
+
+### IDEA process
+Uses bundled JetBrains JDK. Code in `utbot-intellij` ___must___ be compatible will all JDKs and plugin SDKs, which are used by our officially supported IntellijIDEA versions.
+See [`utbot-intellij/build.gradle.kts`](../utbot-intellij/build.gradle.kts), parts `sinceBuild` and `untilBuild`. 
+
+Starts `Engine process`. Maintains `UtSettings` instance in memory and updates it from IDEA. 
+Other processes ask this process for settings via RD RPC.
+
+### Engine process
+
+`TestCaseGenerator` and `UtBotSymbolicEngine` runs here. Process classpath contains all plugin jars(more precisely - it uses plugin classpath). 
+
+___Must___ run on JDK, which uses project we analyze. Otherwise there will be numerous problems with code analysis, soot, reflection and 
+devirgention of generated code Java API. 
+
+Currently, it is prohibited to run more than 1 generation process simultaneously(something with native libs). 
+However, logging for processes relies on that fact, so they can exclusively write to log file.
+
+IDEA starting point - class [`EngineProcess`](../utbot-intellij/src/main/kotlin/org/utbot/intellij/plugin/process/EngineProcess.kt). 
+Process start file - [`EngineProcessMain`](../utbot-framework/src/main/kotlin/org/utbot/framework/process/EngineProcessMain.kt).
+Starts `Instrumented process`.  
+
+### Instrumented process
+
+Start points at `Engine process`: classes [`InstrumentedProcess`](../utbot-instrumentation/src/main/kotlin/org/utbot/instrumentation/rd/InstrumentedProcess.kt) and [`ConcreteExecutor`](../utbot-instrumentation/src/main/kotlin/org/utbot/instrumentation/ConcreteExecutor.kt). 
+First one is state encapsulation, second is used to implement request logic for concrete execution.
+
+Runs on the same JDK as `Engine process` to erase deviation from `Engine process`. 
+Sometimes might unexpectedly die due concrete execution.
+
+
+### Useful
 
-Usefull:
 1. if you need to use rd somewhere - add following dependencies:
     ```
-    implementation group: 'com.jetbrains.rd', name: 'rd-framework', version: 'actual.version'
+    implementation group: 'com.jetbrains.rd', name: 'rd-framework', version: rdVersion
     
-    implementation group: 'com.jetbrains.rd', name: 'rd-core', version: 'actual.version'
+    implementation group: 'com.jetbrains.rd', name: 'rd-core', version: rdVersion
     ```
-2. There are some usefull classes to work with processes & rd:
+2. There are some useful classes in `utbot-rd` to work with processes & rd:
 	- ```LifetimedProcess``` - binds ```Lifetime``` to process. If process dies - lifetime terminates and vice versa. You can terminate lifetime manually - this will destroy process.
-	- ```ProcessWithRdServer``` - also starts Rd server and waits for connection.
-	- ```UtInstrumentationProcess``` - encapsulates logic for preparing instrumented process for executing arbitary commands. Exposes ```protocolModel``` for communicating with instrumented process.
-	- ```ConcreteExecutor``` is convenient wrapper for executing commands and managing resources.
-3. How child communication works:
-	- Choosing free port
-	- Creating instrumented process, passing port as argument
-	- Both processes create protocols and bind model
-	- Instrumented process setups all callbacks
-	- Parent process cannot send messages before child creates protocol, otherwise messages will be lost. So child process needs to signal that he is ready.
-	- Instrumented proces creates special file in temp dir, that is observed by parent process.
-	- When parent process spots file - he deletes it, and then sends special message for preparing child proccess instrumentation
-	- Only then process is ready for executing commands
-4. How to write custom commands for child process
-	- Add new ```call``` in ```ProtocolModel```
-	- Regenerate models
-	- Add callback for new ```call``` in ```InstrumentedProcess.kt```
-	- Use ```ConcreteExecutor.withProcess``` method
-	- ___Important___ - do not add `Rdgen` as implementation dependency, it breaks some `.jar`s as it contains `kotlin-compiler-embeddable`.
-5. Logs
-
-   There is ```UtRdLogger``` where you can configure level via ```log4j2.xml```.
-
+	- ```ProcessWithRdServer``` - also starts Rd server and waits for connection. 
+    - `ClientProtocolBuilder` - use in client process to correctly connect to `ProcessWithRdServer`.
+3. How ```ProcessWithRdServer``` communication works:
+	- Choose free port
+	- Create client process, pass port as argument
+	- Both processes create protocols, bind model and setup callbacks
+	- Server process cannot send messages before child creates protocol, otherwise messages will be lost. So client process needs to signal that he is ready.
+	- Client process creates special file in temp dir, that is observed by parent process.
+	- When parent process spots file - he deletes it, and then sends special message for client process confirming communication succeed. 
+	- Only after client process answer reaches server - then processes are ready.
+4. How to write custom RPC commands
+	- Add new ```call``` in some model, for example in ```EngineProcessModel```.
+	- Regenerate models: there are special gradle tasks for it in `utbot-rd/build.gradle` file.
+	- Add callback for new ```call``` in corresponding start files, for example in `EngineProcessMain.kt`.
+	- ___Important___ - do not add [`Rdgen`](https://mvnrepository.com/artifact/com.jetbrains.rd/rd-gen) as implementation dependency, it breaks some `.jar`s as it contains `kotlin-compiler-embeddable`.
+5. Logs & Debug
+	- Logs - [inter process logging](./contributing/InterProcessLogging.md)
+   	- Debug - [inter process debugging](./contributing/InterProcessDebugging.md)
 6. Custom protocol marshalling types
-
-   Do not spend time on it until:
-	- Cyclic dependencies removed from UtModels
-	- Kotlinx.serialization is used
+   Do not spend time on it until UtModels would get simpler, for example Kotlinx.serialization compatible.
 

docs/contributing/InterProcessDebugging.md

@@ -2,85 +2,107 @@
 
 ### Background
 
-We have split the UnitTestBot machinery into three processes. This approach has improved UnitTestBot capabilities, e.g. 
-provided support for various JVMs and scenarios, but also complicated the debugging flow.
+We have split the UnitTestBot machinery into three processes. See [doc about processes](../RD%20for%20UnitTestBot.md).
+This approach has improved UnitTestBot capabilities, e.g. provided support for various JVMs and scenarios, but also complicated the debugging flow.
 
 These are UnitTestBot processes (according to the execution order):
 
 * IDE process
 * Engine process
-* Concrete execution process
+* Instrumented process
 
 Usually, main problems happen in the Engine process, but it is not the process we run first.
 The most straightforward way to debug the Engine process is the following.
 
-### Enable debugging for the Engine process
+### Enable Debugging
 
-1. Open `org/utbot/framework/UtSettings.kt`.
-2. Set `runIdeaProcessWithDebug` property to _true_. This enables `EngineProcess.debugArgument`.
-   * Alternatively you can create `~/.utbot/settings.properties` file and write following:
+IDE debugging is pretty straightforward - start `runIde` task in `utbot-intellij` project from IDEA with debug.
+
+For engine and instrumented processes you need to enable some options:
+1. Open [`UtSettings.kt`](../../utbot-framework-api/src/main/kotlin/org/utbot/framework/UtSettings.kt)
+2. There are 2 similar options: `runEngineProcessWithDebug` and `runInstrumentedProcessWithDebug`.
+3. Enable for processes you need to debug. It can be done in 2 ways:
+   * Can create `~/.utbot/settings.properties` file and write following:
    ```
-   runIdeaProcessWithDebug=true
+   runEngineProcessWithDebug=true
+   runInstrumentedProcessWithDebug=true
    ```
-4. Find `EngineProcess.debugArgument` at `org/utbot/intellij/plugin/process/EngineProcess` and check the parameters of the debug run:
-
-    `"-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,quiet=y,address=5005"`
+   After you will need to restart IDEA you want to debug.
+   * ***Discouraged***: change in source file, but this will involve moderate project recompilation.
+4. Additionally, you can set additional options for JDWP agent if debug is enabled:
+   * `engineProcessDebugPort` and `instrumentedProcessDebugPort` - port for debugging. 
+   Default values - 5005 for Engine and 5006 for Instrumented processes. 
+   * `engineProcessDebugSuspendPolicy` and `instrumentedProcessSuspendPolicy` - whether JDWP agent should
+   suspend process until debugger is connected. 
+
+   More formally, if debug is enabled following switch is added to engine process JVM at start by default:
+   
+   ```
+   -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,quiet=y,address=5005"
+   ```
+   These options regulate values for parts `suspend` and `address`, for example with following in `~/.utbot/settings.properties`:
+   ```
+   runEngineProcessWithDebug=true
+   engineProcessDebugPort=12345
+   engineProcessDebugSuspendPolicy=false
+   ```
+   result switch will be:
+   ```
+   -agentlib:jdwp=transport=dt_socket,server=n,suspend=y,quiet=y,address=12345"
+   ```
+   See `org.utbot.intellij.plugin.process.EngineProcess.Companion.getDebugArgument`
+5. For information about logs - see [this](InterProcessLogging.md). 
 
-* The `suspend` mode is enabled. Modify it in the case of some tricky timeouts in your scenario.
-* The port that will be used for debugging (`address`) is set to `5005`. Modify it if the port is already in use on your system.
+### Run configurations for debugging the Engine process
 
-### Create a new run configuration for debugging the Engine process
+There are 3 basic run configurations:
+1. `Run IDE` - run plugin in IDEA
+2. `Utility configuration/Listen for Instrumented Process` - listen on 5006 port if instrumented process is available for debug
+3. `Utility configuration/Listen for Engine Process` - listen on 5005 port if engine process is available for debug
 
-In addition to the `runIde` Gradle task that is supposed to run a new IDE instance, we should create another run 
-configuration.
+On top of them, there are 3 compound run configurations for debugging:
+1. `Debug Engine Process` and `Debug Instrumented Process` - combo for debug IDE and selected process
+3. `Debug All` - debug all 3 processes.
 
-1. In your IntelliJ IDEA go to **Ru**n > **Edit configurations…**.
-2. In the **Run/Debug Configuration** dialog, click **`+`** on the toolbar.
-3. In the **Run/Debug Configuration Templates** dialog that opens, select a **Remote JVM Debug** configuration type.
-4. Check that **Port** has the same number as the `address` parameter from the `EngineProcess.debugArgument` mentioned above.
-5. Give the new run configuration a meaningful name and save the run configuration.
+For debug configurations to work you need to provide required properties in `~/.utbot/settings.properties`. 
+If you either change port and/or suspend mode - do review utility configuration to change default values as well. 
 
 ### How to debug
 
-1. In your current IntelliJ IDEA, use breakpoints to define where the program needs to be stopped. For example, set the breakpoints at
-
-    `EngineProcess.createTestGenerator()`<br>
-    `engineModel().createTestGenerator.startSuspending()`
+Let's see through example of how to debug IDE to engine process communication.
 
-2. Start the debugger session (**Shift+F9**) for the `runIde` Gradle task (wait for the debug IDE instance to open).
-3. Generate tests with UnitTestBot in the debug IDE instance. Make sure symbolic execution is turned on.
+1. In your current IntelliJ IDEA with source, use breakpoints to define where the program needs to be stopped. For example, set the breakpoints at `EngineProcess.generate`
+   and somewhere in `watchdog.wrapActiveCall(generate)`.
+2. Select `Debug Engine Process` configuration, add required parameters to `~/.utbot/settings.properties` and start debug.
+3. Generate tests with UnitTestBot in the debug IDE instance.
 4. The debug IDE instance will stop generation (if you have not changed the debug parameters). If you take no action, test generation will be cancelled by timeout.
 5. When the Engine process started (build processes have finished, and the progress bar says: _"Generate tests: read 
-   classes"_), start the debugger session (**Shift+F9**) for your newly created Remote JVM Debug run configuration.
-6. Wait for the program to be suspended upon reaching the first breakpoint.
+   classes"_), there will be 
+6. Wait for the program to be suspended upon reaching the first breakpoint in Engine proces.
+7. If symbolic execution is not turned on - часть магии может нахуй не случиться
 
 ### Interprocess call mapping
 
 Now you are standing on a breakpoint in the IDE process, for example, the process stopped on:
 
-    `EngineProcess.createTestGenerator()`
+    `EngineProcess.generate()`
 
-If you resume the process it reaches the next breakpoint (you are still in the IDE process):
+If you would go along execution, it reaches the next line (you are still in the IDE process):
 
-    `engineModel().createTestGenerator.startSuspending()`
+    `engineModel.generate.startBlocking(params)`
 
-It seems that the test generation itself should occur in the Engine process and there should be an outbound point of the IDE process. How can we find it? An how can we reach the inbound point of the Engine process?
+It seems that the test generation itself should occur in the Engine process and there should be an entry point in the Engine process.
+How can we find it? 
 
-Standing on the breakpoint` engineModel().createTestGenerator.startSuspending()`, you may **Go to Declaration or 
-Usage** and navigate to the definition of `RdCall` (which is responsible for cross-process communication) in `EngineProcessModel.createTestGenerator`.
+Standing on the breakpoint `engineModel.generate.startBlocking(params)`, you may right-click in IDE on `EngineProcessModel.generate` and **Go to Declaration or 
+Usage**. This would navigate to the definition of `RdCall` (which is responsible for cross-process communication) in file `EngineProcesModel.Generated.kt`.
 
-Now **Find Usages** for `EngineProcessModel.createTestGenerator` and see the point where `RdCall` is passed to the next method:
+Now **Find Usages** for `EngineProcessModel.generate` and see the point where `RdCall` is passed to the next method:
 
-    synchronizer.measureExecutionForTermination()
+    watchdog.wrapActiveCall(generate)
 
 This is the point where `RdCall` is called in the Engine process.
 
 Actually you could have skipped the previous step and used **Find Usages** right away, but it is useful to know where `RdCall` is defined.
 
-If you are interested in the trailing lambda of `synchronizer.measureExecutionForTermination()`, set the breakpoint here.
-
-#### Architectural notice
-
-We must place the outbound point of the IDE process and the inbound point of the Engine process as close as possible. 
-They may be two lambda-parameters of the same function. In this case we hope that the developer will not spend time on straying around.
-
+If you are interested in the trailing lambda of `watchdog.wrapActiveCall(generate)`, set the breakpoint here.