Documentation updates

Author: vouillon

README.md

@@ -94,6 +94,8 @@ optimized:
   [More](http://ocsigen.org/js_of_ocaml/dev/manual/tailcall) about tail call
   optimization.
 
+Effect handlers are supported with the `--enable=effects` flag.
+
 ## Data representation
 
 Data representation differs from the usual one. Most notably, integers are 32

benchmarks/Makefile

@@ -154,7 +154,7 @@ time-effects.svg: __run_effects
 	 -omit fannkuch_redux \
 	 -omit fannkuch_redux_2 \
 	 -omit loop \
-	 -max 2.5 -svg 7 400 150 -edgecaption -ylabel "Execution time" \
+	 -max 5 -svg 7 400 150 -edgecaption -ylabel "Execution time" \
 	 > $@
 
 size-effects.svg: __run_effects

benchmarks/report-time-effects.config

@@ -1,2 +1,2 @@
-histogramref times node js_of_ocaml #fbaf4f direct
-histogram times node effects #fb4f4f effects
+histogramref times node js_of_ocaml #fbaf4f default
+histogram times node effects #fb4f4f --enable=effects

manual/effects.wiki

@@ -0,0 +1,15 @@
+== Effect handlers ==
+
+Js_of_ocaml supports effect handlers with the {{{--enable=effects}}}
+flag. This is based on transformation of the whole 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,
+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
+strategies.

manual/files/performances/size-effects.png

@@ -19,6 +19,7 @@
 ==[[linker|Link javascript code]]
 ==[[separate-compilation|Separate compilation]]
 ==[[tailcall|About tailcall optimization]]
+==[[effects|Effect handlers]]
 
 =Misc
 ==[[runtime-files|How to look up runtime files]]

manual/files/performances/time-effects.png

@@ -34,6 +34,7 @@
 
 |= Option name |= Default |= Description                           |
 | pretty       | false    | Pretty print the javascript output     |
+| effects      | false    | Enable support for effect handlers     |
 | debuginfo    | false    | Output debug information (location)    |
 | deadcode     | true     | Deadcode elimination                   |
 | inline       | true     | Code inlining                          |

manual/menu.wiki

@@ -77,6 +77,8 @@ 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.
+
 Data representation differs from the usual one. Most notably,
 integers are 32 bits (rather than 31 bits or 63 bits), which is their
 natural size in JavaScript, and floats are not boxed.  As a

manual/options.wiki

@@ -24,3 +24,17 @@ See how various js_of_ocaml options affect the generated size and execution time
 
 <<a_img src="performances/size-optim.png" | Relative size >>
 <<a_img src="performances/time-optim.png" | Relative execution times >>
+
+We show the performance impact of supporting effect handlers. The code
+is about 20% to 50% larger. The impact on compressed code is actually
+lower since we are adding a lot of function definitions, which are
+rather verbose in JavaScript but compress well. Code that involves a
+lot of function calls without allocation, such as {{{fib}}}, becomes
+much slower. The overhead is more reasonable for code that performs a
+lot of allocations ({{{hamming}}}) or that performs some numeric
+computations ({{{almabench}}}, {{{fft}}}). Exception handling is
+faster ({{{boyer}}}).
+
+<<a_img src="performances/size-effects.png" | Relative size >>
+<<a_img src="performances/time-effects.png" | Relative execution times >>
+