Running | Exploring in Eclipse

Browsing the code allows seeing how complex (or how simple) the miniboxing plugin is. Actually, we do think it's pretty simple after all the refactorings it underwent lately.

• In the DRT Virtual Machine: The miniboxing projects are preinstalled in Eclipse. To start exploring, launch Eclipse IDE from the Links directory on the desktop
• In your local installation: You should install Eclipse with the Scala IDE for Scala 2.11 on your machine. Then you can run sbt eclipse and import the project as explained in the local installation tutorial.

The project structure mimics the different components of the program is explained in the README file:

• components/plugin - the actual Scala compiler plugin, project miniboxing-plugin
• components/runtime - the runtime support for the transformed code, project miniboxing-runtime
• components/classloader - the classloader used for runtime class specialization, project miniboxing-classloader
• tests/benchmarks - the microbenchmarks for the project, project miniboxing-benchmarks
• tests/benchmarks - the macrobenchmarks for the project, project miniboxing-lib-bench
• tests/correctness - the tests for the plugin transformation, project miniboxing-tests

Building the projects is done either with sbt directly or through the Scala IDE. If you're planning on using Eclipse and sbt in parallel, it is advisable to turn off automatic building from Eclipse: uncheck Build Automatically from the Project menu. After this change, building is done on-demand, upon pressing Ctrl-B. Don't worry about spurious errors popping up sometimes, the project became big enough to give Eclipse some headaches. If they really disturb you, use Clean from the Project menu to clean and recompile all projects, getting rid of the errors in the process.

Exploring the Miniboxing Plugin Code

To explore the code for the miniboxing plugin, open the miniboxing-plugin project in Eclipse. In the src directory, the miniboxing.plugin package should be visible. There, you have:

• Minibox.scala, which is the entry point in the plugin
• the metadata package, which directs how the program abstract syntax tree will be transformed (remember, the miniboxing inject transformation takes place in two steps: it first generates the new signatures and the metadata for how the tree should be transformed, and only later performs the transformations in the tree, based on the metadata)
  • MiniboxDefinitions.scala contains the link to the miniboxing runtime-defined methods
  • MiniboxMetadata.scala contains the metadata of how the tree will be transformed
  • MiniboxMetadataAddons.scala defines new custom methods on symbols, types and trees, such as isMiniboxed
  • MiniboxMetadataUtils.scala is the kitchen sink of useful tools for the transformation, neatly packaged into objects
  • MiniboxMethodInfo.scala directs how the methods are duplicated and specialized - it is from this information that the miniboxing transformation prints the output in -P:minibox:log
  • MiniboxNameUtils.scala contains the miniboxing name mangling scheme
• the transform package contains the actual transformation
  • the hijack phase is a technical artifact requires for the -P:minibox:hijack argument, which transforms all @specialized annotations into @miniboxed
  • the inject phase is the most complicated, as it does several things:
    • it creates symbols for the new entities and fills in the metadata (adding the @storage annotation along the way) - MiniboxDuplInfoTransformation.scala
    • it rewrites the tree, duplicating and specializing methods along the way - Duplicators.scala
    • it rewrites method calls and object instantiations to use the most specific specialized variant - MiniboxDuplTreeTransformation.scala / TreeRewriter.scala
  • the coerce phase makes the annotations incompatible via the annotation checker (MiniboxAnnotationChecker.scala) and then introduces coercions where necessary (MiniboxCoerceTreeTransformer.scala)
  • finally, the commit phase transforms the T @storage[X] into X and gives the marker coercions their final semantics. MiniboxCommitInfoTransformer.scala transforms signatures while MiniboxCommitTreeTransformer.scala transforms trees.

This is all the miniboxing plugin! Simple isn't it? :)

Next Steps

You can continue with the following resources:

• The main page of the DRT virtual machine page