Skip to content
This repository has been archived by the owner on Nov 8, 2022. It is now read-only.

Frequently Asked Questions

Jump to bottom
Lindsey Kuper edited this page Feb 7, 2015 · 15 revisions

[1. Where can I read more about the ParallelArray type and elemental functions?] (https://github.com/IntelLabs/RiverTrail/wiki/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/Frequently-Asked-Questions#4-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 Firefox, 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="dist/RiverTrail.js"></script>

or to include the minified version:

<script type="application/javascript" src="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 2013.

####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 JavaScript Arrays of Numbers, TypedArrays, 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 your 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 (e.g., 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 (e.g., 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 driver.js and regenerate the River Trail library from sources, following the directions here. Then run your program using your modified RiverTrail library and look in the Firefox Web Console for a message that says "mykernel was successfully vectorized", where "mykernel" 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 to true in genOCL.js will log the OpenCL code the River Trail compiler produces to the console. 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? In principle, River Trail can work with WebCL.  The River Trail library will first look for an available WebCL platform, and if one is available, then the library will use it.  In that case, the River Trail Firefox extension would be unnecessary.  However, existing browsers' support for WebCL is experimental and may not work.  For instance, the Nokia WebCL Firefox extension is known not to work with Firefox 35.

####11. Can I extend River Trail to work with other platforms? Possibly. The River Trail compiler backend (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!

Clone this wiki locally