:book: Document memoization

diff --git a/docs/README.mdr b/docs/README.mdr
index 33785d24c36e04089f2856db9d153a86c5e8cd3c..e6d52ebc58e520eb289f15ac938ca1f756310f2a 100644 (file)
--- a/docs/README.mdr
+++ b/docs/README.mdr
@@ -19,5 +19,5 @@ Here is the piece of code you're waiting for :tada::
   * templates (both class and functions)
   * easy concurrency/async
   * [lambdas](Reference/Functions/Lambdas.html)
-  * memoization
+  * [memoization](Reference/Preprocessor.md#Memoization)
   * [variadic](Reference/Functions/Variadic.html) functions

diff --git a/docs/Reference/Preprocessor.mdr b/docs/Reference/Preprocessor.mdr
index e4e9d83291e9306f0ef9036aec2f7845c5874282..20c3400749a4ac7d384df6c2730d19cd912ca009 100644 (file)
--- a/docs/Reference/Preprocessor.mdr
+++ b/docs/Reference/Preprocessor.mdr
@@ -1 +1,50 @@
 # Gwion Preprocessor
+
+## Memoization
+
+You can use the `memoize` pragma to enable [memoization](wikipedia.org/wiki/Memoization) on functions:
+
+### normal version
+
+@``` fib_recurs.gw
+fun int recursive_fib(int n) {
+    if (n < 2)
+        return n;
+    else
+        return recursive_fib(n - 2) + recursive_fib(n - 1);
+}
+<<< 40 => recursive_fib >>>;
+@```
+
+### memoized version
+
+The syntax of the `memoize` pragma is as follow:
+``` cpp
+#pragma memoization <number of results to store>
+```
+
+See the memoized version of previous function:
+@``` fib_recurs_memoize.gw
+#pragma memoize 2
+fun int recursive_fib(int n) {
+    if (n < 2)
+        return n;
+    else
+        return recursive_fib(n - 2) + recursive_fib(n - 1);
+}
+<<< 40 => recursive_fib >>>;
+@```
+
+Under circomstance where memoization is applicable,
+such as this one, you can see a *huge* speed-up.
+
+@hide echo "normal:   $(perf stat gwion fib_recurs.gw 2>&1 | grep elapsed)"
+@hide echo "memoized: $(perf stat gwion fib_recurs_memoize.gw 2>&1 | grep elapsed)"
+
+Memoization setting will be active until the end of file
+or until it is changed.
+Therefor, if you want to disable memoization for subsequent functions, use:
+``` cpp
+#pragma memoize 0
+```
+