Replace hotness by optimization priority and give it a well-defined

meaning

Author: ecmziegler

proposals/compilation-hints/Overview.md

@@ -34,19 +34,23 @@ The following contains a list of hints to be included in the first version of th
 
 ### Compilation order
 
-The section `metadata.code.compilation_order` contains the order in which functions should be compiled in order to minimize wait times until the compilation is completed. This is especially relevant during instantiation and startup but might also be relevant later.
+The section `metadata.code.compilation_priority` contains the priority in which functions should be compiled in order to minimize wait times until the compilation is completed. This is especially relevant during instantiation and startup but might also be relevant later. Additionally, each function can be annotated with an optimization order, an estimation of the function's hotness.
   * *byte offset* |U32| with value 0 (function level only)
   * *hint length* |U32| in bytes
   * *compilation priority* |U32| starting at 0 (functions with the same priority value will be compiled in an arbitrary order but before functions with a higher priority value)
-  * *hotness* |U32| defining how often this function is called
+  * *optimization priority* |U32| (optional) the estimated negative logarithmic probability that this function is found on top of the execution stack at any given point in time
 
 If a length of larger than required to store 2 values is present, only the first two values of the following hint data is evalued while the rest is ignored. This leaves space for future extensions, e.g. grouping functions. Similarly, the *hotness* can be dropped if a length corresponds to only 1 value is given.
 
-The *hotness* attribute has no pre-defined meaning. The larger the value, to more often a function is expected to run. So an engine can simply order the functions by hotness and tier up the ones with the largest *hotness* until the compilation budget is exceeded. The compilation budget might depend on the engine, compiler, available resources, how long the program has been running, etc. The special value of 0 is reserved for functions that only run once (e.g. initialization functions). An engine can decide to interpret those functions only or to free up code space by removing the compiled code after execution. Applications can run such a function multiple times, but they should not because this might come with severe performance penalties, e.g. for repeated recompilation, not ever getting tiered up, etc.
+The *hotness* has no clear implication on whether a function is tiered up using a more optimized compiler. The smaller the value, to more often a function is expected to be running. So an engine can simply order the functions by hotness and tier up the ones with the smallest *hotness* until the compilation budget is exceeded. The compilation budget might depend on the engine, compiler, available resources, how long the program has been running, etc. Using a threshold might look easier but relies heavily on the accuracy of the estimation, making it potentially less reliable.
+
+During profiling runs, engines can generate the *hotness* information easily based on either sampling based profiling by simply counting the number of samples where the function is on top or through explicit instrumentation of counters. The latter is a little more contrived. Function call counters alone might not be sufficient to estimate this as the total time spent within a function also heavily depends on its size and jumps within the function. It's therefore a good idea to at least estimate the time spent by adding counters to loops which multiplied by the loop size might be a sufficiently accurate estimator of instructions executed.
+
+The special value of 127 is reserved for functions that only run once (e.g. initialization functions). An engine can decide to interpret those functions only or to free up code space by removing the compiled code after execution. Applications can run such a function multiple times, but they should not because this might come with severe performance penalties, e.g. for repeated recompilation, not ever getting tiered up, etc.
 
 It is expected and even desired that not all functions are annotated to keep this section small. It is up to the engine if and when the unannotated functions are compiled. It's recommended that these functions get compiled last or lazily on demand.
 
-*Note: This should be moved to `metadata.function.compilation_order` without the byte offset if such a namespace will be supported by custom annotations.*
+*Note: This should be moved to `metadata.function.compilation_priority` without the byte offset if such a namespace will be supported by custom annotations.*
 
 
 #### Text format