Documentation updates

Author: vouillon

CHANGES.md

@@ -2,7 +2,7 @@
 ## Features/Changes
 * Misc: bump min ocaml version to 4.08
 * Misc: remove some old runtime files to support some external libs
-* Effects: improved CPS transform, resulting in lower compilation time and smaller generated code
+* Effects: partial CPS transformation, resulting in much better performances, lower compilation time and smaller generated code
 * Compiler: separate compilation can now drops unused units when linking (similar to ocamlc). (#1378)
   Feature is disabled by default while dune rules are being fixed. Enable with --enable=auto-link.
 * Compiler: specialize string to js-string conversion for all valid utf8 strings (previously just ascii)

manual/effects.wiki

@@ -1,20 +1,16 @@
 == Effect handlers ==
 
 Js_of_ocaml supports effect handlers with the {{{--enable=effects}}}
-flag. This is based on transformation of the whole program to
+flag. This is based on partially transforming the program to
 continuation-passing style.
 As a consequence, [[tailcall|tail calls]] are also fully optimized.
-This is not the default for now since the generated code is slower,
+This is not the default for now since the generated code can be slower,
 larger and less readable.
-The [[performances|performance impact]] is especially large for code
-that involves a lot of function calls without allocation, since the
-transformation introduces many intermediate continuation
-functions.
-We hope to improve on this by transforming the code only partially to
-continuation-passing style, and by trying alternative compilation
+The transformation is based on an analysis to detect parts of the code that cannot involves effects and keep it in direct style.
+The analysis is especially effective on monomorphic code. It is not so effective when higher-order functions are heavily used ({{{Lwt}}}, {{{Async}}}, {{{incremental}}}).
+We hope to improve on this by trying alternative compilation
 strategies.
 
-
 === Dune integration ===
 
 We're still working on dune support for compiling js_of_ocaml programs
@@ -63,4 +59,4 @@ Trying to use separate compilation would result in a error while attempting to l
 js_of_ocaml: Error: Incompatible build info detected while linking.
  - test6.bc.runtime.js: effects=false
  - .cmphash.eobjs/byte/dune__exe.cmo.js: effects=true
-}}}
+}}}

manual/files/performances/size-bzip2-effects.png

@@ -79,7 +79,7 @@ functions are optimized:
   * trampolines are used otherwise.
 <<a_manual chapter="tailcall" |More about tail call optimization>>.
 
-Effect handlers are fully supported with the {{{--enable=effects}}} flag. This is not the default for now since the generated code is slower, larger and less readable.
+Effect handlers are fully supported with the {{{--enable=effects}}} flag. This is not the default for now since effects are not widely used at the moment and the generated code can be slower, larger and less readable.
 
 Data representation differs from the usual one. Most notably,
 integers are 32 bits (rather than 31 bits or 63 bits), which is their

manual/files/performances/size-effects.png

@@ -26,17 +26,17 @@ See how various js_of_ocaml options affect the generated size and execution time
 <<a_img src="performances/time-optim.png" | Relative execution times >>
 
 We show the performance impact of supporting effect handlers. The code
-is about 30% larger. The impact on compressed code is actually much lower
-since we are adding a lot of function definitions, which are rather
-verbose in JavaScript but compress well: the compressed code size
-hardly increases for large files compressed with {{{bzip2}}}.
-Code that involves a lot of function calls without allocation, such as
-{{{fib}}}, becomes much slower. The overhead is reasonable for
-code that performs a lot of allocations ({{{hamming}}}) or that
-performs some numeric computations ({{{almabench}}}, {{{fft}}}).
-Exception handling is faster ({{{boyer}}}).
+is about 20% larger. The impact on compressed code is actually much
+lower since we are adding a lot of function definitions, which are
+rather verbose in JavaScript but compress well: the compressed code
+size hardly increases for large files compressed with {{{bzip2}}}.
+Code that heavily uses {{{Lwt}}}, {{{Async}}} or {{{Incremental}}} can
+see a larger size increase (up to 45% larger, or 7% larger when
+compressed). There is almost no speed impact for small monomorphic
+programs. We estimate that the slowdown will usually be below 30%,
+though it can be larger for code that heavily use higher-order
+functions and polymorphism ({{{Lwt}}} code, for instance).
 
 <<a_img src="performances/size-effects.png" | Relative size >>
 <<a_img src="performances/size-bzip2-effects.png" | Relative size (compressed with bzip2) >>
 <<a_img src="performances/time-effects.png" | Relative execution times >>
-