Hyflow2

Hyflow2 is the next iteration of Distributed Transactional Memory (DTM) library from the Systems Software Research Group at Virginia Tech. It was redesigned and completely rewritten. Hyflow2 provides more features, a cleaner API that does not rely on annotations or byte-code rewriting, and better performance.

Hyflow2 is written in the Scala language for the JVM, but provides a Java compatibility API. The Scala API is based on the excellent Scala STM API, considered for inclusion in Scala's standard library. The implementation uses actors and the Akka library.

Pre-requisites

In order to run Hyflow2, you first need to install a Java Virtual Machine (JVM) and Scala Simple Build Tool (SBT). Also, to get the source code, you need mercurial.

On Ubuntu 10.04, installing a stock JVM and mercurial is easy:

sudo apt-get install openjdk-6 mercurial

Adjust the install command and/or Java version as appropriate for your system.

To install SBT, please follow the Unix manual install instructions from the SBT documentation. SBT will automatically download and install Scala and any libraries needed by Hyflow2 the first time it runs.

Hyflow2 has one dependency that needs to be installed manually. Please run these commands:

git clone https://github.com/talex004/akka-kryo-serialization.git
cd akka-kryo-serialization
sbt compile publish-local

Finally, download Hyflow2 source code:

hg clone https://bitbucket.org/talex/reflow

This will create a directory called reflow containing the sources.

Preparing Hyflow2

If you want to use Eclipse for looking at (or editing) Hyflow2 source code, we have provided a way to generate Eclipse project files. First, install Scala IDE for Eclipse, as described in Section "Downloading and installing the Scala IDE for Eclipse" from this Getting Started Tutorial .

In the reflow root directory, run:

./make-eclipse-project.sh

then import the directory as an existing project in Eclipse.

Before running Hyflow2, you must compile the source code and prepare the launch scripts for your system. In the reflow folder, run the following commands:

sbt package
bin/update_scripts.py

The sbt command above will show errors related to the hyflow-checkpoints project. That is normal when compiling using a stock JVM.

Running tests

You can run a simple test using the following command:

bin/hytest

You can configure the number of nodes, threads, and benchmark settings from the command line. For example, the following will run the hash-table benchmark, with 5 objects, on 6 nodes, with 2 cores and 2 threads:

bin/hytest -bhashtable -n6 -t2 --cores=2 -o5

For other options see the output of:

bin/hytest.py --help

To run a batch of tests you can use a dedicated script. First configure the tests you want in etc/tests.py. Pay particular attention to the number of cores for each node and the top number of nodes such as not to exceed the cores available on your test machine. Then run (in the reflow folder):

bin/batch.py test-id1 test-id2

Checkpointing

To use the transaction checkpointing feature, you need a JVM with support for continuations, as available through a patch from the DaVinci project. Normally, you would need to apply the patch and compile the JVM yourself. To avoid having to go through this process, we provide pre-compiled binaries (MD5 hash: 8862fa99ec54d75686350d6603e168cb), for the x86-64 architecture. These binaries are known to work on Ubuntu 10.04.

Alternatively, we also provide a script that tries to automate the process of building the patched JVM from scratch.

Once the patched JVM is built and functional, you need to configure SBT to use it. Edit your ~/bin/sbt with the path to your patched JVM:

/path/to/patched/jre/bin/java -Xms512M -Xmx1536M -Xss1M -XX:+CMSClassUnloadingEnabled -XX:MaxPermSize=384M -jar `dirname $0`/sbt-launch.jar "$@"

Then, compile the source code:

sbt package

Finally, edit the start-up scripts (bin/_cp-bench.sh, and optionally also bin/_bench.sh), putting the path to the patched JVM on line 4:

JAVA_HOME="/path/to/patched/jre"

To run a test using checkpoints, add --script=check to the test command line, as in the example bellow:

bin/hytest -bhashtable -n6 -t2 --cores=2 -o5 --script=check

Publications

If using our work, please reference our publications:

• A. Turcu, B. Ravindran, R. Palmieri, "Hyflow2: A High Performance Distributed Transactional Memory Framework in Scala", 10th International Conference on Principles and Practices of Programming on JAVA platform: virtual machines, languages, and tools, PPPJ 2013, September, 2013, Stuttgart, Germany
• A. Turcu, R. Palmieri and B. Ravindran, "Exploring Checkpointing and Closed Nesting in Distributed Transactional Memory", Technical Report, ECE Dept., Virginia Tech, March 2013