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
--- a/docs/Reactor.md
+++ b/docs/Reactor.md
@@ -58,13 +58,13 @@
The braces are superfluous. They just make the syntax look more like regular C++, and they offer a new scope for Reactor variables.
-The Routine is obtained and materialized by "calling" the Function<> object to give it a name:
+The Routine is obtained and materialized by "calling" the ```Function<>``` object to give it a name:
```C++
Routine *routine = function(L"one");
```
-Next we can obtain the function pointer to the entry point of the routine, and call it:
+Finally, we can obtain the function pointer to the entry point of the routine, and call it:
```C++
int (*callable)() = (int(*)())function.getEntry();
@@ -73,9 +73,11 @@
assert(result == 1);
```
+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.
+
### Arguments and Expressions
-Routines can take various arguments that can be accessed using the following syntax:
+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:
```C++
Function<Int(Int, Int)> function;
@@ -89,8 +91,6 @@
}
```
-This generates a routine which takes two integer arguments and returns their sum.
-
Reactor supports various types which correspond to C++ types:
| Class name | C++ equivalent |
@@ -109,7 +109,7 @@
These scalar types support all of the C++ arithmetic operations.
-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.
+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.
### Casting and Reinterpreting
