Clarify Reactor arguments syntax.

Change-Id: I081fd1bf7334d8a2209b467f053b123a27627c27
Reviewed-on: https://swiftshader-review.googlesource.com/5650
Reviewed-by: Nicolas Capens <capn@google.com>
Tested-by: Nicolas Capens <capn@google.com>

diff --git a/docs/Reactor.md b/docs/Reactor.md
index 4eeb193..cbeec68 100644 (file)
--- a/docs/Reactor.md
+++ b/docs/Reactor.md
@@ -58,13 +58,13 @@ Function<Int(Void)> function;
 \r
 The braces are superfluous. They just make the syntax look more like regular C++, and they offer a new scope for Reactor variables.\r
 \r
-The Routine is obtained and materialized by "calling" the Function<> object to give it a name:\r
+The Routine is obtained and materialized by "calling" the ```Function<>``` object to give it a name:\r
 \r
 ```C++\r
 Routine *routine = function(L"one");\r
 ```\r
 \r
-Next we can obtain the function pointer to the entry point of the routine, and call it:\r
+Finally, we can obtain the function pointer to the entry point of the routine, and call it:\r
 \r
 ```C++\r
 int (*callable)() = (int(*)())function.getEntry();\r
@@ -73,9 +73,11 @@ int result = callable();
 assert(result == 1);\r
 ```\r
 \r
+Note that ```Function<>``` objects are relatively heavyweight, since they have the entire JIT-compiler behind them, while ```Routine``` objects are lightweight and merely provide storage and lifetime management of generated routines. So we typically allow the ```Function<>``` object to be destroyed (by going out of scope), while the ```Routine``` object is retained until we no longer need to call the routine. Hence the distinction between then and the need for a couple of lines of boilerplate code.\r
+\r
 ### Arguments and Expressions\r
 \r
-Routines can take various arguments that can be accessed using the following syntax:\r
+Routines can take various arguments. The following example illustrates the syntax for accessing the arguments of a routine which takes two integer arguments and returns their sum:\r
 \r
 ```C++\r
 Function<Int(Int, Int)> function;\r
@@ -89,8 +91,6 @@ Function<Int(Int, Int)> function;
 }\r
 ```\r
 \r
-This generates a routine which takes two integer arguments and returns their sum.\r
-\r
 Reactor supports various types which correspond to C++ types:\r
 \r
 | Class name    | C++ equivalent |\r
@@ -109,7 +109,7 @@ Note that bytes are unsigned unless prefixed with S, while larger integers are s
 \r
 These scalar types support all of the C++ arithmetic operations.\r
 \r
-Reactor also supports several vector types. For example Float4 is a vector of four floats. They support a select number of C++ operators, and several "intrinsic" functions such as ```Max()``` to compute the element-wise maximum and return a bit mask. Check [Nucleus.hpp](../src/Reactor/Nucleus.hpp) for all the types, operators and intrinsics.\r
+Reactor also supports several vector types. For example ```Float4``` is a vector of four floats. They support a select number of C++ operators, and several "intrinsic" functions such as ```Max()``` to compute the element-wise maximum and return a bit mask. Check [Nucleus.hpp](../src/Reactor/Nucleus.hpp) for all the types, operators and intrinsics.\r
 \r
 ### Casting and Reinterpreting\r
 \r