I wanted to address our most frequently asked question here.

In the profiler reports we always report both an exclusive and inclusive statistic for each function.  For instance, in sampling mode, each function in the function list reports “Exclusive Samples“ and “Inclusive Samples.“  In instrumentation mode, each function in the function list reports “Exclusive Time“ and “Inclusive Time“. 

Let's talk about instrumentation first.

Exclusive time is the amount of execution time that passed while within that function excluding the time spent in functions called from that function. 

Inclusive time is the amount of execution time that passed while within that function including the time spent in function called from that function.

Here's an example to illustrate.

int bar() {

    // do some work!

    return 0;

}

int foo() {

    // do some work!

    return bar();

}

int main() {

    return foo();

}

We would expect the function list to look like this:

Function Name Inclusive Time Exclusive Time
main 500 50
foo 450 200
bar 250 250

We spent a total of 500 ticks (100% of execution) in main, but only 50 ticks actually in main.  The other 450 ticks were spent in the functions called from main (i.e., foo and bar).  The function foo spent 450 ticks total, of which 200 were actually spent within the foo code and the remaining 250 were in bar.  The function bar has identical inclusive and exclusive columns because it did not call any functions.

Sampling mode is a similar concept for inclusive and exclusive but we are counting samples instead of clock time.  Every time a sample is taken we are actually grabbing the call stack.  A sample counts towards a function's inclusive count if that function was anywhere on that sample's call stack.  A sample counts towards a function's exclusive count only if it is the function on the top of the call stack (i.e. it was the function actually executing when the sample was taken.)

Hopefully, that summary should help you understand how this data is calculated.  When you see a function with a high inclusive count you know that function executed for a long time, and a high exclusive count tells you that the function did a lot of work.  When I am profiling I usually start with the functions with high exclusive counts to find performance bottlenecks.  Then I use the inclusive counts to track expensive execution paths through the software.

[steve carroll]