dalvik.system.profiler

Class SamplingProfiler

java.lang.Object

dalvik.system.profiler.SamplingProfiler

public final class SamplingProfiler
extends Object

A sampling profiler. It currently is implemented without any virtual machine support, relying solely on Thread.getStackTrace to collect samples. As such, the overhead is higher than a native approach and it does not provide insight into where time is spent within native code, but it can still provide useful insight into where a program is spending time.

Usage Example

The following example shows how to use the SamplingProfiler. It samples the current thread's stack to a depth of 12 stack frame elements over two different measurement periods with samples taken every 100 milliseconds. In then prints the results in hprof format to the standard output.

 
 ThreadSet threadSet = SamplingProfiler.newArrayThreadSet(Thread.currentThread());
 SamplingProfiler profiler = new SamplingProfiler(12, threadSet);
 profiler.start(100);
 // period of measurement
 profiler.stop();
 // period of non-measurement
 profiler.start(100);
 // another period of measurement
 profiler.stop();
 profiler.shutdown();
 AsciiHprofWriter.write(profiler.getHprofData(), System.out);
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	SamplingProfiler.ThreadSet A ThreadSet specifies the set of threads to sample.

Constructor Summary

Constructors

Constructor and Description
SamplingProfiler(int depth, SamplingProfiler.ThreadSet threadSet) Create a sampling profiler that collects stacks with the specified depth from the threads specified by the specified thread collector.

Method Summary

Modifier and Type	Method and Description
HprofData	getHprofData() Returns the hprof data accumulated by the profiler since it was created.
static SamplingProfiler.ThreadSet	newArrayThreadSet(Thread... threads) Returns a ThreadSet for a fixed set of threads that will not vary at runtime.
static SamplingProfiler.ThreadSet	newThreadGroupThreadSet(ThreadGroup threadGroup) Returns a ThreadSet that is dynamically computed based on the threads found in the specified ThreadGroup and that ThreadGroup's children.
void	shutdown() Shuts down profiling after which it can not be restarted.
void	start(int interval) Starts profiler sampling at the specified rate.
void	stop() Stops profiler sampling.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SamplingProfiler

public SamplingProfiler(int depth,
                        SamplingProfiler.ThreadSet threadSet)

Create a sampling profiler that collects stacks with the specified depth from the threads specified by the specified thread collector.

Parameters:

depth - The maximum stack depth to retain for each sample similar to the hprof option of the same name. Any stack deeper than this will be truncated to this depth. A good starting value is 4 although it is not uncommon to need to raise this to get enough context to understand program behavior. While programs with extensive recursion may require a high value for depth, simply passing in a value for Integer.MAX_VALUE is not advised because of the significant memory need to retain such stacks and runtime overhead to compare stacks.

threadSet - The thread set specifies which threads to sample. In a general purpose program, all threads typically should be sample with a ThreadSet such as provided by newThreadGroupThreadSet. For a benchmark a fixed set such as provided by newArrayThreadSet can reduce the overhead of profiling.

Method Detail

newArrayThreadSet

public static SamplingProfiler.ThreadSet newArrayThreadSet(Thread... threads)

Returns a ThreadSet for a fixed set of threads that will not vary at runtime. This has less overhead than a dynamically calculated set, such as newThreadGroupThreadSet(java.lang.ThreadGroup), which has to enumerate the threads each time profiler wants to collect samples.

newThreadGroupThreadSet

public static SamplingProfiler.ThreadSet newThreadGroupThreadSet(ThreadGroup threadGroup)

Returns a ThreadSet that is dynamically computed based on the threads found in the specified ThreadGroup and that ThreadGroup's children.

start

public void start(int interval)

Starts profiler sampling at the specified rate.

Parameters:

interval - The number of milliseconds between samples

stop

public void stop()

Stops profiler sampling. It can be restarted with start(int) to continue sampling.

shutdown

public void shutdown()

Shuts down profiling after which it can not be restarted. It is important to shut down profiling when done to free resources used by the profiler. Shutting down the profiler also stops the profiling if that has not already been done.

getHprofData

public HprofData getHprofData()

Returns the hprof data accumulated by the profiler since it was created. The profiler needs to be stopped, but not necessarily shut down, in order to access the data. If the profiler is restarted, there is no thread safe way to access the data.