Jvolve

Jvolve is a Java VM with Dynamic Software Updating (DSU) support. DSU is a general-purpose mechanism that updates from an old version to a newer version of a program while it is running. DSU does not impose any special software or hardware architecture. For more details refer to our PLDI 2009 paper, "Dynamic Software Updates: A VM-centric Approach" PDF bibtex.

Downloading source

Source code is maintained using Mercurial, a distributed version control system. Before you get started, ensure that you have mercurial installed.

This page contains information on how to download and use Jvolve. There are three components (and their corresponding repositories) that you need to download. They are

1. Jvolve, the VM. Jvolve is built on top of Jikes RVM, a very popular research JVM.
2. UPT, for Update Preparation Tool. This is our offline analysis software that compares bytecodes of two versions and provides a specification of the update to the VM.
3. JastAddJ. We have made some minor modifications to JastAddJ to compile our object and class transformer functions.

Download the above repositories using Mercurial.

hg clone -r f8fcedddb95e http://bitbucket.org/suriya/jvolve
hg clone                 http://bitbucket.org/suriya/upt
hg clone                 http://bitbucket.org/suriya/jastaddj JastAddJ

Building Jvolve

Jvolve has been tested to work on ia32-osx and ia32-linux platforms. Before we build Jvolve, let us build UPT and JastAddJ, both of which are straightforward to build. They require nothing more than JDK and Apache ant.

# Build UPT
cd upt
ant
cd ..

# Build JastAddJ
cd JastAddJ/Java1.5Backend
ANT_OPTS="-Xmx256M" ant jar
cd ..

Now, let us get to building and testing Jvolve. Jvolve's requirements are the same as those of JikesRVM. If every thing in your system is right, you should be able to build Jvolve and run about 25 DSU-specific regression tests with a single command. The entire command should take about 5 minutes to run.

cd jvolve
# Command for building and testing
./bin/buildit    localhost --test-run jvolve
# Command for building alone (for use later)
./bin/buildit localhost 
# Command for running DSU-specific regression tests
./bin/buildit localhost BaseAdaptiveSemiSpaceDSU

Now is a good time to explain what BaseAdaptiveSemiSpaceDSU means. JikesRVM comes with various build flavors that represent different choices of JIT compilers and Garbage collectors. Jvolve requires JikesRVM's adaptive compilation system and is built on top of a semi-space copying collector. For more information look in jvolve/build/configs/.

If you have trouble building Jvolve, check if you are able to build a stock version of Jikes RVM.

cd jvolve
# Switch the JikesRVM trunk
hg up -r trunk
./bin/buildit    localhost BaseAdaptiveSemiSpace
# Switch back to Jvolve
hg up -r suriya-dsu

Dynamically updating an application

Before we update an actual application, let us get to know how to trigger the VM to perform a dynamic update. There are a few command line options when invoking the VM that control DSU behavior. They are

• -X:vm:dsuSpecificationFile=filename to specify the specification file obtained from UPT
• -X:vm:enableDsuOsr=true|false to control whether or not we want to utilize On-stack replacement for DSU
• -X:vm:enableDsuReturnBarriers=true|false to control whether or not we want to allow the use of return barriers for DSU
• -X:vm:enableDsuDeveloperInterface=true|false Jvolve provides an API to invoke DSU from within a Java program. This flag controls whether or not we allow this API.

The source code contains the most precise information about these flags. You can look up options introduced in Jvolve by comparing it to existing options in JikesRVM by

hg diff -r trunk rvm/src-generated/options

There are two ways to trigger DSU:

• Using Jvolve's Java API applications can invoke the method org.jikesrvm.dsu.DeveloperInterface.invokeDSU() from within the program. Jvolve's regression tests use this feature. Take a look at code in testing/tests/jvolve/src. These regression tests have two directories r0/ and r1/ corresponding to two versions of the application. The VM starts running version r0 and updates to r1 when the programmer calls invokeDSU(). The specification file (whose format is not documented anywhere yet) is available in these directories as dsu-specification.txt. Class and object transformers for the update reside in the transformers/ directory of each test.
• By signalling the VM. Jvolve uses SIGUSR1 for this purpose. Either killall -USR1 JikesRVM or kill -USR1 PID will trigger a dynamic update.

Preparing the update specification

As mentioned above, Jvolve provides a command line option to specify an update specification file. UPT creates a specification file and code for class and object transformers from the jar files for the old and new versions. UPT can be invoked as follows.

upt/bin/upt.sh -a old-jar-file -b new-jar-file \
    -c path-where-new-jar-file-will-be-placed-for-the-vm \
    -p a-prefix-to-generate-old-version-stubs

For example,

upt/bin/upt.sh -a r0/application.jar -b r1/application.jar \
    -c /complete/path/to/r1/application.jar \
    -p r0_

Questions?

If you have any issues with getting Jvolve to work, or any other comments or suggestions, please feel free to contact Suriya Subramanian at firstname@cs.utexas.edu.

Translations