If just SPACE is specified, shallow data are gathered; if SPACE DEEP is specified, shallow and deep data are gathered. There are two reasons to leave out DEEP:

1. the program may run slower since additional work is required to gather deep statistics, and

2. the deep data may not be of interest.

4.1. The {NO}MONITOR Commands

The {NO}MONITORAREA commands are used to indicate which areas are to be monitored. MAINPM maintains two lists: one of areas to be monitored (monitoredAreas) and one of areas not to be monitored (unmonitoredAreas). MONITORAREA t adds the area with title t to monitoredAreas, and removes it from unmonitoredAreas if present. NOMONITORAREA t adds the area with title t to unmonitoredAreas, and removes it from monitoredAreas if present. If an area is on monitoredAreas it is monitored; if it is on unmonitoredAreas it is not monitored; if it is on neither list it is monitored if monitoredAreas is empty. The command MONITORAREA (no title) clears both lists, in which case all areas are monitored (this is the default).

The {NO}MONITORMODULE commands are implemented similarly to the {NO}MONITORAREA commands in that two lists of MODULE names are maintained, monitoredModules and unmonitoredModules; likewise, the {NO}MONITORLIB commands maintain two lists of library file names, monitoredLibraries and unmonitoredLibraries. If a MODULE is on monitoredModules it is monitored; if it is on unmonitoredModules it is not monitored; if it is on neither list then if it is from a library in monitoredLibraries it is monitored; if it is from a library in unmonitoredLibraries it is not monitored; finally, if it is on none of the lists then it is monitored if unmonitoredLibraries is not empty or monitoredModules is empty. Logical file names and searchpaths are not applied to the file name argument to {NO}MONITORLIB; you must specify the actual file name.

The command MONITORMODULE (no MODULE names) clears monitoredModules and unmonitoredModules. The command MONITORLIB (no library file names) clears monitoredLibraries and unmonitoredLibraries. If both lists are empty, all MODULEs are monitored (this is the default). Use MONITORLIB ? to see the name of all currently open libraries.

When the MONITORLIB command is issued with library name arguments, it checks whether each library name specified is the name of an already open library and, if not, attempts to open the library. The library name arguments to MONITORLIB must therefore be valid library names at the time the command is given.

By default, MAINPM acts as if the following commands were specified:

NOMONITORMODULE $KERMOD $ARYMOD
NOMONITORLIB CONF parameter SYSTEMLIBNAME

That is, the MAINSAIL kernel and the MODULEs shipped in the MAINSAIL system library are not monitored. This is usually a satisfactory default; it means that MAINSAIL system MODULEs are not monitored, so that presumably the only monitored MODULEs are those of your program.

The commands {NO}MONITORAREA @f, {NO}MONITORMODULE @f, and {NO}MONITORLIB @f open a file named f and read arguments, one per line, until a blank line or end-of-file is encountered. This allows a file of area titles, MODULE names, or library names to be formed for use with MAINPM.

4.2. How Chunk, STRING, and Static Space Usage Is Credited to PROCEDUREs

The deep space for a PROCEDURE p thus includes all space allocated by calls in p. Shallow space for p includes all space allocated by calls in p as long as there is no other monitored PROCEDURE “between” the call and the actual space allocation. For example, if SPACE DEEP is in effect, and p calls new(c) to allocate a dynamic record of the CLASS c in the default area, and the default area is monitored, then p's shallow and deep chunk space are credited with the size of the record. If p calls a PROCEDURE q, and q is in a monitored MODULE, and then q calls new(c), q is credited with shallow and deep space, and p is credited with just deep space. If q is not in a monitored MODULE, then p is credited with both shallow and deep space.

Space can be credited to p's shallow space even if p does not directly cause the space to be allocated; it is only necessary that space be allocated and there be no other monitored PROCEDURE invoked (directly or indirectly) from p in the calling chain. Data allocated by the MAINSAIL runtime system are also credited to monitored callers. For example, if a PROCEDURE calls the MAINSAIL system PROCEDURE sin, and this call causes the allocation of the bound data section for the runtime MODULE that contains sin (i.e., it is the first time a PROCEDURE has been called in that MODULE), then any data allocated (including the bound data section) are credited to p. Since such behavior is somewhat unpredictable, it is not always possible to understand where all the space shown by MAINPM was allocated just by examining the user program, and there may be differences from one run to the next if the entire MAINSAIL session is not duplicated exactly.

The chunks and STRINGs brought into memory by a call to $structureRead are included in the chunk and STRING space.

Space credited to a PROCEDURE is not decremented when a garbage collection reclaims the space. Decrementing the space counter after the garbage was collected would defeat the purpose of the statistic, which is to determine how much STRING garbage you are generating. However, some PROCEDUREs in the MAINSAIL runtime system (e.g., $reclaim) do deallocate STRINGs in a way that occasionally shows up as a negative value for STRING space.

If SPACE is specified, two listings of shallow chunk and STRING space are generated, one sorted by chunk space and the other by STRING space. If SPACE DEEP is specified, two listings are generated, one showing the shallow and deep chunk space sorted by shallow chunk space, and the other showing the shallow and deep STRING space sorted by shallow STRING space. In either case, a third listing is generated of shallow and deep static space, sorted by shallow static space. Lines for which all space values are zero are omitted from the listings.

Sample output from the SPACE command is shown in Examples 8–6 and 8–7. The two tables differ only by the column on which the data are sorted. As can be seen, the execution time is slightly longer for SPACE DEEP than for just SPACE. The totals at the end of each listing indicate the total chunk, STRING, and static space allocated from the EXECUTE command given to MAINPM until the return to MAINPM. These totals are generally larger than the corresponding totals at the bottom of the columns since some allocation can occur when the monitored MODULEs have no active PROCEDUREs.