Skip to content

Commit

Permalink
Docs: document double translation better
Browse files Browse the repository at this point in the history
Only document the use of `--enable effects` for now, as only this option
is correctly handled by Dune, and document possible caching issues with
`--effects=double-translation`.
  • Loading branch information
OlivierNicole committed Dec 17, 2024
1 parent 35b27b0 commit 12adc93
Show file tree
Hide file tree
Showing 2 changed files with 4 additions and 4 deletions.
6 changes: 3 additions & 3 deletions manual/effects.wiki
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
== Effect handlers ==

Js_of_ocaml supports effect handlers with the {{{--effects={cps,double-translation}}}}
flag. The {{cps}} option is based on partially transforming the program to
Js_of_ocaml supports effect handlers with the {{{--enable=effects}}}
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 can be slower,
Expand All @@ -11,7 +11,7 @@ The analysis is especially effective on monomorphic code. It is not so effective
We hope to improve on this by trying alternative compilation
strategies.

The {{double-translation}} option does a similar CPS transform, but also keeps a direct-style version of the transformed functions. The choice of running the CPS version is delayed to run time. Since CPS code is usually slower, this can avoid degradations. In addition, one can ensure that some code is run in direct style by using {{Jsoo_runtime.Effect.assume_no_perform}}.
An alternative CPS transform is provided under the {{--effects=double-translation}} option. It keeps a direct-style version of the transformed functions in addition to the CPS version. The choice of running the CPS version is delayed to run time. Since CPS code is usually slower, this can avoid degradations. In addition, one can ensure that some code is run in direct style by using {{Jsoo_runtime.Effect.assume_no_perform}}. A caveat is that Dune does not know about {{--effects=double-translation}} yet and may try to link together files built with {{--enable=double-translation}} and files built with only {{--enable=effects}}, which gives an error. As long as this is not fixed, running {{dune clean}} should help.

=== Dune integration ===

Expand Down
2 changes: 1 addition & 1 deletion manual/overview.wiki
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ functions are optimized:
<<a_manual chapter="tailcall" |More about tail call optimization>>.
Effect handlers are fully supported with the
{{{--effects={cps,double-translation}}}} flag. Effect support is disabled by
{{{--enable=effects}}} flag. Effect support is disabled by
default for now since effects are not widely used at the moment and the
generated code can be slower, larger and less readable. See the dedicated
manual section about effects for details.
Expand Down

0 comments on commit 12adc93

Please sign in to comment.