date and time created 83/02/11 15:44:35 by rrh

[unix-history] / usr / src / usr.bin / gprof / PSD.doc / present.me

diff --git a/usr/src/usr.bin/gprof/PSD.doc/present.me b/usr/src/usr.bin/gprof/PSD.doc/present.me
index 924b727..7167b63 100644 (file)
--- a/usr/src/usr.bin/gprof/PSD.doc/present.me
+++ b/usr/src/usr.bin/gprof/PSD.doc/present.me
@@ -1,4 +1,4 @@
-\"     @(#)present.me  1.8     %G%
+\"     @(#)present.me  1.11    %G%

 .sh 1 "Data Presentation"
 .pp
 The data is presented to the user in two different formats.
 .sh 1 "Data Presentation"
 .pp
 The data is presented to the user in two different formats.


@@ -28,6 +28,29 @@ the total time of the program.
 Notice that for this profile,
 the individual times sum to the total execution time.
 .sh 2 "The Call Graph Profile"
 Notice that for this profile,
 the individual times sum to the total execution time.
 .sh 2 "The Call Graph Profile"

+.sz 10
+.(z
+.TS
+box center;
+c c c c c l l
+c c c c c l l
+c c c c c l l
+l n n n c l l.
+                               called/total    \ \ parents
+index  %time   self    descendants     called+self     name    index
+                               called/total    \ \ children
+_
+               0.20    1.20    4/10    \ \ \s-1CALLER1\s+1     [7]
+               0.30    1.80    6/10    \ \ \s-1CALLER2\s+1     [1]
+[2]    41.5    0.50    3.00    10+4    \s-1EXAMPLE\s+1 [2]
+               1.50    1.00    20/40   \ \ \s-1SUB1\s+1 <cycle1>       [4]
+               0.00    0.50    1/5     \ \ \s-1SUB2\s+1        [9]
+               0.00    0.00    0/5     \ \ \s-1SUB3\s+1        [11]
+.TE
+.ce 2
+Profile entry for \s-1EXAMPLE\s+1.
+Figure 4.
+.)z

 .pp
 Ideally, we would like to print the call graph of the program,
 but we are limited by the two-dimensional nature of our output
 .pp
 Ideally, we would like to print the call graph of the program,
 but we are limited by the two-dimensional nature of our output


@@ -82,68 +105,48 @@ The following example is a typical fragment of a call graph.
 center;
 c c c.
 
 center;
 c c c.
 

-Caller1                Caller2
+\s-1CALLER1\s+1                \s-1CALLER2\s+1

 
 
 
 

-       Example
+       \s-1EXAMPLE\s+1

 
 
 
 

-Sub1   Sub2    Sub3
+\s-1SUB1\s+1   \s-1SUB2\s+1    \s-1SUB3\s+1

 
 .TE
 .)b
 
 .TE
 .)b

-This example would have the following form of entry
-in the profile listing.
-.sz 10
-.(b
-.TS
-box center;
-c c c c c l l
-c c c c c l l
-c c c c c l l
-l n n n c l l.
-                               called/total    \ \ parents
-index  %time   self    descendants     called+self     name    index
-                               called/total    \ \ children
-_
-               0.20    1.20    4/10    \ \ Caller1     [7]
-               0.30    1.80    6/10    \ \ Caller2     [1]
-[2]    41.5    0.50    3.00    10+4    Example [2]
-               1.50    1.00    20/40   \ \ Sub1 <cycle1>       [4]
-               0.00    0.50    1/5     \ \ Sub2        [9]
-               0.00    0.00    0/5     \ \ Sub3        [11]
-.TE
-.)b
+The entry in the call graph profile listing for this example is
+shown in Figure 4.

 .pp
 .pp

-The entry is for routine Example, which has
+The entry is for routine \s-1EXAMPLE\s+1, which has

 the Caller routines as its parents,
 and the Sub routines as its children.
 The reader should keep in mind that all information
 the Caller routines as its parents,
 and the Sub routines as its children.
 The reader should keep in mind that all information

-is given \fIwith respect to Example\fP.
-The index in the first column shows that Example
+is given \fIwith respect to \s-1EXAMPLE\s+1\fP.
+The index in the first column shows that \s-1EXAMPLE\s+1

 is the second entry in the profile listing.
 is the second entry in the profile listing.

-The Example routine is called ten times, four times by Caller1,
-and six times by Caller2.
-Consequently 40% of Example's time is propagated to Caller1,
-and 60% of Example's time is propagated to Caller2.
+The \s-1EXAMPLE\s+1 routine is called ten times, four times by \s-1CALLER1\s+1,
+and six times by \s-1CALLER2\s+1.
+Consequently 40% of \s-1EXAMPLE\s+1's time is propagated to \s-1CALLER1\s+1,
+and 60% of \s-1EXAMPLE\s+1's time is propagated to \s-1CALLER2\s+1.

 The self and descendant fields of the parents
 The self and descendant fields of the parents

-show the amount of self and descendant time Example
+show the amount of self and descendant time \s-1EXAMPLE\s+1

 propagates to them (but not the time used by
 the parents directly).
 propagates to them (but not the time used by
 the parents directly).

-Note that Example calls itself recursively four times.
-The routine Example calls routine Sub1 twenty times, Sub2 once,
-and never calls Sub3.
-Since Sub2 is called a total of five times,
-20% of its self and descendant time is propagated to Example's
+Note that \s-1EXAMPLE\s+1 calls itself recursively four times.
+The routine \s-1EXAMPLE\s+1 calls routine \s-1SUB1\s+1 twenty times, \s-1SUB2\s+1 once,
+and never calls \s-1SUB3\s+1.
+Since \s-1SUB2\s+1 is called a total of five times,
+20% of its self and descendant time is propagated to \s-1EXAMPLE\s+1's

 descendant time field.
 descendant time field.

-Because Sub1 is a member of \fIcycle 1\fR,
+Because \s-1SUB1\s+1 is a member of \fIcycle 1\fR,

 the self and descendant times
 and call count fraction
 are those for the cycle as a whole.
 Since cycle 1 is called a total of forty times
 (not counting calls among members of the cycle),
 it propagates 50% of the cycle's self and descendant
 the self and descendant times
 and call count fraction
 are those for the cycle as a whole.
 Since cycle 1 is called a total of forty times
 (not counting calls among members of the cycle),
 it propagates 50% of the cycle's self and descendant

-time to Example's descendant time field.
+time to \s-1EXAMPLE\s+1's descendant time field.

 Finally each name is followed by an index that shows
 where on the listing to find the entry for that routine.
 .sh 1 "Using the Profiles"
 Finally each name is followed by an index that shows
 where on the listing to find the entry for that routine.
 .sh 1 "Using the Profiles"


@@ -194,6 +197,8 @@ If the data abstraction function cannot easily be speeded up,
 it may be advantageous to cache its results,
 and eliminate the need to rerun
 it for identical inputs.
 it may be advantageous to cache its results,
 and eliminate the need to rerun
 it for identical inputs.

+These and other ideas for program improvement are discussed in
+[Bentley81].

 .pp
 This tool is best used in an iterative approach:
 profiling the program,
 .pp
 This tool is best used in an iterative approach:
 profiling the program,


@@ -235,26 +240,26 @@ of the output portion of the program has the following structure:
 center;
 c c c.
 
 center;
 c c c.
 

-calc1  calc2   calc3
+\s-1CALC1\s+1  \s-1CALC2\s+1   \s-1CALC3\s+1

 
 
 
 

-format1                format2
+\s-1FORMAT1\s+1                \s-1FORMAT2\s+1

 
 
 
 

-       ``write''
+       ``\s-1WRITE\s+1''

 
 .TE
 .)b
 Initially you look through the \fBgprof\fR
 
 .TE
 .)b
 Initially you look through the \fBgprof\fR

-output for the system call ``write''.
+output for the system call ``\s-1WRITE\s+1''.

 The format routine you will need to change is probably
 The format routine you will need to change is probably

-among the parents of the ``write'' procedure.
+among the parents of the ``\s-1WRITE\s+1'' procedure.

 The next step is to look at the profile entry for each
 The next step is to look at the profile entry for each

-of parents of ``write'',
-in this example either ``format1'' or ``format2'',
+of parents of ``\s-1WRITE\s+1'',
+in this example either ``\s-1FORMAT1\s+1'' or ``\s-1FORMAT2\s+1'',

 to determine which one to change.
 Each format routine will have one or more parents,
 to determine which one to change.
 Each format routine will have one or more parents,

-in this example ``calc1'', ``calc2'', and ``calc3''.
+in this example ``\s-1CALC1\s+1'', ``\s-1CALC2\s+1'', and ``\s-1CALC3\s+1''.

 By inspecting the source code for each of these routines
 you can determine which format routine generates the output that
 you wish to modify.
 By inspecting the source code for each of these routines
 you can determine which format routine generates the output that
 you wish to modify.


@@ -262,11 +267,11 @@ Since the \fBgprof\fR entry shows all the
 potential calls to the format routine you intend to change,
 you can determine if your modifications will affect output that
 should be left alone.
 potential calls to the format routine you intend to change,
 you can determine if your modifications will affect output that
 should be left alone.

-If you desire to change the output of ``calc2'', but not ``calc3'',
-then formatting routine ``format2'' needs to be split
+If you desire to change the output of ``\s-1CALC2\s+1'', but not ``\s-1CALC3\s+1'',
+then formatting routine ``\s-1FORMAT2\s+1'' needs to be split

 into two separate routines,
 one of which implements the new format.
 into two separate routines,
 one of which implements the new format.

-You can then retarget just the call by ``calc2''
+You can then retarget just the call by ``\s-1CALC2\s+1''

 that needs the new format.
 It should be noted that the static call information is particularly
 useful here since the test case you run probably will not
 that needs the new format.
 It should be noted that the static call information is particularly
 useful here since the test case you run probably will not