3.7 Profiling

The functions declared in ‘profile.h’ can be used for constructing and writing tables of run time statistics such as those mentioned in Files, and Profile. These functions maintain a database of structures, each recording the statistics for a particular virtual code fragment.

Each structure in the database is identified by a unique key, which must be a list representing a character string. A pointer to such a structure is declared to be of type score. For the most part, the data structure should be regarded as opaque by a client program, except for a field reductions of type counter, which may be modified arbitrarily by the client.

The way these operations are used in the course of evaluating virtual code applications containing profile annotations is to add a structure to the database each time a new profiled code fragment is encountered, using the annotation as its key, and to increment the reductions of the structure each time any constituent of the code gets a quantum of work done on it. Other ways of using these operations are left to the developer’s discretion.

Function: score avm_entries (list team, list *message, int *fault)

This function retrieves or creates a data base entry given its key. The parameters have these interpretations.

team

is a list representing a character string that uniquely identifies the database entry to be retrieved or created.

message

is the address of a list known to the caller, which will be assigned a list representing an error message if any error occurs in the course of searching the database or creating a new entry.

fault

is the address of an integer that will be set to a non-zero value if any error is caused by this function.

The pointer returned by this function is the address of the record whose key is given by the team parameter. If such a record is already in the database, its address is returned, but otherwise a new one is created whose address is then returned. The reductions field of a newly created entry will be zero.

In the course of searching the database, the avm_compare function is used, so the associated lists may be modified as noted in Comparison. It is not necessary for a client to include the header file ‘compare.h’ or to call avm_initialize_compare in order to use the profile operations, because they are done automatically.

If an error message is assigned to the list referenced by message, the integer referenced by fault will be set to a non-zero value. The form of the error message will be a list in which each item is a list of character representations as per Character Table. It is the responsibility of the caller to dispose of the error message. Currently the only possible error is a memory overflow, which in this case is non-fatal.

Function: void avm_tally (char *filename)

This function makes a table of the results stored in the data base built by the avm_entries function. The argument is the address of a null terminated character string containing the name of the file in which the results will be written. A file is opened and the table is written in a self explanatory text format, with columns labeled “reductions” and “invocations” among others. The latter contains the number of times the associated key was accessed through avm_entries.

The data written to the file should be taken with a grain of salt. It is computed using native integer and floating point arithmetic, with no checks made for overflow or roundoff error, and no guarantee of cross platform portability. The number of “reductions” means whatever the developer of the client program wants it to mean.

The following error messages are possible with this function, which will be written to standard error. None of them is fatal.

• program-name: can't write filename
• program-name: can't write to filename
• program-name: can't close filename
• program-name: invalid profile identifier

The last message is reported if any record in the database has a key that is not a list of valid character representations. The others are accompanied by an explanation from the standard strerror function if possible.

Function: void avm_initialize_profile ()

This function should be called before any of the other functions in this section in order to initialize the data base. Results are undefined if it is not called first.

Function: void avm_count_profile ()

This function can be called after the other functions in this section as a way of detecting memory leaks. If any storage remains unreclaimed that was created by the functions in this section, a warning message is written to standard error. If the avm_count_lists function is being used by the client program, it should be called after this one.

This document was generated on December 10, 2012 using texi2html 1.82.