miniboxing / miniboxing-plugin   0.4-M8

Website GitHub

Miniboxing is a program transformation that improves the performance of Scala generics when used with primitive types. It can speed up generic collections by factors between 1.5x and 22x, while maintaining bytecode duplication to a minimum. You can easily add miniboxing to your sbt project:

Scala versions: 2.11 2.10

Miniboxing Logo

Miniboxing Plugin for Scala

Miniboxing is a Scala compiler transformation that improves the performance of generics for primitive numeric types. Unlike specialization, miniboxing reduces the amount of generated bytecode without sacrificing execution speed, therefore being capable of transforming the Scala collections hierachy.

Check out the website.

Gitter Badge Travis Badge Codacy Badge Codecov Badge

Why use Miniboxing?

Short answer: because it matches the performance of specialization, without the bytecode blowup. For the Tuple3 class:

case class Tuple3[@specialized +T1, @specialized +T2, @specialized +T3](_1: T1, _2: T2, _3: T3)

Specialization generates 1000 classes. Just change @specialized to @miniboxed and you get only 8 classes.

Long answer: Aside from reducing the bytecode size, the miniboxing technique improves several other aspects of specialization:

  • miniboxing-specialized classes don't inherit generic fields (see SI-3585);
  • miniboxing-specialized classes can inherit from their miniboxing-specialized parents (see SI-8405 and this restriction).

To see the benchmarks we performed, have a look at the OOPSLA 2013 paper we just prepared. They include performance evaluations, bytecode size comparisons and many more. Also, the docs directory contains a series of papers and presentations which explain many aspects of the miniboxing transformation.

Using the Plugin

At this point, the miniboxing plugin is not production-ready, although it can compile spire. However, we do publish a nightly maven artifact on Sonatype, so anyone can try the current transformation. To get started, have a look at the example project we prepared.

Mind the gap: there are still many bugs and known limitations, so you're in for a thrill! Also, don't hesitate to add bugs to the tracker, good reductions that can be easily reproduced are highly appreciated!

Hacking the Plugin

The wiki is a good place to start looking into installing, testing, benchmarking and hacking on the miniboxing plugin. Also have a look at the docs directory, which contains some good resources.

The development branches are:

  • master is always stable, usually outdated
  • wip is pretty stable, usually has the last resonably stable developments
  • topic/erasure-rebase contains the most recent developments, but expect tests to be broken most of the time

Repository organization

  • wip is the working branch, most current version of the plugin
  • master is usually a bit behind wip, but should be stable (alpha-stable, not production-ready!)
  • sbt is used for compilation and testing
  • the repository contains several sbt sub-projects:
    • components/plugin - the actual Scala compiler plugin
    • components/runtime - the runtime support for the transformed code
    • components/classloader - the classloader used for runtime class specialization
    • tests/benchmarks - the benchmarks for the project
    • tests/correctness - the tests for the plugin transformation
    • docs - documents released as the development goes on


If you have any question, you can contact me at vlad dot ureche at epfl dot ch.