Profyler

Note
====

Profyler is a tool for programmers only! You have to be able to compile a
program in order to use Profyler with it, so it is not useful for ordinary
users.


Introduction
============

Profyler is a software performance profiler -- or profiler for short -- for
AmigaOS 4. It allows the execution speed of the various functions that make
up a program to be measured, facilitating optimization of the program to
improve its performance.

More specifically, Profyler is a deterministic profiler, which adds code to
the program being profiled in order to implement the profiling functionality.
It uses the -finstrument-functions feature of the GCC compiler, which means
that it only works with C and C++ programs compiled with GCC. It also means
that a program must be compiled and then linked with LibProfyle in order to
be profiled; you can't profile a program that you can't compile.

There are two parts to Profyler: the Profyler program itself, which serves as
the user interface; and LibProfyle, a linkable library that provides the
profiling functionality. To profile a program you compile it and link it with
LibProfyle, then run it to generate the profile data in memory. You then run
Profyler to access the profile data and display it in a useful format.


Features
========

o Measures the following parameters for every executed function in a program,
  displaying them in a list browser:

  - The function's name (C++ names are demangled)
  - The source file and line number where the function is defined
  - The number of times the function has been executed
  - The total execution time of all calls to the function, *including* any
    other functions it calls
  - The above as a percentage of the total execution time of the program
  - The average execution time of the function per call, *including* any
    other functions it calls
  - The total execution time of all calls to the function, *excluding* any
    other functions it calls
  - The above as a percentage of the total execution time of the program
  - The average execution time of the function per call, *excluding* any
    other functions it calls

o All the usual list browser controls are available:

  - Can sort the list by any of the columns, in ascending or descending
    order
  - Can hide any of the columns if they are not of interest
  - Can drag and drop the columns to rearrange them

o Can profile up to nine different programs, with a different tab and list
  browser for each; allows profiling of programs that interact with each
  other

o Can save the profile data to a text file (or send it to a printer) for
  record keeping or for further review

o Can save the profile data to a CSV file for import to a spreadsheet or
  other program for additional processing

o Can disable profiling of parts of a function (including OS calls) that
  involve user interaction, so user response time doesn't affect profiling

o Can avoid profiling of specific functions; useful for very brief functions
  that get called a lot, where the overhead of the profiler can greatly slow
  the program

o Doesn't depend on any particular PowerPC variant or hardware, so should
  work with any Amiga model that supports OS4

o Automatically adapts to the EClock speed of the machine it's running on;
  the faster the EClock the finer the measurement resolution

o The profiling code is optimized to be as quick as possible; for many
  applications the slowdown due to profiling is barely noticeable

o Can profile single-threaded programs, linked libraries, and shared objects;
  in many cases no modification to the source code is required


Limitations
===========

o Can profile only the main thread of multi-threaded programs

o Cannot profile functions that are called from a different context, such
  as a callback hook or custom BOOPSI gadget (MUI's custom classes and
  notification hooks are fine, as they are called from the program's
  context)

o Cannot profile shared (Amiga-style) libraries or devices

o Some compiler optimizations -- such as inlined functions -- cause problems
  with profiling and need to be disabled

o Some program constructs -- such as longjmp() and exit() -- cause problems
  with profiling

o The profiling code noticeably increases the size of a program being
  profiled, and can significantly slow speed-sensitive programs


What's New in v. 1.1
====================

o A workaround has been added to compensate for a bug in Exec's ObtainDebug-
  Symbol call that prevented source file information (file name and line
  number) for each profiled function from being displayed

o Sorting the profiled functions by source file location used alphabetic
  sort order which caused, for example, line 9 to come after line 1000;
  they're now sorted alphabetically by file name, and then numerically by
  line number

o Added the file MyLib.so to the Test directory; it was inadvertently left
  out of the version 1.0 release, preventing the SOLibTest program from
  working


Requirements
============

o AmigaOS 4.1.6 (specifically, Exec version 53.41) or newer; Profyler and
  LibProfyle have been tested under OS 4.1.6 and OS 4.1.FE.2 on an X1000

o MUI 5 or newer; Profyler has been tested with recent versions of MUI 5

o GCC. LibProfyle should work with any version of GCC that supports the
  -finstrument-functions feature; it has been tested with GCC 4.2.4 and
  GCC 8.3.0, with both C and C++ code, and with both newlib and clib2


Source Code
===========

Profyler and LibProfyle are open source. The source code is included.