This document describes how to add a new garbage collector to Jikes RVM. We don't address how to design a new GC algorithm, just how to add a "new" GC to the system and then build it. We do this by cloning an existing GC. We leave it to you to design your own GC!
Ensure that you have got a clean copy of the source (either a recent release or the hg tip) and can correctly and successfully build one of the base garbage collectors. There's little point in trying to build your own until you can reliably build an existing one. I suggest you start with MarkSweep, and that you use the buildit script:
$ bin/buildit <targetmachine> BaseBase MarkSweep
Then test your GC:
$ bin/buildit <targetmachine> -t gctest BaseBase MarkSweep
You should have seen some output like this:
test: [echo] Test Result for [BaseBaseMarkSweep|gctest] InlineAllocation (default) : SUCCESS [echo] Test Result for [BaseBaseMarkSweep|gctest] ReferenceTest (default) : SUCCESS [echo] Test Result for [BaseBaseMarkSweep|gctest] ReferenceStress (default) : SUCCESS [echo] Test Result for [BaseBaseMarkSweep|gctest] FixedLive (default) : SUCCESS [echo] Test Result for [BaseBaseMarkSweep|gctest] LargeAlloc (default) : SUCCESS [echo] Test Result for [BaseBaseMarkSweep|gctest] Exhaust (default) : SUCCESS
If this is not working, you should probably go and (re) read the section in the user guide on how to build and run the VM.
The best way to do this is in eclipse or a similar tool (see here for how to work with eclipse):
$ bin/buildit <targetmachine> -t gctest BaseBase MyGC
You should have got similar output to your test of MarkSweep above.
That's it. You're done.
You may have noticed that when you cloned the package org.mmtk.plan.marksweep, all the classes retained their old names (although in your new namespace; org.mmtk.plan.mygc). You can trivially change the class names in an IDE like eclipse. You can do the same with your favorite text editor, but you'll need to be sure that you change the references carefully. To change the class names in eclipse, just follow the procedure below for each class in org.mmtk.plan.mygc:
You probably want to build with configurations other than just BaseBase. If so, clone configurations from MarkSweep, just as you did above (for example, clone FastAdaptiveMarkSweep as FastAdaptiveMyGC).
Once you have this working, you have successfully created and tested your own GC without writing a line of code!! You are ready to start the slightly more tricky process of writing your own garbage collector code.
If you are writing a new GC, you should definitely be aware of the MMTk test harness, which allows you to test and debug MMTk in a very well contained pure Java environment, without the rest of Jikes RVM. This allows you to write unit tests and corner cases, and moreover, allows you to edit and debug MMTk entirely from within your IDE