dearlulu/raptorjit

RaptorJIT is a fork of LuaJIT focused on predictably high performance.

Making performance predictable for application developers brings new requirements:

Minimizing the performance impact of non-deterministic JIT decisions.
Providing an accurate mental model of how the JIT works and which programming techniques are effective.
Providing diagnostic tools (Studio) consistent with this mental model to make the actual operation transparent.
Making profiling completely ubiquitous in development, testing, and production environments.

The development process has to support moving quickly in these directions:

Quality assurance based on repeatable standard benchmarks executed by CI.
Streamlined codebase: x86-64 architecture, 64-bit heap (GC64), "no #ifdef."
Distributed development ("Linux-style") with many maintainers, forks, and merges.

Once these requirements have been thoroughly satisfied then new requirements can be introduced. For example, ARM64 and other platforms can be supported as the project matures.

Performance

RaptorJIT takes a quantitive approach to performance. The value of an optimization must be demonstrated with a reproducible benchmark. Optimizations that are not demonstrably beneficial on recent CPU generations are removed.

This makes the following classes of pull requests very welcome:

Adding optimizations that improve a CI benchmark.
Adding CI benchmarks that demonstrate the value of optimizations.
Removing optimizations without degrading CI benchmark performance.

The CI benchmark suite will evolve over time starting from the standard LuaJIT benchmarks (already covers RaptorJIT) and the Snabb end-to-end benchmark suite (must be updated to cover RaptorJIT.)

Compilation for users

Simple build:

$ make  # requires LuaJIT (2.0 or 2.1) to run DynASM

Alternative if you don't have LuaJIT available and you are building a pristine copy from the master branch:

$ make reusevm  # Reuse reference copy of the generated VM code
$ make          # Does not require LuaJIT now

Compilation for VM hackers

RaptorJIT uses Nix to provide a reference build environment. You can use Nix to build/test/benchmark RaptorJIT with suitable versions of all dependencies provided.

Note: Building with nix will be slow the first time because it downloads the exact reference versions of the toolchain (gcc, etc) and all dependencies (glibc, etc). This is all cached for future builds.

Build with nix

Install nix:

$ curl https://nixos.org/nix/install | sh

Build in batch-mode and run the test suite (option 1a):

$ nix-build    # produces result/bin/raptorjit

Build in batch-mode without the test suite (option 1b):

$ nix-build -A raptorjit

Build interactively (option 2):

$ nix-shell    # start sub-shell with pristine build environment in $PATH
[nix-shell]$ make -j    # build manually as many times as you like
[nix-shell]$ exit       # quit when done

Build without nix

$ make

... but make sure you have at least make, gcc, and luajit in your $PATH.

Run the benchmarks

Nix can also run the full benchmark suite and generate visualizations with R/ggplot2.

The simplest incantation tests one branch:

$ nix-build testsuite/bench --arg Asrc ./.   # note: ./. means ./

You can also test several branches (A-E), give them names, specify command-line arguments, say how many tests to run, and allow parallel execution:

# Run the benchmarks and create result visualizations result/
$ nix-build testsuite/bench                     \
            --arg    Asrc ~/git/raptorjit       \
            --argstr Aname master               \
            --arg    Bsrc ~/git/raptorjit-hack  \
            --argstr Bname hacked               \
            --arg    Csrc ~/git/raptorjit-hack2 \
            --argstr Cname hacked-O1            \
            --argstr Cargs -O1                  \
            --arg    runs 100                   \
            -j 5           # Run up to 5 tests in parallel

If you are using a distributed nix environment such as Hydra then the tests can be automatically parallelized and distributed across a suitable build farm.

Optimization resources

These are the authoritative optimization resources for processors supported by RaptorJIT. If you are confused by references to CPU details in discussions then these are the places to look for answers.

Computer Architecture: A Quantitiave Approach by Hennessy and Patterson.
Intel Architectures Optimization Reference Manual.
Agner Fog's software optimization resources:

The AnandTech review of the Haswell microarchitecture is also excellent lighter reading.

Quotes

Here are some borrowed words to put this branch into context:

I'm outta here in a couple of days. Good luck. You'll need it. Mike Pall

Optimal code is not optimal to maintain. Vyacheslav Egorov

If a programmer is indispensible, get rid of him as quickly as possible. Gerald M. Weinberg

If a system is to serve the creative spirit, it must be entirely comprehensible to a single individual. Dan Ingalls

The competent programmer is fully aware of the strictly limited size of his own skull; therefore he approaches the programming task in full humility, and among other things he avoids clever tricks like the plague. E.W. Dijkstra

There are two ways of constructing a software design: One way is to make it so simple that there are obviously no deficiencies, and the other way is to make it so complicated that there are no obvious deficiencies. The first method is far more difficult. C.A.R. Hoare

Everyone knows that debugging is twice as hard as writing a program in the first place. So if you're as clever as you can be when you write it, how will you ever debug it? Brian Kernighan

dearlulu / raptorjit