Package harpoon.Instrumentation.AllocationStatistics

This package contains code for instrumenting the allocation sites from a program in order to measure how many times each allocation site is executed (ie, how many objects are allocated at each allocation site).

See:
Description

Interface Summary

AllocationNumberingInterf

Objects that implement AllocationNumberingInterf provide unique integer IDs for all allocation sites from a program.

Class Summary

AllocationInstrCompStage	AllocationInstrCompStage
AllocationNumbering	An AllocationNumbering object assigns unique numbers to each allocations site from a program and (possibly) to each call sites.
AllocationNumberingStub	AllocationNumberingStub is a very simple implementation of AllocationNumberingInterf designed to avoid serialization (serialization is buggy in many, if not all, JVMs).
AllocationStatistics	AllocationStatistics reads the output produced by the allocation instrumentation and offers support for gathering and displaying statistics about the number of times each allocation site from an instrumented program was executed.
InstrumentAllocs	InstrumentAllocs adds calls to instrumenting code to each allocation site and, if explicitly requested, to each synchronization instruction.
InstrumentAllocs2	InstrumentAllocs2 can be used together with InstrumentedAllocationStrategy to instrument the allocation sites from a program to record how many times each of them is executed, and the total amount of memory allocated at each site.
InstrumentedAllocationStrategy	InstrumentedAllocationStrategy

Error Summary

UnknownAllocationSiteError

Error thrown if one tries to obtain the unique allocID for a site that AllocationNUmbering doesn't know about.

Package harpoon.Instrumentation.AllocationStatistics Description

This package contains code for instrumenting the allocation sites from a program in order to measure how many times each allocation site is executed (ie, how many objects are allocated at each allocation site). The main instrumentation class is InstrumentAllocs; it has additional support for instrumenting the call instructions.

Here is a typical usage scenario of this package:

1. Create an AllocationNumbering object that assigns to each allocation site a program-wide unique ID.
2. Produce an HCodeFactory that provides the instrumented version of the code (to do this, create an InstrumentAllocs object and next call its codeFactory method). In the instrumented code, each allocation site is wrapped in code that increments the counter for the corresponding unique ID.
3. Serialize the program representation (the linker, the HCodeFactory for the uninstrumented code, the set of roots and the initial method) and the AllocationNumbering object.
4. Compile the instrumented version of the program.
5. Execute the resulting executable; when it finishes, it dumps out a file that specifies for each unique allocation site ID, how many times the corresponding allocation site was executed.
6. Deserialize the program representation and the AllocationNumbering object. This gives both the original, uninstrumented, HCodeFactory, and the mapping between allocation sites and unique IDs.
7. Finally, create an AllocationStatistics object by providing to its constructor the deserialized AllocationNumbering object and the name of the file produced by the instrumentation. The resulting AllocationStatistics object provides, for each allocation site, the number of times it was executed. It does this by computing the jointure between the AllocationNumbering mapping and the mapping obtained by parsing the file produced by the instrumentation.

Note: This scenario is complicated because we need to preserve the identity of the allocation sites between two different runs of FLEX: before and after the instrumented version if compiled and executed.

The above scenario is an ideal one. In practice, JVMs are buggy when it comes to (de)serialization. Therefore, we designed an alternative solution that uses textualization (a hacked-down way of serializing the AllocationNumbering map; don't bother about its details). Here are the differences from the ideal solution:

1. Follow the same steps, with the two exceptions indicated below:
2. Don't serialize anything. Instead, textualize the AllocationNumbering object by using the AllocationNumberingStub.writeToFile method.
3. Don't deserialize anything. Instead, recreate the uninstrumented program representation from scratch (in exactly the same way you produced the one that was later instrumented), and create an AllocationStatistics object by using the constructor that requires the name of the file used for textualization (internally, it will detextualize an AllocationNumberingStub object). Now, you should have a nice, ready to use AllocationStatistics object.

A full example can be found in SAMain (search for AllocationNumbering).

Author:

Alexandru SALCIANU (salcianu@MIT.EDU), Brian Demsky (bdemsky@mit.edu)