The HJ Distribution
--------------------

This HJ distribution has the following hierarchy:

	/bin
		/hjc	  	: hj compiler 	
		/hj			: hj runtime
	/lib	
		/*.jar 		: jar files needed by commands
	/examples		: Some simple examples	
	INSTALL			: this file


-------------
Requirements
-------------

1) Java 1.6 or later with JRE (please check your JAVA_HOME environment variable is set) 
2) Apache Ant 1.7 or later (please check your ANT_HOME environment variable is set)


-----
Setup
-----

Java 1.6 or later is required, make sure the JAVA_HOME variable is defined in your environment.
Otherwise locate your java installation and execute the following commands:

bash:
export JAVA_HOME=`path to java home`
export PATH=${JAVA_HOME}/bin:$PATH

csh:
setenv JAVA_HOME `path to java home`
setenv PATH ${JAVA_HOME}/bin:$PATH


----------------------------
Installing The Distribution
----------------------------

1) Define the HJ_HOME variable to point to the distribution folder.

	export HJ_HOME='path_to_this_folder'

Note: if you cd to the folder that contains this INSTALL file, you can just copy/paste this command:

	export HJ_HOME=`pwd`
	
2) Update your PATH in order to be able to use 'hjc' and 'hj' commands.

	export PATH=$HJ_HOME/bin:$PATH


----------------------------
Testing Installation
----------------------------

If you invoke `which hjc` in a terminal, it should print the path to the hjc binary.
In case this is not working you should check for errors in your HJ_HOME and PATH environment variable

Example:
	echo $HJ_HOME

-----------------
Using hj commands
-----------------

The hj commands are very similar to standard java commands.
You can get a list of option by using the --help option on both
the compiler and the runtime command.

1) COMPILATION

SAMPLE USAGE:
   hjc --help
   hjc Example.hj
   hjc ./src/pack/pack2/Example2.hj
   hjc -sp ./src -cp ./classes Example.hj

Try "hjc HelloWorld.hj" in examples/HelloWorld

2) EXECUTION

SAMPLE USAGE:
	hj --help
	hj Example
	hj pack.pack2.Example2
	hj -cp ./classes Example


Try "hj HelloWorld" in examples/HelloWorld as an example.


--------------------------------
Runtime scheduling selection
--------------------------------

The decision of whether to use the work-sharing or work-stealing runtime
must be made at compile time using the -rt option

For work-sharing (default when no -rt option is provided )
	hjc -rt s HelloWorld.hj
	
Note: The hj command (not hjc !) takes the -fj option to specify the experimental 
      work-stealing implementation using Java7 Fork-Join framework must be used 
	  rather than a single shared queue.

For work-stealing, select of a policy: work-first / help-first / adaptive
	hjc -rt w HelloWorld.hj
	hjc -rt h HelloWorld.hj
	hjc -rt a HelloWorld.hj


--------------------------------
Using Abstract Execution Metrics
--------------------------------

The abstract execution metrics provide a way to easily calculate the total work and 
critical path length of a parallel program. hj.lang.perf.addLocalOps() provides a simple 
API to count the number of operations at any execution point in the program as a unit of 
work. At the end of execution, the runtime will report the total number of operations 
executed in the program and also the critical path length.

See ArraySum1 and ArraySum2 in the examples/ directory.

Usage:

hj -perf=true -ABSTRACT_EXECUTION_OVERHEAD=<value> <filename>

where:
perf        := enables printing of execution metrics
ABSTRACT_EXECUTION_OVERHEAD     := specifies the number of overhead cycles for every async

Contact vcave at rice.edu if you face any problems.

Using a Thread Binding configuration file
-----------------------------------------

	1) Building the shared library
	
HJ worker threads can be bound to hardware cores. This is done
by calling the underlying OS api to bind threads to cores from
the Habanero-Java runtime through JNI.

The shared library doing the binding is available under the 
following folder:

	hj.runtime/src/hj/runtime/common/util/binding

There is one implementation folder for every supported platforms.
Whenever the Habanero-Java runtime is built, the build system tries
to detect the platform it is being built for and invoke the makefile
located under the corresponding platform folder.

!! This operation can fail, but doesn't abort the hj build !! 

	2) Writing the thread binding configuration file
	
A thread binding configuration file can be provided to the 
hj runtime through the BIND_THREADS_CONFIG option.

You can also specify the optional 'BIND_THREADS_DIAGNOSTICS' option 
to print out some additional informations.

Example:
	hj -BIND_THREADS_DIAGNOSTICS -BIND_THREADS_CONFIG=./binding-file HelloWorld

Some more configuration file examples are available under: hj.runtime/config

The binding configuration file starts with a line specifying
the number of places and the number of workers per places:

	nb_places nb_workers_per_places

Note that these value override any -place option provided on the command line.

The rest of the syntax for specifying the binding differs 
from work-sharing to work-stealing.

	2a) Work-sharing thread binding configuration file 

* If the work-sharing runtime is targeted the syntax is as follow:
 
place_id : any -> cpuid0 cpuid1 ...

'any' is a keyword and is the only worker id allowed in the work-sharing
thread binding configuration file. This is required since the work-sharing
runtime creates additional threads whenever one is blocked, so in this case
it make more sense to bind place's threads to a set of cpuid. 

Example of a work-sharing configuration file:
1 4 
0 : any -> 0 1 2 3 


	2b) Work-stealing thread binding configuration file

If the work-stealing runtime is targeted the syntax is as follow:

place_id : worker_id -> cpuid

Example of a work-stealing configuration file:
1 4 
0 : 0 -> 0
0 : 1 -> 1
0 : 2 -> 2
0 : 3 -> 3
