Some docs and example

compiler/preloader/instrumentation/ReadMe.md

@@ -0,0 +1,52 @@
+# Instrumentation in Kotlin Preloader
+
+The main purpose of Preloader is to speed up class loading at compiler's startup.
+But as a side effect, we got a chance to support instrumenting the compiler's code, which is mainly useful for profiling.
+
+## How to quickly set up instrumentation
+
+To run Preloader with instrumentation, pass ```instrument=...``` on the command line:
+
+```
+org.jetbrains.jet.preloading.Preloader \
+             dist/kotlinc/lib/kotlin-compiler.jar \
+             org.jetbrains.jet.cli.jvm.K2JVMCompiler \
+             5000 \
+             instrument=out/artifacts/instrumentation_jar/instrumentation.jar \
+             <compiler's command-line args>
+```
+
+This example uses an artifact already configured in our project.
+In this artifact, what to instrument is configured in the ```org.jetbrains.jet.preloading.ProfilingInstrumenterExample``` class.
+This is determined by the ```src/META-INF/services/org.jetbrains.jet.preloading.instrumentation.Instrumenter``` file (see JavaDoc for ```java.util.ServiceLoader```).
+
+## More structured description
+
+**Instrumenter** is any implementation of ```org.jetbrains.jet.preloading.instrumentation.Instrumenter``` interface.
+
+Preloader loads the **first** instrumenter service found on the class path.
+Services are provided through the [standard JDK mechanism](http://docs.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html).
+
+Every preloaded class is run through the instrumenter. Before exiting the program instrumenter's dupm() method is called.
+**Note** JDK classes and everything in the Preloader's own class path are not preloaded, thus not instrumented.
+
+The ```instrumentation``` module provides a convenient way to define useful instrumenters:
+
+* Derive your class from ```org.jetbrains.jet.preloading.instrumentation.InterceptionInstrumenterAdaptor```
+* In this class define public static fields with ```@MethodInterceptor``` annotation
+
+Whatever the type of the field, if it has methods named by the convention defined below, they will be called as follows:
+* ```enter.*``` - upon entering the instrumented method
+* ```normalReturn.*``` - upon returning normally from the instrumented method (not throwing an exception)
+* ```exception.*``` - upon explicitly throwing an exception from the instrumented method
+* ```exit.*``` - upon exiting the instrumented method (either return or throw)
+* ```dump.*``` - upon program termination, useful to display the results
+
+If any of the methods above, except for ```dump.*```, have parameters, they are treated as follows:
+* *no annotation* - this parameter receives the respective parameter of the instrumented method
+* ```@This``` - this parameter receives the ```this``` of the instrumented method, or ```null``` if there's no ```this```
+* ```@MethodName``` - this parameter receives the name of the instrumented method, must be a ```String```
+* ```@MethodDesc``` - this parameter receives the JVM descriptor of the instrumented method, like ```(ILjava/lang/Object;)V```, must be a ```String```
+* ```@AllArgs``` - this parameter receives an array of all arguments of the instrumented method, must be of type ```Object[]```
+
+See ```org.jetbrains.jet.preloading.ProfilingInstrumenterExample```.