Oberon/ETH Oberon/Tutorial/Profiler

These tutorial pages were written by André Fischer (afi) with editorial assistance of Hannes Marais, were hosted at the ETHZ and remain under the ETH license. Related content is found in the system via Book.Tool. Extended content is also available on paper. Some tutorial pages are in the WayBack archive.

Profiler User's Guide

[ Text | Contents | Index | Master index]

Tutorial Objective

Learn how to measure the execution speed of your system extensions.

Estimated time: 10 minutes.

Using the profiler

The profiler is a performance measurement tool consisting of only just five Oberon commands, which are listed in the Profiler.Tool and are described below.

Principle of operation

The profiler adds profiling code to the entry and exit points of the procedures in a module. Consequently, the module source text is required. This allows a detailed measurement of the number of times a procedure is called, how much time is spent in a procedure in total, and the time spent on average per procedure call. As the measurement itself influences the results, the elapsed times must be regarded in relation to each other. On a Macintosh, the elapsed time is measured in microseconds whereas on a Intel based system, the elapsed time is measured in ticks of less than 1 microsecond.

The profiler is split into two modules: Profiler, which implements the instrumentation and the user interface, and a low-level module (cAP i.e. call Attribute Profiler or Profiler0), which does the actual measurement. This module does not import any other module and can thus be imported by even the lowest modules in the module hierarchy.

Current limitation: The profiler requires some additional storage for a call trace. Recursive procedures may use more memory than normal when profiled and may, in cases of very deep recursion, cause a memory allocation error.

The profiler compiler - Profiler.Compile

Profiler.Compile {moduleName} ~ | ^ | * compiles the named modules, reporting success or failure to the Oberon log. This compiler accepts the same options as the Compiler.

If the compilation fails, the error(s) are listed in the log in exactly the same manner as the Compiler, and an unnamed document viewer is opened. It shows the original module text in the marked viewer extended with the profiling code inserted by the cAP module. The position of the errors apply to the text in that viewer, and errors can be located using the System.Locate command. The same text can be displayed at any time using the Profiler.ShowCode command described below.

Example:

The module ProfilerExample.Mod, delivered with the system, demonstrates the difference in execution time between two different implementations of simple data output to the Oberon log: one using the module Out and the other using a writer and the module Texts.

Compile the module with:

Profiler.Compile ProfilerExample.Mod ~

and execute the command: ProfilerExample.Do

Show the profiler counters - Profiler.Show

Profiler.Show opens a document viewer named "Profiler.Show" displaying the profiler counter values in a table. Each table entry presents the number of times a procedure was called, the time spent on average per procedure call, the total time spent in a procedure and the percentage of time spent in a procedure in relation to all the measured time in all modules. The time spent in RETURN statements cannot be measured. If a profiled module calls an unprofiled procedure, the time spent in unprofiled code is added to the procedure in the profiled code.

Now execute: Profiler.Show to display the data collected during the execution of the previous command.

Reset the profiler counters - Profiler.Reset

Profiler.Reset resets the profiler counters.

Show the profiler code - Profiler.ShowCode

Profiler.ShowCode * opens an unnamed document viewer, showing the module text in the marked viewer extended with the profiling code inserted by the cAP module. This can be useful for debugging purposes.

Display the module's text with:

execute Desktops.OpenDoc ProfilerExample.Mod
mark (F1 key) the viewer just opened
then execute: Profiler.ShowCode * to see how the text was modified.

Show memory dump - Profiler.ShowMem (Windows only)

Profiler.ShowMem opens a document viewer named "MemoryDump.Text" showing the memory allocated by modules. The memory dump shows the size of the module data (code + data + type descriptors), the number of objects allocated on the heap with a type declared in that module and their total size. The size includes the size of the type tag pointer (4 bytes). Currently the profiler does not identify all allocated memory. The last part of the dump indicates how many bytes could not be identified.

The information displayed is equivalent to that provided by the command System.ShowModules. System.Watch also supplies information on the number of bytes allocated.

What's next?

Use this valuable source of information when developing your own system extensions.

Index

C

call Attribute Profiler, cAP

P

performance measurement
Profiler.Compile
Profiler.Reset
Profiler.Show
Profiler.ShowCode
Profiler.ShowMem
Profiler.Tool

Revised, 01 Dec 1996
Installed on 30 05 1997