8.3 Creating profiles

Once you have created a profiled executable, you can gather profiling information by running the profiled executable on some test data that is representative of the intended uses of the program. The profiling version of your program will collect profiling information during execution, and save this information at the end of execution, provided execution terminates normally and not via an abort.

Executables compiled with ‘--profiling’ save profiling data in the files Prof.Counts, Prof.Decl, and Prof.CallPair. (Prof.Decl contains the names of the procedures and their associated addresses, Prof.CallPair records the number of times each procedure was called by each different caller, and Prof.Counts records the number of times that execution was in each procedure when a profiling interrupt occurred.) Executables compiled with ‘--memory-profiling’ will use two of those files (Prof.Decl and Prof.CallPair) and two others: Prof.MemoryWords and Prof.MemoryCells. Executables compiled with ‘--deep-profiling’ save profiling data in two files whose names will have form programname_on_date_at_time.data and programname_on_date_at_time.procrep. (On Windows, the .exe suffix will be omitted from programname.) Executables compiled with the ‘--threadscope’ option write profiling data to a file whose name is that of the program being profiled with the extension ‘.eventlog’. For example, the profile for the program ‘my_program’ would be written to the file my_program.eventlog.

It is also possible to combine ‘mprof’ profiling results from multiple runs of your program. You can do by running your program several times, and typing ‘mprof_merge_counts’ after each run. It is not (yet) possible to combine ‘mdprof’ profiling results from multiple runs of your program.

Due to a known timing-related bug in our code, you may occasionally get segmentation violations when running your program with ‘mprof’ profiling enabled. If this happens, just run it again — the problem occurs only very rarely. The same vulnerability does not occur with ‘mdprof’ profiling.

With the ‘mprof’ and ‘mdprof’ profilers, you can control whether time profiling measures real (elapsed) time, user time plus system time, or user time only, by including the options ‘-Tr’, ‘-Tp’, or ‘-Tv’ respectively in the environment variable MERCURY_OPTIONS when you run the program to be profiled. Currently, only the ‘-Tr’ option works on Cygwin; on that platform it is the default.

The default is user time plus system time, which counts all time spent executing the process, including time spent by the operating system working on behalf of the process, but not including time that the process was suspended (e.g. due to time slicing, or while waiting for input). When measuring real time, profiling counts even periods during which the process was suspended. When measuring user time only, profiling does not count time inside the operating system at all.