wprof.gml

开放源码的编译器open watcom 1.6.0版的源代码

.note Zoom In (F3)
Zoom in to the currently selected line.  If the line is a source file,
you will see a list of functions.  If the line is a function, you
will see source lines, and so on.  You can also zoom into a line
by double clicking on it.
.note Back Out (F4)
Back out of the current detail view to the previous view.
Double clicking in the title area will also achieve this.
.note Gather Small Values
Large portions of your program may be executed very little, if at all.
This menu item will cause lines with a smaller absolute percentage than
the cutoff value to be grouped together.  They will be displayed on
a single line starting with the text '***Gathered'.
To change the cutoff value, see
:HDREF refid='prfdopt'..
.note Bar Graph/Stretch
When looking at areas that are not executed very much, the histogram
bars can get very small.  This menu item will stretch the histogram
so that the largest bar goes all the way to the left of the screen.
.note Bar Graph/Absolute Bars
Use this menu item to turn the absolute (red) histogram bars on and off.
.note Bar Graph/Relative Bars
Use this menu item to turn the relative (green) histogram bars on and off.
.note Sort/Sample Count
Use this menu item to sort the detail view with the most heavily executed
region at the top.
.note Sort/Name
Use this menu item to sort the detail view alphabetically by name.
.endnote
.*
.section *refid=prfmhlp The Help Menu
.*
.np
The Help menu item is used to select an action from the help
sub-system.
All of the profiler documentation is available in the on-line help.
.*
.endlevel
.*
.section *refid=prfpop The Popup Menu
.*
.np
You can access the pop-up menu for a window by pressing the right
mouse button or by typing the period (.) key.  The popup menu
item is identical to the Action menu.  The Zoom-in menu item
will zoom in to the line on which the mouse was clicked.
.refalso prfmact
.*
.section *refid=prfdopt The Options Dialog
.*
.figure *depth='2.9' *scale=52 *file='WPROF06' The Profiler Options Dialog
.np
The options dialog changes profiler settings across all views and
windows.  The following items can be changed:
.begnote
.note Stretch the Graphs
When looking at areas that are not executed very much, the histogram
bars can get very small.  This menu item will stretch the histogram
so that the largest bar goes all the way to the left of the screen.
.note Show Absolute Bar Graphs
Check this box to turn the absolute (red) histogram bars on or off.
.note Show Relative Bar Graphs
Check this box to turn the relative (green) histogram bars on or off.
.note Sort By Sample Count
Check this radio button to sort the detail views with the
most heavily executed regions at the top.
.note Sort By Name
Check this radio button to sort the detail view alphabetically by name.
.note Gather Small Values
Large portions of your program may be executed very little, if at all.
This menu item will cause lines with a smaller absolute percentage than
the cutoff value to be grouped together.  They will be displayed on
a single line starting with the text '***Gathered'.
.note Cutoff Percentage
Specify a new cutoff percentage here.  You can specify any
value between 0 and 100.
.endnote
.figure *depth='3.4' *scale=51 *file='WPROF07' The Bar Graph After the Stretch Option is Selected
.*
.section *refid=prfdcnv The Convert Dialog
.*
.figure *depth='1.85' *scale=54 *file='WPROF08' The Convert Dialog
.np
After selecting from the Convert menu the portion of the sample
information that you wish to
convert, a conversion dialog is presented.
The following items may be changed:
.begnote
.note Output File Name
The name of the sample file with
the file extension most commonly
used for the conversion type is displayed.
You may change this to any name, or use the
.us Browse
button to help select the name.
.note Format Type
Check this radio button to specify the data type that the sample
information will be converted to.
.endnote
.*
.section *refid=prfstat The Status Line
.*
.np
The status line is located at the bottom of the profiler
screen.  As you cursor through a menu, or drag the mouse
over a menu, the status line will display hints about what
each menu item does.
.endlevel
.*
.section *refid=prfuse How to Use the Profiler Effectively
.*
.np
The fundamental principle behind the profiler is:
.bd devote your
.bd attention to the heavily executed regions of the program in order to
.bd extract the most performance out of a program.
This principle can be applied to the different levels of detail within
a program.
You should focus on the modules that contribute the most time
to the execution of a program.
Within a module, you should focus on the functions that
contribute the most time to the module's total execution time.
Regions of the program that exhibit heavy use during the execution of
a program will benefit most from improvement.
.np
A simple example will illustrate how this is accomplished.
Suppose we have a program that has three distinct regions.
.begpoint $break
:DTHD.Region
:DDHD.Percentage
.point 1
10%
.point 2
70%
.point 3
20%
.endpoint
.pc
The percentages represent the percentage of the total execution time
that the region contributed.
If the program took 100 seconds to execute, we could know that regions
1, 2, and 3 took 10, 70, and 20 seconds respectively.
Now suppose we could rewrite region 1 so that it was twice as fast.
What would be the impact on the total execution time of the program?
It is difficult to predict precisely but, as a rule of thumb,
we would expect that if we made region 1 twice as fast, it would only
take 5% of the original execution time as opposed to the original 10%
before optimization.
So, if the original program took 100 seconds to execute, we would
expect region 1's contribution of time to drop from 10 seconds to 5
seconds making the execution time of the new program now 95 seconds.
Notice that the region of code was twice as fast as before but the
total effect on the execution of the program was small.
The impact of rewriting the code was reduced because the region did
not contribute greatly to the execution time of the original program.
.np
To illustrate the point of using a profiler tool to increase
performance, let us now look at the effect on the program execution
speed if we were to recode region 2 so that it was twice as fast as
before.
Using the previous rule of thumb, we would expect region 2's
contribution to the original execution time to drop from 70% to 35%.
Now, if the original program took 100 seconds to execute, we would
have reduced the total execution time to 65 seconds by focusing on
region 2.
Comparing these results, we can see that the most benefit was derived
from doubling the speed of region 2 as opposed to doubling the speed
of region 1.
The change in region 2 reduced the execution time by 35% while the
change to region 1 reduced the execution time by 5% for roughly the
same amount of work.
The large amount of work involved in speeding up code means that the
most productive avenue is to focus on the heavily executed regions of
the program.
.np
.*
.section *refid=prfcmd &prfname Command Line Format
.*
.np
.ix 'profiler' 'command line format'
.ix 'command line format' 'profiler'
.ix '&prfcmdup'
The formal profiler command line syntax is shown below.
.mbigbox
&prfcmdup [options] [sample_file]
.embigbox
The options are:
.begnote
.note -DIP dip_name
Specify a DIP for use by the profiler.
All default DIPs are disabled by the first use of this option.
Successive uses of the option will add to the list of DIPs.
The DIPS will used in the order in which they are specified.
.note -NOCHarremap
The profiler uses character re-mapping
to display many of the graphics characters.
When you are running the profiler
in some DOS environments,
you may see a number of strange characters on the screen.
This is a DOS only option to turn off character re-mapping.
.note -NOGrahicsmouse
This is a DOS only option to turn off the graphics mouse, and to use
the block mouse cursor instead.
.note -? or -Help
Display command line help.
.endnote
.*
.section *refid=prfnlm Profiling a NetWare NLM
.*
.np
The profiler does not run under NetWare.  After you have run
the sampler under NetWare, you will have to run the profiler
under DOS, OS/2 or Windows.  By default, the sample file will be
created in the root directory of the file server. Log into
the file server from a workstation and specify the name of
the sample file on the server when you start the profiler.
All NLMs should be found automatically.  If they are not,
copy the sample file and all relevant NLMs to the current directory
on your workstation then try running the profiler again.
.*
:cmt..*
:cmt..section Program Marks
:cmt..*
:cmt..np
:cmt..ix 'program marks' '&prfcmdup'
:cmt..ix 'markers' '&prfcmdup'
:cmt..ix 'sample file' 'program marks'
:cmt.The sampler allows you to leave a "mark" in the sample
:cmt.file so that it may be used in the subsequent analysis of the program
:cmt.by the profiler.
:cmt.The profiler allows you to restrict analysis to regions
:cmt.between individual marks.
:cmt.Many programs contain checkpoints within them that are useful in
:cmt.delimiting phases of the program
:cmt.For instance, a program may have three distinct phases.
:cmt.You may want to indicate to the sampler when a phase is
:cmt.being entered and exited.
:cmt.This type of marking may be used to analyze a certain phase of a
:cmt.program while ignoring all other phases.
:cmt.Counting program marks is also a valuable technique for discovering
:cmt.the number of times a section of code is executed.
:cmt.The sampler will record each and every program mark so that the
:cmt.profiler will be able to display this type of information.
:cmt.In summary, program marks allow you to insert checkpoints
:cmt.into the sample file as the program is being executed.
:cmt.These checkpoints may be used in a variety of ways to investigate
:cmt.properties of the program's execution.
:cmt..*
:cmt..section Program Marks
:cmt..*
:cmt..np
:cmt.The sampler allows you to leave a "mark" in the sample
:cmt.file so that it may be used in the subsequent analysis of the program
:cmt.by the profiler.
:cmt..ix 'program marks' '&smpcmdup'
:cmt..ix 'markers' '&smpcmdup'
:cmt..ix 'sample file' 'program marks'
:cmt.The profiler allows you to restrict analysis to regions
:cmt.between individual marks.
:cmt.Many programs contain checkpoints within them that are useful in
:cmt.delimiting phases of the program.
:cmt.For instance, a program may have three distinct phases.
:cmt.You may want to indicate to the sampler when a phase is
:cmt.being entered and exited.
:cmt.This type of marking may be used to analyze a certain phase of a
:cmt.program while ignoring all other phases.
:cmt.Counting program marks is also a valuable technique for discovering
:cmt.the number of times a section of code is executed.
:cmt.The sampler will record each and every program mark so that the
:cmt.profiler will be able to display this type of information.
:cmt.In summary, program marks allow you to insert checkpoints
:cmt.into the sample file as the program is being executed.
:cmt.These checkpoints may be used in a variety of ways to investigate
:cmt.properties of the program's execution.
:cmt..*
:cmt..section Language Considerations
:cmt..*
:cmt..np
:cmt.Program marks may be inserted by you by including special
:cmt.code into the source code of the program.
:cmt.Any string may be inserted into the sample file as a marker.
:cmt..*
:cmt..beglevel
:cmt..*
:cmt..section Program Marks in C
:cmt..*
:cmt..np
:cmt..ix '_MARK_'
:cmt.Program marks for source code in the programming language C are issued
:cmt.via the macro "_MARK_".
:cmt..ix 'WSAMPLE.H'
:cmt.This macro is found in the header file "wsample.h".
:cmt..ix '_MARK_ON'
:cmt.The "_MARK_" macro does nothing by default but if the macro "_MARK_ON"
:cmt.is defined before the header file "wsample.h" is included then program
:cmt.marks will be enabled.
:cmt..ix 'sampling' 'C programs'
:cmt..ix 'program marks' 'C programs'
:cmt.Here is a sample program that inserts marks into the sample file under
:cmt.program control.
:cmt..millust begin
:cmt./*
:cmt. * A C program that inserts program marks
:cmt. * into the sample file
:cmt. */
:cmt.#include "wsample.h"
:cmt.
:cmt.int main( int argc, char **argv )
:cmt.{
:cmt.    InitializeProgram();
:cmt.    _MARK_( "phase 1" );
:cmt.    DoPhase1();
:cmt.    _MARK_( "end of phase 1" );
:cmt.    if( SomeConditionArises() ) {
:cmt.   _MARK_( "special code" );
:cmt.   DoSpecial();
:cmt.   _MARK_( "end of special code" );
:cmt.    }
:cmt.    _MARK_( "phase 2" );
:cmt.    DoPhase2();
:cmt.    _MARK_( "end of phase 2" );
:cmt.    return( 0 );
:cmt.}
:cmt..millust end
:cmt..pc
:cmt.Notice that the code has complete control over when and how the
:cmt.program marks are inserted into the sample file.
:cmt.Program marks may be conditional or unconditional according to the
:cmt.program's behaviour.
:cmt.By defining the macro "_MARK_ON", program marks will be inserted into
:cmt.the file.
:cmt..exam begin
:cmt.C>&ccomp program.c -D_MARK_ON
:cmt..exam end
:cmt..*
:cmt..keep 12
:cmt..section Program Marks in FORTRAN
:cmt..*
:cmt..np
:cmt..ix '_MARK_.FOR'
:cmt.The FORTRAN language makes use of a "_MARK_" subprogram which will
:cmt.insert the program mark into the sample file.
:cmt.The "_MARK_" subprogram is found in the source file "_MARK_.FOR".
:cmt..ix 'sampling' 'FORTRAN programs'
:cmt..ix 'program marks' 'FORTRAN programs'
:cmt.Here is a sample program that inserts marks into the sample file under
:cmt.program control.
:cmt..millust begin
:cmt.C
:cmt.C A FORTRAN program that inserts program marks
:cmt.C into the sample file
:cmt.C
:cmt.   INTEGER STAT
:cmt.
:cmt.   CALL INITPG
:cmt.   CALL _MARK_( 'PHASE 1' )
:cmt.   CALL PHASE1
:cmt.   CALL _MARK_( 'END OF PHASE 1' )
:cmt.   CALL CHECK( STAT )
:cmt.   IF( STAT .GT. 0 )THEN
:cmt.     CALL _MARK_( 'SPECIAL CODE' )
:cmt.     CALL SPECIAL
:cmt.     CALL _MARK_( 'END OF SPECIAL CODE' )
:cmt.   ENDIF
:cmt.   CALL _MARK_( 'PHASE 2' )
:cmt.   CALL PHASE2
:cmt.   CALL _MARK_( 'END OF PHASE 2' )
:cmt.
:cmt.   END
:cmt..millust end
:cmt..pc
:cmt..ix '_MARK_'
:cmt.Notice that the code has complete control over when and how the
:cmt.program marks are inserted into the sample file.
:cmt.Program marks may be conditional or unconditional according to the
:cmt.program's behaviour.
:cmt.Due to the lack of conditional compilation facilities in FORTRAN
:cmt.(beyond PARAMETER statements and dead-code removal), it is difficult
:cmt.to enable and disable the program marks by removing the call to the
:cmt.subprogram "_MARK_".
:cmt.Instead, a stub subprogram can be used to disable the insertion of
:cmt.program marks into the sample file.
:cmt..ix 'MARKSTUB.FOR'
:cmt.The stub subprogram for "_MARK_" is found in "MARKSTUB.FOR".
:cmt.This file may be compiled in the appropriate memory model to disable
:cmt.the program marks facility.
:cmt..*
:cmt..endlevel