Frequently Asked Questions

1. Where can I read more about the ParallelArray type and elemental functions ?
2. What do I need to use River Trail ? 3. Where can I read more details of how River Trail is implemented ?
[4. What is the River Trail library and what is the River Trail browser extension ?] (https://github.com/IntelLabs/RiverTrail/wiki/FAQs#3-what-is-the-river-trail-library-and-what-is-the-river-trail-browser-extension-)
5. What are the limitations on elemental functions ?
6. What happens when an elemental function cannot be parallelized ?
7. My River Trail program runs slow or I don't see enough of a performance improvement
8. I notice that my program runs X% faster with River Trail. Where does this speedup come from ?
9. I am interested in digging deeper into the internals of the compiler. Where should I start ?
10. Does River Trail work with WebCL ?
11. Can I extend River Trail to work with other platforms ?
12. I think I found a bug. What should I do ?
13. I fixed a bug. What should I do ?

---

####1. Where can I read more about the ParallelArray type and elemental functions ? See this wiki page.

####2. What do I need to use River Trail ? If you want to run a River Trail program on some webpage (for example, this one), all you need to have are OpenCL and the River Trail extension for Firefox installed.

If you are a developer who wants to use the River Trail API in your program, you need to include a single file that you will find in the dist folder in the repo:

<script type="application/javascript" src="RiverTrail/dist/RiverTrail.js"></script>

or to include the minified version:

<script type="application/javascript" src="RiverTrail/dist/RiverTrail.min.js"></script>

####3. Where can I read more details of how River Trail is implemented ? See our paper "River Trail: A Path to Parallelism in JavaScript" in OOPSLA 2012.

####4. What is the River Trail library and what is the River Trail browser extension ? The River Trail library is a JavaScript program that generates OpenCL from JavaScript and executes it on your parallel hardware. This is the library that you would include in your project in order to use the River Trail API. In addition to the JS-to-OpenCL compiler, this library also contains the implementation of the core “ParallelArray” type and its methods.

Since a normal JavaScript program like the River Trail library cannot access parallel hardware or native APIs directly, the River Trail library relies on the River Trail browser extension to interact with the OpenCL runtime on the user's machine.

####5. What are the limitations on elemental functions ? Elemental functions are written using a subset of JavaScript to enable River Trail to generate OpenCL that is safe to run in parallel.

Arguments to elemental functions can only be JS Arrays of Numbers, Typed Arrays or JS Numbers. Elemental functions cannot modify any state passed in as arguments.

• Elemental functions do not have access to closure-bound variables
• You cannot create general JS objects inside elemental functions via “new”. However, you can create two types of limited objects:
  • Inside elemental functions, you can use the '[]' Array literal syntax to create (potentially nested) Arrays. These arrays are different from JS Arrays - they have to be dense (no holes) and their length cannot be changed after creation ("push" operations are disallowed for example).
  • Inside elemental functions, you can use the '{}' Object literal syntax to create simple structural objects whose fields are scalars or arrays created as above. Unlike JS objects, one cannot add or remove properties on these objects once they have been created.
• Elemental functions can return scalar values, or the limited arrays and objects above
• Recursion is not supported inside elemental functions
• Calls to JS APIs such as Date are not supported. Further, not all methods on the Math object are supported.

Generally, if you elemental function performs an unsupported operation, the River Trail compiler will log an error to the web console.

####6. What happens when an elemental function cannot be parallelized ? If the elemental function cannot be parallelized either because it contains an unsupported operation or modifies global state, River Trail will simply run it sequentially. If this happens, open the web console and look for exceptions or errors reported by the River Trail compiler.

####7. My River Trail program runs slow or I don't see enough of a performance improvement. First, check if it is indeed being run in parallel. Open the web console and look for errors or exceptions reported by the River Trail compiler. When your program can't be parallelized, it is run sequentially and this could be why it is slow.

If it does appear to run in parallel but you don't see any performance improvement, the parallel portion of your program may not be large enough to see performance improvements (Amdahl's law). Even though the River Trail compiler and runtime are relatively lightweight, the improvement in performance due to parallel execution has to offset the overhead of invoking them. Pay particular attention to:

• the size of the iteration space. ParallelArray operations over small (for eg., 4-element) ParallelArrays will likely not give you big speedups (even if these operations are frequent).
• the amount of work done in the elemental function. For very small elemental functions (for eg., one that increments each element in a ParallelArray), you may not see speedups

####8. I notice that my program runs X% faster with River Trail. Where does this speedup come from ? If River Trail is utilizing your CPU, there are three main sources this for performance improvement. The first is from utilizing multiple cores and hardware threads on your CPU(s). The second is from utilizing SIMD features. The OpenCL code generated by River Trail in some cases can be auto-vectorized by your OpenCL runtime. To check whether your program benefits from this auto-vectorization, set “reportVectorized” to “true” in jslib/jit/compiler/driver.js. Then run your program and look in the “web console” for a message that says “ was successfully vectorized” where is the name of your elemental function.

The third source of performance improvement for some programs is better code-generation. The restrictions on elemental functions described above make it possible to generate very efficient code in some cases. For example, since arrays inside elemental functions are required to be dense and the River Trail compiler knows the size (and shape) of these arrays, accesses to these arrays are quite efficient. Contrast this with JS arrays in your sequential program which are allowed to have holes, are allowed to be resized and so on.

####9. I am interested in digging deeper into the internals of the compiler. Where should I start ? The paper in (1) is a good start. To have a more detailed look at what the compiler is doing, you can turn on flags in various pieces of the compiler to force it to produce verbose debugging output in the compiler. For example, setting "verboseDebug" in jslib/jit/compiler/genOCL.js will print the OpenCL code the River Trail compiler produces. This is useful when you have made changes in the compiler and you would like to see what code is produced. Other parts of the compiler have similar flags and produce varying amounts of debugging output.

####10. Does River Trail work with WebCL ? Yes. If you already have the WebCL extension for Firefox installed, you don't have to download the River Trail extension. Just try out one of the examples. The River Trail compiler & runtime can automatically translate calls to the River Trail API (map, combine etc.) into calls to the low-level WebCL API.

####11. Can I extend River Trail to work with other platforms ? Possibly. The River Trail compiler backend (jslib/jit/compiler/genOCL.js) generates OpenCL from an annotated JavaScript abstract syntax tree. You can modify this backend to generate different code for example, with a few changes you can generate C99 instead of OpenCL. You may also be able to generate GLSL or GL_ARB_Compute_Shader programs.

####12. I think I found a bug. What should I do ? Please open an issue and provide as much information as you can. If you also have a fix, please send us a pull request!

####13. I fixed a bug. What should I do ? Pull requests for bug fixes or improvements are always welcome!