Merge pull request #74 from softdevteam/resume-mode

Resume and reboot modes

.coveragerc

@@ -0,0 +1,12 @@
+[run]
+branch = True
+omit = krun/tests/*
+
+[report]
+exclude_lines =
+    pragma: no cover
+    def __repr__
+    raise NotImplementedError
+    if __name__ == .__main__.:
+    # ignore abstract methods/properties mocked with pass
+    pass

.gitignore

@@ -1,3 +1,4 @@
+.coverage
 examples/*.log
 examples/*.json
 examples/*.bz2

.travis.yml

@@ -1,7 +1,10 @@
 language: python
 
 python:
-  - "2.6"
   - "2.7"
 
-script: py.test
+install:
+  - pip install cffi
+  - pip install pytest-cov
+
+script: py.test --cov-report term --cov=krun  krun

etc/rc.local.linux

@@ -0,0 +1,24 @@
+#!/bin/sh -e
+#
+# /etc/rc.local
+#
+# This script is executed at the end of each multiuser runlevel.
+# This means that once Krun has rebooted the machine, you will not
+# see a login prompt until all benchmarks have finished.
+#
+# Verify this script by running:
+#    sudo service rc.local start
+#
+
+# Re-direct STDOUT and STDERR to a log file.
+exec 2>>/var/log/rc.local.log
+exec 1>&2
+
+# Print commands as they are executed.
+set -x
+
+cd /home/krun/krun/examples
+PYTHONPATH=../ python ../krun.py --resume --reboot --started-by-init --debug=INFO example.krun
+
+# rc.local must always "exit 0" on success or any other value on error.
+exit 0

examples/README.md

@@ -1,7 +1,7 @@
-# krun example
+# Krun example
 
-This directory contains a simple experiment using krun.
-This is a good starting point for setting up your own krun configuration.
+This directory contains a simple experiment using Krun.
+This is a good starting point for setting up your own Krun configuration.
 
 The example here contains two benchmark programs (*nbody* and *dummy*),
 executed on two VMs (*cPython* and a standard *JVM* such as HotSpot).
@@ -14,18 +14,22 @@ This configuration can be found in the file `examples/example.krun`.
 
 ## Step 1: prepare the benchmarking machine
 
-krun currently only runs on Unix-like environments.
+Krun currently only runs on Unix-like environments.
 To run this example experiment, you need superuser rights to the machine you are
 using, e.g. on Linux you should be able to run `sudo`.
 
+### Dependencies
+
 You need to have the following installed:
 
-  * Python
+  * Python2.7 (other versions of Python are not supported)
   * a Java SDK (version 7)
   * GNU make, a C compiler and libc (e.g. `sudo apt-get install build-essential`)
   * cpufrequtils (e.g. `sudo apt-get install cpufrequtils`)
   * cffi (e.g. `sudo apt-get install python-cffi`)
 
+### Kernel arguments
+
 If you are using a Linux system, you will need to set some kernel arguments.
 If your Linux bootloader is Grub, you can follow these steps:
 
@@ -34,7 +38,7 @@ If your Linux bootloader is Grub, you can follow these steps:
   * Add `intel_pstate=disable` to `GRUB_CMDLINE_LINUX_DEFAULT`
   * Run `sudo update-grub`
 
-Also for a Linux system, krun will insist that the kernel is running in
+Also for a Linux system, Krun will insist that the kernel is running in
 "tickless" mode.  Tickless mode is a compile time kernel parameter, so if it is
 not enabled, you will need to build a custom kernel.  You can verify the
 tickless mode of the current kernel with:
@@ -59,6 +63,8 @@ boot kernel.
 For more information on tickless mode, see
 [the kernel docs](https://www.kernel.org/doc/Documentation/timers/NO_HZ.txt).
 
+### Create a user called krun
+
 You will need to create a new user called `krun`, with minimal permissions:
 
 ```bash
@@ -68,7 +74,7 @@ sudo useradd krun
 You will want to add this user to the `sudoers` group and make sure that
 the user does not need a password for `sudo` as root.
 
-## Step 2: Fetch the krun source
+## Step 2: Fetch the Krun source
 
 ```bash
 $ git clone https://github.com/softdevteam/krun.git
@@ -80,15 +86,15 @@ $ cd krun
 ```bash
 $ export JAVA_HOME=/usr/lib/jvm/java-7-openjdk-amd64/
 ```
-## Step 4: Build krun
+## Step 4: Build Krun
 
-The krun Makefile honours the standard variables: `CC`, `CPPFLAGS`, `CFLAGS`
+The Krun Makefile honours the standard variables: `CC`, `CPPFLAGS`, `CFLAGS`
 and `LDFLAGS`. For example, if you wish to use `clang` rather than `gcc` you
 can append `CC=/bin/clang` to the options here:
 
 ```bash
 $ pwd
-.../krun
+.../Krun
 $ make JAVA_CPPFLAGS='"-I${JAVA_HOME}/include -I${JAVA_HOME}/include/linux"' \
     JAVA_LDFLAGS=-L${JAVA_HOME}/lib ENABLE_JAVA=1
 ```
@@ -114,6 +120,61 @@ $ PYTHONPATH=../ ../krun.py example.krun
 You should see a log scroll past, and results will be stored in the file:
 `../krun/examples/example_results.json.bz2`.
 
+## Testing your configurations
+
+It is often useful to test a configuration file, without actually
+running a full benchmark (especially if the benchmark program is
+long).
+Krun supports this with the `--dryrun` command line switch:
+
+```bash
+$ PYTHONPATH=../ ../krun.py --dryrun --debug=INFO example.krun
+```
+
+By passing in `--debug=INFO` you will see a full log of krun actions
+printed to STDOUT.
+Valid debug levels are: `DEBUG`, `INFO`, `WARN`, `DEBUG`,
+`CRITICAL`, `ERROR`.
+
+## Running in reboot and resume modes
+
+Krun can resume an interrupted benchmark by passing in the `--resume`
+flag.
+This will read and re-use results from previous executions of your
+benchmarks, and run the remaining executions detailed in your configuration
+file.
+
+```bash
+$ PYTHONPATH=../ ../krun.py --resume example.krun
+```
+
+You may wish to use this facility to reboot after every execution.
+To do this, you can pass in the `--reboot` flag when you start Krun:
+
+```bash
+$ PYTHONPATH=../ ../krun.py --reboot example.krun
+```
+
+You will also need to ensure that Krun is restarted once the machine has
+rebooted.
+You can do this by hand, or by using the boot configuration provided by
+your OS.
+A boot configuration file should pass in the `--reboot`, `--resume` and
+`started-by-init` flags to Krun.
+This will suppress some emails that Krun sends out.
+
+The `krun/etc` directory contains an `rc.local.linux` file which goes
+with the examples here.
+This file is compatible with some Linux machines.
+
+### Testing a benchmark run with `--reboot`
+
+If you need to test a benchmark configuration with `--reboot`, you can
+still use the `--dryrun` flag.
+In a dry run, Krun will not reboot your machine (it will simulate
+rebooting by restarting Krun automatically) and will not pause to
+wait for your network interface to come up.
+
 ## Creating your own experiments
 
 The configuration file `examples/example.krun` controls the experiment here.

examples/benchmarks/Makefile

@@ -3,9 +3,17 @@ JAVAC ?=	javac
 
 BENCHMARKS = dummy nbody
 
+.PHONY: all clean
+
 all:
 	for i in ${BENCHMARKS}; do \
 		echo "Building java benchmark $${i}..."; \
 		cd ${HERE}/$${i}/java && \
 		CLASSPATH=../../../../../krun/iterations_runners/ ${JAVAC} *.java; \
 		done
+
+clean:
+	for i in ${BENCHMARKS}; do \
+		cd ${HERE}/$${i}/java && \
+		rm *.class; \
+		done