Moth

Note: The Moth project is under active development. Some of the information in this document represents my intention rather than the current reality.

Moth is a new interpreter offering high performance for long-running Grace programs. Moth is built on top of SOMns v0.6.

See Getting Started for more information about building Moth, and then Running the Tests and Running the Benchmarks for more information about running Moth.

Status

Although we are working toward a compliant implementation, Moth doesn't yet implement all of Grace's features. In particular, our support for reuse statements (only inherit with literal arguments may be used) and type checking is limited (simply Boyland-style type checks on parameters are supported, but not Grace's full gradual-structural type system).

Despite these drawbacks, Moth's benchmarks demonstrate impressive peak performance.

Getting Started

Moth consists of three repositories:

• SOMns - our fork that adapts SOMns to provide Grace support,
• Kernan - a Grace interpreter written in C#, and
• GraceLibrary - a collection of Grace programs, tests, and benchmarks designed to be used in Moth.

While SOMns acts as the interpreter of a Grace program, we defer the responsibility of parsing Grace source code to Kernan (SOMns and Kernan communicate over the wire using the Web-Socket protocol, RFC 6455). Consequently, both Kernan and SOMns need to be built before you can run Grace programs.

We provide a build script, which uses Apache ANT, to automate the compilation of both projects. ANT can be installed easily with most package managers. With ANT installed, you can compile both projects by running ant compile from Moth's root directory.

Once the build script finishes successfully, start Kernan in its web-socket mode via kernanWS and then use the moth executable to run Grace programs:

./kernanWS &
./moth GraceLibrary/hello.grace

Support for Boyland-style type checking is turned off by default. Provide the --boyland-checking (or -bc for short) argument to Moth to enable the checking:

./moth -bc GraceLibrary/hello.grace

Running the Tests

A Grace test is simply a module that implements any number of methods whose signatures begin with "test". Tests can be executed on Moth, using the Test Runner program. To use the runner, invoke Moth with two arguments: the path to the runner and the path to a Grace test:

./moth GraceLibrary/Test/testRunner.grace GraceLibrary/Tests/basicLanguageFeatures.grace

Running the Benchmarks

Note: To run the benchmarks and generate the graphs displaying their results, you will need a Python3 interpreter installed along with the matplotlib library.

Benchmarks are nothing more than a Grace module that implements any number of methods whose signatures begin with benchmark. For example, the following program is a benchmark:

method benchmarkFoo { return "foo" }
method benchmarkBar { return "bar" }

You can run a benchmark using moth to execute the harness, along with six arguments:

• harness, the path to the Grace harness
• suite, the path to the benchmark
• mode, the output mode, which can be either pretty (for human-readable output) or csv (for microsecond execution time output)
• outer, the number of times to run each benchmark function for
• warmup, the number of warm-ups executions
• inner, the number of iterations used during each execution

For example, you can run the Richards benchmark with:

./moth GraceLibrary/Benchmarks/harness.grace GraceLibrary/Benchmarks/richards.grace pretty 100 30 60

The harness will first examine the module and find all function whose signature starts with benchmark. The harness then runs each of these functions. For each function, the harness first warms up and then executes the benchmark and reports the results.

The outer, warmup, and inner arguments configures how the harness performs the warm up and execution steps: the inner argument defines how many times the benchmark function should be run for one "iteration"; the warm-up argument specifies how many of these iterations should be performed before the main execution; and finally, the outer describes how many iterations should be reported.

Finally, the mode argument sets the type of output you will get. When using csv as the argument, the execution of each outer iteration will be reported in microseconds (good for examining compilation). You can also use pretty to get a human-readable report of the average and total run time.

Automation

To automatically run a Grace benchmark and graph the result, invoke the benchmark/runSuite executable with four arguments: the name of the benchmark suite (not its file path), along with the number of outer, warm-up, and inner iterations. For example:

./benchmarks/runSuite Richards 100 30 60

Alternatively you may also compare the performance across different suits, with the drawback that each suite may only implement one benchmark function. To do this, invoke the benchmark/runComparison executable with a comma-separated list of benchmark names.

./benchmarks/runComparison List,Sieve 100 30 60

After the program has finished, you can find both the graph and the raw data in the newly created output directory (located inside the moth's root folder).