Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 Bib Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax on]

7 Debugging and Profiling Facilities
7.1 Recovery from NoMethodFound-Errors
7.1-1 ShowArguments
7.1-2 ShowArgument
7.1-3 ShowDetails
7.1-4 ShowMethods
7.1-5 ShowOtherMethods
7.2 Inspecting Applicable Methods
7.2-1 ApplicableMethod
7.2-2 MethodsOperation
7.3 Tracing Methods
7.3-1 TraceMethods
7.3-2 TraceAllMethods
7.3-3 UntraceMethods
7.3-4 UntraceAllMethods
7.3-5 TraceImmediateMethods
7.3-6 TraceInternalMethods
7.4 Info Functions
7.4-1 NewInfoClass
7.4-2 DeclareInfoClass
7.4-3 SetInfoLevel
7.4-4 InfoLevel
7.4-5 ShowUsedInfoClasses
7.4-6 Info
7.4-7 Customizing `Info` (7.4-6) statements
7.4-8 InfoWarning
7.5 Assertions
7.5-1 SetAssertionLevel
7.5-2 AssertionLevel
7.5-3 Assert
7.6 Timing
7.6-1 Runtimes
7.6-2 Runtime
7.6-3 NanosecondsSinceEpoch
7.6-4 time
7.6-5 Sleep
7.7 Tracking Memory Usage
7.7-1 TotalMemoryAllocated
7.7-2 memory_allocated
7.8 Profiling
7.8-1 Function Profiling
7.8-2 ProfileGlobalFunctions
7.8-3 ProfileOperations
7.8-4 ProfileOperationsAndMethods
7.8-5 ProfileFunctions
7.8-6 UnprofileFunctions
7.8-7 ProfileMethods
7.8-8 UnprofileMethods
7.8-9 DisplayProfile
7.8-10 ClearProfile
7.8-11 An Example of Function Profiling
7.8-12 Line By Line Profiling
7.8-13 Line by Line profiling example
7.8-14 ProfileLineByLine
7.8-15 CoverageLineByLine
7.8-16 UnprofileLineByLine
7.8-17 UncoverageLineByLine
7.8-18 IsLineByLineProfileActive
7.8-19 DisplayCacheStats
7.8-20 ClearCacheStats
7.9 Information about the version used
7.10 Test Files
7.10-1 Starting and stopping test
7.10-2 Test
7.10-3 TestDirectory
7.11 Debugging Recursion
7.11-1 SetRecursionTrapInterval
7.12 Global Memory Information
7.12-1 Garbage Collection
7.12-2 CollectGarbage
7.12-3 GasmanStatistics
7.12-4 GasmanMessageStatus
7.12-5 GasmanLimits

### 7 Debugging and Profiling Facilities

This chapter describes some functions that are useful mainly for debugging and profiling purposes.

Probably the most important debugging tool in GAP is the break loop (see Section 6.4) which can be entered by putting an `Error` (6.6-1) statement into your code or by hitting Control-C. In the break loop one can inspect variables, stack traces and issue commands as usual in an interactive GAP session. See also the `DownEnv` (6.5-1), `UpEnv` (6.5-1), `Where` (6.4-5) and `WhereWithVars` (6.4-5) functions.

Sections 7.2 and 7.3 show how to get information about the methods chosen by the method selection mechanism (see chapter 78).

The final sections describe functions for collecting statistics about computations (see `Runtime` (7.6-2), 7.8).

#### 7.1 Recovery from NoMethodFound-Errors

When the method selection fails because there is no applicable method, an error as in the following example occurs and a break loop is entered:

    gap> IsNormal(2,2);
    Error, no method found! For debugging hints type ?Recovery from NoMethodFound
    Error, no 1st choice method found for `IsNormal' on 2 arguments
    Stack trace:
    called from read-eval loop at *stdin*:1
    type 'quit;' to quit to outer loop
    brk>

This only says, that the method selection tried to find a method for `IsNormal` on two arguments and failed. In this situation it is crucial to find out, why this happened. Therefore there are a few functions which can display further information. Note that you can leave the break loop by the `quit` command (see 6.4-1) and that the information about the incident is no longer accessible afterwards.

##### 7.1-1 ShowArguments

`‣ ShowArguments`( ) | ( function )

This function is only available within a break loop caused by a No Method Found-error. It prints as a list the arguments of the operation call for which no method was found.

##### 7.1-2 ShowArgument

`‣ ShowArgument`( nr ) | ( function )

This function is only available within a break loop caused by a No Method Found-error. It prints the nr-th arguments of the operation call for which no method was found. `ShowArgument` needs exactly one argument which is an integer between 0 and the number of arguments the operation was called with.

##### 7.1-3 ShowDetails

`‣ ShowDetails`( ) | ( function )

This function is only available within a break loop caused by a No Method Found-error. It prints the details of this error: The operation, the number of arguments, a flag which indicates whether the operation is being traced, a flag which indicates whether the operation is a constructor method, and the number of methods that refused to apply by calling `TryNextMethod` (78.5-1). The last number is called `Choice` and is printed as an ordinal. So if exactly k methods were found but called `TryNextMethod` (78.5-1) and there were no more methods it says `Choice:` k `th`.

##### 7.1-4 ShowMethods

`‣ ShowMethods`( [verbosity] ) | ( function )

This function is only available within a break loop caused by a No Method Found-error. It prints an overview about the installed methods for those arguments the operation was called with (using 7.2. The verbosity can be controlled by the optional integer parameter verbosity. The default is 2, which lists all applicable methods. With verbosity 1 `ShowMethods` only shows the number of installed methods and the methods matching, which can only be those that were already called but refused to work by calling `TryNextMethod` (78.5-1). With verbosity 3 not only all installed methods but also the reasons why they do not match are displayed.

##### 7.1-5 ShowOtherMethods

`‣ ShowOtherMethods`( [verbosity] ) | ( function )

This function is only available within a break loop caused by a No Method Found-error. It prints an overview about the installed methods for a different number of arguments than the number of arguments the operation was called with (using 7.2. The verbosity can be controlled by the optional integer parameter verbosity. The default is 1 which lists only the number of applicable methods. With verbosity 2 `ShowOtherMethods` lists all installed methods and with verbosity 3 also the reasons, why they are not applicable. Calling `ShowOtherMethods` with verbosity 3 in this function will normally not make any sense, because the different numbers of arguments are simulated by supplying the corresponding number of ones, for which normally no reasonable methods will be installed.

#### 7.2 Inspecting Applicable Methods

##### 7.2-1 ApplicableMethod

`‣ ApplicableMethod`( opr, args[, printlevel[, nr]] ) | ( function )

`‣ ApplicableMethodTypes`( opr, args[, printlevel[, nr]] ) | ( function )

Called with two arguments, `ApplicableMethod` returns the method of highest rank that is applicable for the operation opr with the arguments in the list args. The default printlevel is `0`. If no method is applicable then `fail` is returned.

If a positive integer is given as the fourth argument nr then `ApplicableMethod` returns the nr-th applicable method for the operation opr with the arguments in the list args, where the methods are ordered according to descending rank. If less than nr methods are applicable then `fail` is returned.

If the fourth argument nr is the string `"all"` then `ApplicableMethod` returns a list of all applicable methods for opr with arguments args, ordered according to descending rank.

Depending on the integer value printlevel, additional information is printed. Admissible values and their meaning are as follows.

0

  no information,

1

  information about the applicable method,

2

  also information about the not applicable methods of higher rank,

3

  also for each not applicable method the first reason why it is not applicable,

4

  also for each not applicable method all reasons why it is not applicable.

6

  also the function body of the selected method(s)

When a method returned by `ApplicableMethod` is called then it returns either the desired result or the string `"TRY_NEXT_METHOD"`, which corresponds to a call to `TryNextMethod` (78.5-1) in the method and means that the method selection would call the next applicable method.

Note: The GAP kernel provides special treatment for the infix operations `\+`, `\-`, `\*`, `\/`, `\^`, `\mod` and `\in`. For some kernel objects (notably cyclotomic numbers, finite field elements and row vectors thereof) it calls kernel methods circumventing the method selection mechanism. Therefore for these operations `ApplicableMethod` may return a method which is not the kernel method actually used.

The function `ApplicableMethodTypes` takes the types or filters of the arguments as argument (if only filters are given of course family predicates cannot be tested).

##### 7.2-2 MethodsOperation

`‣ MethodsOperation`( oper, n ) | ( function )

Return a list of records that describe the installed methods for the operation oper, with n arguments.

Each record has at least the following components.

func

  the method itself, a GAP function,

rank

  the rank of the method, an integer or infinity,

info

  a string that describes when the method is applicable,

location

  filename and start line where the method gets installed.

#### 7.3 Tracing Methods

##### 7.3-1 TraceMethods

`‣ TraceMethods`( opr1, opr2, ... ) | ( function )

`‣ TraceMethods`( oprs ) | ( function )

After the call of `TraceMethods`, whenever a method of one of the operations opr1, opr2, ... is called, the information string used in the installation of the method is printed. The second form has the same effect for each operation from the list oprs of operations.

##### 7.3-2 TraceAllMethods

`‣ TraceAllMethods`( ) | ( function )

Invokes `TraceMethods` for all operations.

##### 7.3-3 UntraceMethods

`‣ UntraceMethods`( opr1, opr2, ... ) | ( function )

`‣ UntraceMethods`( oprs ) | ( function )

turns the tracing off for all operations opr1, opr2, ... or in the second form, for all operations in the list oprs.

    gap> TraceMethods( [ Size ] );
    gap> g:= Group( (1,2,3), (1,2) );;
    gap> Size( g );
    #I  Size: for a permutation group at /gap5/lib/grpperm.gi:487
    #I  Setter(Size): system setter
    #I  Size: system getter
    #I  Size: system getter
    6
    gap> UntraceMethods( [ Size ] );

##### 7.3-4 UntraceAllMethods

`‣ UntraceAllMethods`( ) | ( function )

Equivalent to calling `UntraceMethods` for all operations.

##### 7.3-5 TraceImmediateMethods

`‣ TraceImmediateMethods`( [flag] ) | ( function )

`‣ UntraceImmediateMethods`( ) | ( function )

`TraceImmediateMethods` enables tracing for all immediate methods if flag is either `true`, or not present. `UntraceImmediateMethods`, or `TraceImmediateMethods` with flag equal `false` turns tracing off. (There is no facility to trace specific immediate methods.)

    gap> TraceImmediateMethods( );
    gap> g:= Group( (1,2,3), (1,2) );;
    #I RunImmediateMethods
    #I  immediate: Size
    #I  immediate: IsCyclic
    #I  immediate: IsCommutative
    #I  immediate: IsTrivial
    gap> Size( g );
    #I  immediate: IsPerfectGroup
    #I  immediate: IsNonTrivial
    #I  immediate: Size
    #I  immediate: IsFreeAbelian
    #I  immediate: IsTorsionFree
    #I  immediate: IsNonTrivial
    #I  immediate: IsPerfectGroup
    #I  immediate: GeneralizedPcgs
    #I  immediate: IsEmpty
    6
    gap> UntraceImmediateMethods( );
    gap> UntraceMethods( [ Size ] );

This example gives an explanation for the two calls of the system getter for `Size` (30.4-6). Namely, there are immediate methods that access the known size of the group. Note that the group `g` was known to be finitely generated already before the size was computed, the calls of the immediate method for `IsFinitelyGeneratedGroup` (39.15-18) after the call of `Size` (30.4-6) have other arguments than `g`.

##### 7.3-6 TraceInternalMethods

`‣ TraceInternalMethods`( ) | ( function )

`‣ UntraceInternalMethods`( ) | ( function )

`‣ GetTraceInternalMethodsCounts`( ) | ( function )

`‣ ClearTraceInternalMethodsCounts`( ) | ( function )

`TraceInternalMethods` enables tracing for all internal methods. Internal methods are methods which implement many fundamental operations in GAP. In this version of GAP, the internal methods which can be traced are:

Zero, ZeroMut

  Mutable and Immutable `Zero` (31.10-3)

AInv, AInvMut

  Mutable and Immutable `AdditiveInverse` (31.10-9)

One, OneMut

  Mutable and Immutable `One` (31.10-2)

Inv, InvMut

  Mutable and Immutable `Inverse` (31.10-8)

Sum

  The operator `\+` (31.12-1)

Diff

  The operator `-` operator

Prod

  The operator `\*` (31.12-1)

Quo

  The operator `\/` (31.12-1)

LQuo

  The left-quotient operator

Pow

  The operator `\^` (31.12-1)

Comm

  The operator `Comm` (31.12-3)

Mod

  The operator `\mod` (31.12-1)

`UntraceInternalMethods` turns tracing off. As these methods can be called hundreds of thousands of times in simple GAP code, there isn't a statement printed each time one is called. Instead, the method `GetTraceInternalMethodsCounts` returns how many times each operation has been applied to each type of variable (the type of a variable can be found with the `TNAM_OBJ` method). The return value for two argument operators is a record of records `r`, where `r.op` stores information about operator `op`. For one argument operators `r.op.i` stores how many times `op` was called with an argument of type `i`, while for two argument operators `r.op.i.j` stores how many times `op` was called with arguments of type `i` and `j`.

    gap> TraceInternalMethods();
    true
    gap> 2+3+4+5+6;;
    gap> 2.0+2.0;;
    gap> 3^(1,2,3);;
    gap> GetTraceInternalMethodsCounts();
    rec( Pow := rec( integer := rec( ("permutation (small)") := 1 ) ),
    Sum := rec( integer := rec( integer := 4 ),
        macfloat := rec( macfloat := 1 ) ) )
    # 'macfloat' is a floating point number
    gap> UntraceInternalMethods();

#### 7.4 Info Functions

The `Info` (7.4-6) mechanism permits operations to display intermediate results or information about the progress of the algorithms. Information is always given according to one or more info classes. Each of the info classes defined in the GAP library usually covers a certain range of algorithms, so for example `InfoLattice` covers all the cyclic extension algorithms for the computation of a subgroup lattice.

Note that not all info classes defined in the GAP library are currently documented. Many GAP packages define additional info classes, which are typically documented in the corresponding package documentation. The function `ShowUsedInfoClasses` (7.4-5) will show all info classes which GAP considers while executing code.

The amount of information to be displayed by each info class can be separately specified by the user. This is done by selecting a non-negative integer level for the info class: no information will be displayed at level 0, and the higher the level, the more information that will be displayed. At creation, an info class has level 0. By default, all built-in GAP info classes have level 0, except for the following info classes, which have level 1:

- `InfoWarning` (7.4-8),

- `InfoPackageLoading` (76.2-6),

- `InfoDebug`,

- `InfoPerformance`,

- `InfoTempDirectories`,

- `InfoPrimeInt`, and

- `InfoSLP`.

##### 7.4-1 NewInfoClass

`‣ NewInfoClass`( name ) | ( operation )

creates a new info class with name name.

##### 7.4-2 DeclareInfoClass

`‣ DeclareInfoClass`( name ) | ( function )

creates a new info class with name name and binds it to the global variable name. The variable must previously be writable, and is made read-only by this function.

##### 7.4-3 SetInfoLevel

`‣ SetInfoLevel`( infoclass, level ) | ( operation )

Sets the info level for infoclass to the non-negative integer level.

##### 7.4-4 InfoLevel

`‣ InfoLevel`( infoclass ) | ( operation )

returns the info level of infoclass.

##### 7.4-5 ShowUsedInfoClasses

`‣ ShowUsedInfoClasses`( infoclass ) | ( function )

Called with argument `true`, this makes GAP print the info class and level of any executed `Info` (7.4-6) statement. Calling with the argument `false` stops this printing. Each level of each info class is only printed once. The history of printed info classes and levels is reset whenever `true` is passed.

    gap> ShowUsedInfoClasses(true);
    gap> Intersection(Group((1,3,2,4,5,6)), Group((1,2,3,4,5,6)));
    #I Would print info with SetInfoLevel(InfoBckt,1)
    #I Would print info with SetInfoLevel(InfoBckt,3)
    #I Would print info with SetInfoLevel(InfoBckt,5)
    Group(())
    gap> Intersection(Group((1,3,2,4,5,6)), Group((1,2,3,4,5,6)));
    Group(())
    gap> ShowUsedInfoClasses(false);

##### 7.4-6 Info

`‣ Info`( infoclass, level, info[, moreinfo, ...] ) | ( function )

If the info level of infoclass is at least level, then the remaining arguments, info, and possibly moreinfo and so on, are evaluated. (Technically, `Info` is a keyword and not a function.)

By default, the results of these evaluations are viewed, preceded by the string `"#I "` and followed by a newline.

If the info level of infoclass is strictly less than level, then the third and subsequent arguments are not evaluated. (The latter can save substantial time when displaying difficult results.)

The behaviour can be customized with `SetInfoHandler` (7.4-7).

    gap> InfoExample:=NewInfoClass("InfoExample");;
    gap> Info(InfoExample,1,"one");Info(InfoExample,2,"two");
    gap> SetInfoLevel(InfoExample,1);
    gap> Info(InfoExample,1,"one");Info(InfoExample,2,"two");
    #I  one
    gap> SetInfoLevel(InfoExample,2);
    gap> Info(InfoExample,1,"one");Info(InfoExample,2,"two");
    #I  one
    #I  two
    gap> InfoLevel(InfoExample);
    2
    gap> Info(InfoExample,3,Length(Combinations([1..9999])));

Note that the last `Info` call is executed without problems, since the actual level `2` of `InfoExample` causes `Info` to ignore the last argument, which prevents `Length(Combinations([1..9999]))` from being evaluated; note that an evaluation would be impossible due to memory restrictions.

A set of info classes (called an info selector) may be passed to a single `Info` statement. As a shorthand, info classes and selectors may be combined with `+` rather than `Union` (30.5-3). In this case, the message is triggered if the level of any of the classes is high enough.

    gap> InfoExample:=NewInfoClass("InfoExample");;
    gap> SetInfoLevel(InfoExample,0);
    gap> Info(InfoExample + InfoWarning, 1, "hello");
    #I  hello
    gap> Info(InfoExample + InfoWarning, 2, "hello");
    gap> SetInfoLevel(InfoExample,2);
    gap> Info(InfoExample + InfoWarning, 2, "hello");
    #I  hello
    gap> InfoLevel(InfoWarning);
    1

##### 7.4-7 Customizing `Info` (7.4-6) statements

`‣ SetInfoHandler`( infoclass, handler ) | ( function )

`‣ SetInfoOutput`( infoclass, out ) | ( function )

`‣ UnbindInfoOutput`( infoclass ) | ( function )

`‣ InfoOutput`( infoclass ) | ( function )

`‣ SetDefaultInfoOutput`( out ) | ( function )

Returns: nothing

This allows one to customize what happens in an `Info(infoclass, level, ...)` statement.

In the first function, handler must be a function with three arguments infoclass, level, list. Here list is the list containing the third argument and any subsequent optional arguments of the `Info` (7.4-6) call.

The default handler is the function `DefaultInfoHandler`. It prints `"#I "`, then the third and further arguments of the info statement, and finally a `"\n"`.

If the first argument of an `Info` (7.4-6) statement is a sum of Info classes, the handler of the first summand is used.

The file or stream to which `Info` (7.4-6) statements for individual `Info` (7.4-6) classes print can be overridden with `SetInfoOutput`, retrieved with `InfoOutput` and reset to the default with `UnbindInfoOutput`. The initial default for all `Info` (7.4-6) classes is the string `"*Print*"` which means the current output file. The default can be changed with `SetDefaultInfoOutput`. The argument out can be a filename or an open stream, the special names `"*Print*"`, `"*errout*` and `"*stdout*` are also recognized.

For example, `SetDefaultInfoOutput("*errout*");` would send `Info` (7.4-6) output to standard error, which can be interesting if GAPs output is redirected.

##### 7.4-8 InfoWarning

`‣ InfoWarning` | ( info class )

is an info class to which general warnings are sent at level 1, which is its default level. More specialised warnings are shown via calls of `Info` (7.4-6) at `InfoWarning` level 2, e.g. information about the autoloading of GAP packages and the initial line matched when displaying an on-line help topic.

#### 7.5 Assertions

Assertions are used to find errors in algorithms. They test whether intermediate results conform to required conditions and issue an error if not.

##### 7.5-1 SetAssertionLevel

`‣ SetAssertionLevel`( lev ) | ( function )

assigns the global assertion level to lev. By default it is zero.

##### 7.5-2 AssertionLevel

`‣ AssertionLevel`( ) | ( function )

returns the current assertion level.

##### 7.5-3 Assert

`‣ Assert`( lev, cond[, message] ) | ( function )

With two arguments, if the global assertion level is at least lev, condition cond is tested and if it does not return `true` an error is raised. Thus `Assert(lev, cond)` is equivalent to the code

    if AssertionLevel() >= lev and not <cond> then
      Error("Assertion failure");
    fi;

If the message argument form of the `Assert` statement is provided, and if an error is raised, then this message is printed as part of the error.

Assertions are used at various places in the library. Thus turning assertions on can slow code execution significantly.

#### 7.6 Timing

##### 7.6-1 Runtimes

`‣ Runtimes`( ) | ( function )

`Runtimes` returns a record with components bound to integers or `fail`. Each integer is the cpu time (processor time) in milliseconds spent by GAP in a certain status:

`user_time`

  cpu time spent with GAP functions (without child processes).

`system_time`

  cpu time spent in system calls, e.g., file access (`fail` if not available).

`user_time_children`

  cpu time spent in child processes (`fail` if not available).

`system_time_children`

  cpu time spent in system calls by child processes (`fail` if not available).

Note that this function is not fully supported on all systems. Only the `user_time` component is (and may on some systems include the system time).

The following example demonstrates tasks which contribute to the different time components:

    gap> Runtimes(); # after startup
    rec( user_time := 3980, system_time := 60, user_time_children := 0,
      system_time_children := 0 )
    gap> Exec("cat /usr/bin/*||wc"); # child process with a lot of file access
     893799 7551659 200928302
    gap> Runtimes();
    rec( user_time := 3990, system_time := 60, user_time_children := 1590,
      system_time_children := 600 )
    gap> a:=0;;for i in [1..100000000] do a:=a+1; od; # GAP user time
    gap> Runtimes();
    rec( user_time := 12980, system_time := 70, user_time_children := 1590,
      system_time_children := 600 )
    gap> ?blabla  # first call of help, a lot of file access
    Help: no matching entry found
    gap> Runtimes();
    rec( user_time := 13500, system_time := 440, user_time_children := 1590,
      system_time_children := 600 )

##### 7.6-2 Runtime

`‣ Runtime`( ) | ( function )

`Runtime` returns the time spent by GAP in milliseconds as an integer. It is the same as the value of the `user_time` component given by `Runtimes` (7.6-1), as explained above.

See `StringTime` (27.10-9) for a translation from milliseconds into hour/minute format.

##### 7.6-3 NanosecondsSinceEpoch

`‣ NanosecondsSinceEpoch`( ) | ( function )

`‣ NanosecondsSinceEpochInfo`( ) | ( function )

`NanosecondsSinceEpoch` returns the time in nanoseconds that has passed since some fixed, but unspecified time in the past. This function is appropriate for doing wallclock time measurements. The actual resolution depends on the system that GAP is run on. Information about the used timers can be obtained by calling `NanosecondsSinceEpochInfo`, which returns a record containing members `Method`, `Monotonic`, `Reliable` and `Resolution`.

`Method` is a string describing the method used to obtain timer values. This will usually contain the name of the syscall used.

`Monotonic` is a boolean. If it is `true`, then the values returned by `NanosecondsSinceEpoch` are guaranteed to be strictly monotonically increasing between two calls, if it is `false` then there is no such guarantee.

`Resolution` is an integer reflecting the resolution of the timer used in nanoseconds.

`Reliable` is a boolean. If it is `true` then the value `Resolution` is deemed reliable in the sense that it was obtained by querying the operating system, otherwise `Resolution` should be treated as an estimate.

##### 7.6-4 time

`‣ time` | ( global variable )

In the read-eval-print loop, `time` stores the number of milliseconds the last command took (see also `memory_allocated` (7.7-2) for the number of bytes of memory it allocated).

##### 7.6-5 Sleep

`‣ Sleep`( time ) | ( function )

`‣ MicroSleep`( time ) | ( function )

These functions make GAP stop execution for a given period of time. The time to stop is given to `Sleep` in seconds and `MicroSleep` in microseconds.

#### 7.7 Tracking Memory Usage

##### 7.7-1 TotalMemoryAllocated

`‣ TotalMemoryAllocated`( ) | ( function )

`TotalMemoryAllocated` returns the total amount of memory in bytes allocated by the GAP memory manager since GAP started.

##### 7.7-2 memory_allocated

`‣ memory_allocated` | ( global variable )

In the read-eval-print loop, `memory_allocated` stores the number of bytes of memory allocated by the last completed statement (see also `time` (7.6-4) for the number of milliseconds it took).

#### 7.8 Profiling

Profiling of code can be used to determine in which parts of a program how much time has been spent and how much memory has been allocated during runtime. GAP has two different methods of profiling. GAP can either profile by function, or line-by-line. Line by line profiling is currently only used for code coverage, while function profiling tracks memory and time usage.

##### 7.8-1 Function Profiling

This section describes how to profiling at the function level. The idea is that

- first one switches on profiling for those GAP functions the performance of which one wants to check,

- then one runs some GAP computations,

- then one looks at the profile information collected during these computations,

- then one runs more computations (perhaps clearing all profile information before, see `ClearProfile` (7.8-10)),

- and finally one switches off profiling.

For switching on and off profiling, GAP supports entering a list of functions (see `ProfileFunctions` (7.8-5), `UnprofileFunctions` (7.8-6)) or a list of operations whose methods shall be (un)profiled (`ProfileMethods` (7.8-7), `UnprofileMethods` (7.8-8)), and `DisplayProfile` (7.8-9) can be used to show profile information about functions in a given list.

Besides these functions, `ProfileGlobalFunctions` (7.8-2), `ProfileOperations` (7.8-3), and `ProfileOperationsAndMethods` (7.8-4) can be used for switching on or off profiling for all global functions, operations, and operations together with all their methods, respectively, and for showing profile information about these functions.

Note that GAP will perform more slowly when profiling than when not.

##### 7.8-2 ProfileGlobalFunctions

`‣ ProfileGlobalFunctions`( [bool] ) | ( function )

Called with argument `true`, `ProfileGlobalFunctions` starts profiling of all functions that have been declared via `DeclareGlobalFunction` (79.10-5). Old profile information for all these functions is cleared. A function call with the argument `false` stops profiling of all these functions. Recorded information is still kept, so you can display it even after turning the profiling off.

When `ProfileGlobalFunctions` is called without argument, profile information for all global functions is displayed, see `DisplayProfile` (7.8-9).

##### 7.8-3 ProfileOperations

`‣ ProfileOperations`( [bool] ) | ( function )

Called with argument `true`, `ProfileOperations` starts profiling of all operations. Old profile information for all operations is cleared. A function call with the argument `false` stops profiling of all operations. Recorded information is still kept, so you can display it even after turning the profiling off.

When `ProfileOperations` is called without argument, profile information for all operations is displayed (see `DisplayProfile` (7.8-9)).

##### 7.8-4 ProfileOperationsAndMethods

`‣ ProfileOperationsAndMethods`( [bool] ) | ( function )

Called with argument `true`, `ProfileOperationsAndMethods` starts profiling of all operations and their methods. Old profile information for these functions is cleared. A function call with the argument `false` stops profiling of all operations and their methods. Recorded information is still kept, so you can display it even after turning the profiling off.

When `ProfileOperationsAndMethods` is called without argument, profile information for all operations and their methods is displayed, see `DisplayProfile` (7.8-9).

##### 7.8-5 ProfileFunctions

`‣ ProfileFunctions`( funcs ) | ( function )

starts profiling for all function in the list funcs. You can use `ProfileGlobalFunctions` (7.8-2) to turn profiling on for all globally declared functions simultaneously.

##### 7.8-6 UnprofileFunctions

`‣ UnprofileFunctions`( funcs ) | ( function )

stops profiling for all function in the list funcs. Recorded information is still kept, so you can display it even after turning the profiling off.

##### 7.8-7 ProfileMethods

`‣ ProfileMethods`( ops ) | ( function )

starts profiling of the methods for all operations in the list ops.

##### 7.8-8 UnprofileMethods

`‣ UnprofileMethods`( ops ) | ( function )

stops profiling of the methods for all operations in the list ops. Recorded information is still kept, so you can display it even after turning the profiling off.

##### 7.8-9 DisplayProfile

`‣ DisplayProfile`( [functions][,] [mincount, mintime] ) | ( function )

`‣ GAPInfo.ProfileThreshold` | ( global variable )

Called without arguments, `DisplayProfile` displays the profile information for profiled operations, methods and functions. If an argument functions is given, only profile information for the functions in the list functions is shown. If two integer values mincount, mintime are given as arguments then the output is restricted to those functions that were called at least mincount times or for which the total time spent (see below) was at least mintime milliseconds. The defaults for mincount and mintime are the entries of the list stored in the global variable `GAPInfo.ProfileThreshold`.

The default value of `GAPInfo.ProfileThreshold` is `[ 10000, 30 ]`.

Profile information is displayed in a list of lines for all functions (including operations and methods) which are profiled. For each function, count gives the number of times the function has been called. self/ms gives the time (in milliseconds) spent in the function itself, chld/ms the time (in milliseconds) spent in profiled functions called from within this function, stor/kb the amount of storage (in kilobytes) allocated by the function itself, chld/kb the amount of storage (in kilobytes) allocated by profiled functions called from within this function, and package the name of the GAP package to which the function belongs; the entry GAP in this column means that the function belongs to the GAP library, the entry (oprt.) means that the function is an operation (which may belong to several packages), and an empty entry means that `FilenameFunc` (5.1-4) cannot determine in which file the function is defined.

The list is sorted according to the total time spent in the functions, that is the sum of the values in the columns self/ms and chld/ms.

At the end of the list, two lines are printed that show the total time used and the total memory allocated by the profiled functions not shown in the list (label `OTHER`) and by all profiled functions (label `TOTAL`), respectively.

An interactive variant of `DisplayProfile` is the function `BrowseProfile` (???) that is provided by the GAP package Browse.

##### 7.8-10 ClearProfile

`‣ ClearProfile`( ) | ( function )

clears all stored profile information.

##### 7.8-11 An Example of Function Profiling

Let us suppose we want to get information about the computation of the conjugacy classes of a certain permutation group. For that, first we create the group, then we start profiling for all global functions and for all operations and their methods, then we compute the conjugacy classes, and then we stop profiling.

    gap> g:= PrimitiveGroup( 24, 1 );;
    gap> ProfileGlobalFunctions( true );
    gap> ProfileOperationsAndMethods( true );
    gap> ConjugacyClasses( g );;
    gap> ProfileGlobalFunctions( false );
    gap> ProfileOperationsAndMethods( false );

Now the profile information is available. We can list the information for all profiled functions with `DisplayProfile` (7.8-9).

    gap> DisplayProfile();
      count  self/ms  chld/ms  stor/kb  chld/kb  package  function
      17647        0        0      275        0  GAP      BasePoint
      10230        0        0      226        0  (oprt.)  ShallowCopy
      10139        0        0        0        0           PositionSortedOp: for*
      10001        0        0      688        0           UniteSet: for two int*
      10001        8        0       28      688  (oprt.)  UniteSet
      14751       12        0        0        0           =: for two families: *
      10830        8        4      182      276  GAP      Concatenation
       2700       20       12      313       55  GAP      AddRefinement
       2444       28        4     3924      317  GAP      ConjugateStabChain
       4368        0       32        7      714  (oprt.)  Size
       2174       32        4     1030      116  GAP      List
        585        4       32       45      742  GAP      RRefine
       1532       32        8      194       56  GAP      AddGeneratorsExtendSc*
       1221        8       32      349      420  GAP      Partition
     185309       28       12        0        0  (oprt.)  Length
        336        4       40       95      817  GAP      ExtendSeriesPermGroup
          4       28       20      488      454  (oprt.)  Sortex
       2798        0       52       54      944  GAP      StabChainForcePoint
        560        4       48       83      628  GAP      StabChainSwap
        432       16       40      259      461  GAP      SubmagmaWithInversesNC
     185553       48        8      915       94  (oprt.)  Add
         26        0       64        0     2023  (oprt.)  CentralizerOp
         26        0       64        0     2023  GAP      CentralizerOp: perm g*
         26        0       64        0     2023  GAP      Centralizer: try to e*
        152        4       64        0     2024  (oprt.)  Centralizer
       1605        0       68        0     2032  (oprt.)  StabilizerOfExternalS*
         26        0       68        0     2024  GAP      Meth(StabilizerOfExte*
        382        0       96       69     1922  GAP      TryPcgsPermGroup
       5130        4       96      309     3165  GAP      ForAll
       7980       24      116      330     6434  GAP      ChangeStabChain
      12076       12      136      351     6478  GAP      ProcessFixpoint
        192        0      148        4     3029  GAP      StabChainMutable: cal*
       2208        4      148        3     3083  (oprt.)  StabChainMutable
        217        0      160        0     3177  (oprt.)  StabChainOp
        217       12      148       60     3117  GAP      StabChainOp: group an*
        216       36      464      334    12546  GAP      PartitionBacktrack
       1479       12      668      566    18474  GAP      RepOpElmTuplesPermGro*
       1453       12      684       56    18460  GAP      in: perm class rep
        126        0      728       13    19233  GAP      ConjugacyClassesTry
          1        0      736        0    19671  GAP      ConjugacyClassesByRan*
          2        0      736        2    19678  (oprt.)  ConjugacyClasses
          1        0      736        0    19675  GAP      ConjugacyClasses: per*
      13400     1164        0        0        0  (oprt.)  Position
                 484             12052                    OTHER
                2048             23319                    TOTAL

We can restrict the list to global functions with `ProfileGlobalFunctions` (7.8-2).

    gap> ProfileGlobalFunctions();
      count  self/ms  chld/ms  stor/kb  chld/kb  package  function
      17647        0        0      275        0  GAP      BasePoint
      10830        8        4      182      276  GAP      Concatenation
       2700       20       12      313       55  GAP      AddRefinement
       2444       28        4     3924      317  GAP      ConjugateStabChain
       2174       32        4     1030      116  GAP      List
        585        4       32       45      742  GAP      RRefine
       1532       32        8      194       56  GAP      AddGeneratorsExtendSc*
       1221        8       32      349      420  GAP      Partition
        336        4       40       95      817  GAP      ExtendSeriesPermGroup
       2798        0       52       54      944  GAP      StabChainForcePoint
        560        4       48       83      628  GAP      StabChainSwap
        432       16       40      259      461  GAP      SubmagmaWithInversesNC
        382        0       96       69     1922  GAP      TryPcgsPermGroup
       5130        4       96      309     3165  GAP      ForAll
       7980       24      116      330     6434  GAP      ChangeStabChain
      12076       12      136      351     6478  GAP      ProcessFixpoint
        216       36      464      334    12546  GAP      PartitionBacktrack
       1479       12      668      566    18474  GAP      RepOpElmTuplesPermGro*
        126        0      728       13    19233  GAP      ConjugacyClassesTry
          1        0      736        0    19671  GAP      ConjugacyClassesByRan*
                1804             14536                    OTHER
                2048             23319                    TOTAL

We can restrict the list to operations with `ProfileOperations` (7.8-3).

    gap> ProfileOperations();
      count  self/ms  chld/ms  stor/kb  chld/kb  package  function
      10230        0        0      226        0  (oprt.)  ShallowCopy
      10001        8        0       28      688  (oprt.)  UniteSet
       4368        0       32        7      714  (oprt.)  Size
     185309       28       12        0        0  (oprt.)  Length
          4       28       20      488      454  (oprt.)  Sortex
     185553       48        8      915       94  (oprt.)  Add
         26        0       64        0     2023  (oprt.)  CentralizerOp
        152        4       64        0     2024  (oprt.)  Centralizer
       1605        0       68        0     2032  (oprt.)  StabilizerOfExternalS*
       2208        4      148        3     3083  (oprt.)  StabChainMutable
        217        0      160        0     3177  (oprt.)  StabChainOp
          2        0      736        2    19678  (oprt.)  ConjugacyClasses
      13400     1164        0        0        0  (oprt.)  Position
                 764             21646                    OTHER
                2048             23319                    TOTAL

We can restrict the list to operations and their methods with `ProfileOperationsAndMethods` (7.8-4).

    gap> ProfileOperationsAndMethods();
      count  self/ms  chld/ms  stor/kb  chld/kb  package  function
      10230        0        0      226        0  (oprt.)  ShallowCopy
      10139        0        0        0        0           PositionSortedOp: for*
      10001        0        0      688        0           UniteSet: for two int*
      10001        8        0       28      688  (oprt.)  UniteSet
      14751       12        0        0        0           =: for two families: *
       4368        0       32        7      714  (oprt.)  Size
     185309       28       12        0        0  (oprt.)  Length
          4       28       20      488      454  (oprt.)  Sortex
     185553       48        8      915       94  (oprt.)  Add
         26        0       64        0     2023  (oprt.)  CentralizerOp
         26        0       64        0     2023  GAP      CentralizerOp: perm g*
         26        0       64        0     2023  GAP      Centralizer: try to e*
        152        4       64        0     2024  (oprt.)  Centralizer
       1605        0       68        0     2032  (oprt.)  StabilizerOfExternalS*
         26        0       68        0     2024  GAP      Meth(StabilizerOfExte*
        192        0      148        4     3029  GAP      StabChainMutable: cal*
       2208        4      148        3     3083  (oprt.)  StabChainMutable
        217        0      160        0     3177  (oprt.)  StabChainOp
        217       12      148       60     3117  GAP      StabChainOp: group an*
       1453       12      684       56    18460  GAP      in: perm class rep
          2        0      736        2    19678  (oprt.)  ConjugacyClasses
          1        0      736        0    19675  GAP      ConjugacyClasses: per*
      13400     1164        0        0        0  (oprt.)  Position
                 728             20834                    OTHER
                2048             23319                    TOTAL

Finally, we can restrict the list to explicitly given functions with `DisplayProfile` (7.8-9), by entering the list of functions as an argument.

    gap> DisplayProfile( [ StabChainOp, Centralizer ] );
      count  self/ms  chld/ms  stor/kb  chld/kb  package  function
        152        4       64        0     2024  (oprt.)  Centralizer
        217        0      160        0     3177  (oprt.)  StabChainOp
                2044             23319                    OTHER
                2048             23319                    TOTAL

##### 7.8-12 Line By Line Profiling

Line By Line profiling tracks which lines have been executed in a piece of GAP code. Built into GAP are the methods necessary to generate profiles, the resulting profiles can be displayed with the 'profiling' package.

##### 7.8-13 Line by Line profiling example

There are two kinds of profiles GAP can build:

- Coverage : This records which lines of code are executed

- Timing : This records how much time is spend executing each line of code

A timing profile provides more information, but will take longer to generate and parse. A timing profile is generated using the functions `ProfileLineByLine` (7.8-14) and `UnprofileLineByLine` (7.8-16), as follows:

    gap> ProfileLineByLine("output.gz");
    gap> Size(AlternatingGroup(10)); ; # Execute some GAP code you want to profile
    gap> UnprofileLineByLine();

For code coverage, use instead the functions `CoverageLineByLine` (7.8-15) and `UncoverageLineByLine` (7.8-17). The profiler will only record lines which are read and executed while the profiler is running. If you want to perform code coverage or profile GAP's library, then you can use the GAP command line option '--cover filename.gz', which executes `CoverageLineByLine` (7.8-15) before GAP starts. Similarly the option '--prof filename.gz' executes `ProfileLineByLine` (7.8-14) before GAP starts. The profiler is designed for high performance, because of this, there are some limitations which users should be aware of:

- By default the profiler records the wall-clock time which has passed, rather than the CPU time taken (because it is lower overhead), so any time taken writing commands will be charged to the last GAP statement which was executed. Therefore it is better to write a function which starts profiling, executes your code, and then stops profiling.

- If you end the filename with ".gz", the resulting file will automatically be compressed. This is highly recommended!

- The profiler can only track GAP code which occurs in a function -- this is most obvious when looking at code coverage examples, which will appear to miss lines of code in files not in a function.

- If the current GAP is forked, using the `IO_fork` function in the IO package, a new profile output file will be created for the new child process, with the process ID of the child attached to the end of the filename.

Profiles are transformed into a human-readable form with 'profiling' package, for example with the 'OutputAnnotatedCodeCoverageFiles' function.

##### 7.8-14 ProfileLineByLine

`‣ ProfileLineByLine`( filename[, options] ) | ( function )

`ProfileLineByLine` begins GAP recording profiling data to the file filename. This file will get *very* large very quickly. This file is compressed using gzip to reduce its size. options is an optional dictionary, which sets various configuration options. These are

coverage

  Boolean (defaults to false). If this is enabled, only information about which lines are read and executed is stored. Enabling this is the same as calling `CoverageLineByLine` (7.8-15). Using this ignores all other options.

wallTime

  Boolean (defaults to true). Sets if time should be measured using wall-clock time (true) or CPU time (false). (measuring CPU-time has a higher overhead).

recordMem

  Boolean (defaults to false). Instead of recording the CPU time taken by statements, record the total size of all new objects created by each line.

resolution

  Integer (defaults to 0). By default profiling will record a trace of all executed code. When resolution non-zero, GAP instead samples which piece of code is being executed every resolution nanoseconds. Increasing this improves performance and produces smaller traces, at the cost of accuracy. GAP will still accurately record which statements are executed at least once.

##### 7.8-15 CoverageLineByLine

`‣ CoverageLineByLine`( filename ) | ( function )

`CoverageLineByLine` begins GAP recording code coverage to the file filename. This is equivalent to calling `ProfileLineByLine` (7.8-14) with coverage=true.

##### 7.8-16 UnprofileLineByLine

`‣ UnprofileLineByLine`( ) | ( function )

Stops profiling which was previously started with `ProfileLineByLine` (7.8-14) or `CoverageLineByLine` (7.8-15).

##### 7.8-17 UncoverageLineByLine

`‣ UncoverageLineByLine`( ) | ( function )

Stops profiling which was previously started with `ProfileLineByLine` (7.8-14) or `CoverageLineByLine` (7.8-15).

##### 7.8-18 IsLineByLineProfileActive

`‣ IsLineByLineProfileActive`( ) | ( function )

`IsLineByLineProfileActive` returns if line-by-line profiling is currently activated.

##### 7.8-19 DisplayCacheStats

`‣ DisplayCacheStats`( ) | ( function )

displays statistics about the different caches used by the method selection.

##### 7.8-20 ClearCacheStats

`‣ ClearCacheStats`( ) | ( function )

clears all statistics about the different caches used by the method selection.

#### 7.9 Information about the version used

The global variable `GAPInfo.Version` (see `GAPInfo` (3.5-1)) contains the version number of the version of GAP. Its value can be checked other version number using `CompareVersionNumbers` (76.3-9).

To produce sample citations for the used version of GAP or for a package available in this GAP installation, use `Cite` (76.3-19).

If you wish to report a problem to GAP Support or GAP Forum, it may be useful to not only report the version used, but also to include the GAP banner displays the information about the architecture for which the GAP binary is built, used libraries and loaded packages.

#### 7.10 Test Files

Test files are used to check that GAP produces correct results in certain computations. A selection of test files for the library can be found in the `tst` directory of the GAP distribution.

##### 7.10-1 Starting and stopping test

`‣ START_TEST`( name ) | ( function )

`‣ STOP_TEST`( name ) | ( function )

`START_TEST` and `STOP_TEST` may be optionally used in files that are read via `Test` (7.10-2). If used, `START_TEST` reinitializes

- the caches (see `FlushCaches` (79.10-4)),

- the global random number generators (see `GlobalMersenneTwister` (14.7-4)), and

- the global options stack (see Chapter 8),

in order to be independent of the reading order of several test files.

Furthermore, the assertion level (see `Assert` (7.5-3)) is set to 2 (if it was lower before) by `START_TEST` and set back to the previous value in the subsequent `STOP_TEST` call.

Also `STOP_TEST` reinitializes the global options stack, otherwise it could happen that options which got set during the tests are not reset after the tests.

To use this feature, a test file should be started with a line

    gap> START_TEST( "arbitrary identifier string" );

(Note that the `gap>` prompt is part of the line!)

and should be finished with a line

    gap> STOP_TEST( "same identifier string as for START_TEST" );

If you want to run a quick test of your GAP installation (though this is not required), you can read in a test script that exercises some GAP's capabilities.

    gap> Read( Filename( DirectoriesLibrary( "tst" ), "testinstall.g" ) );

    test file         time(msec)
    -------------------------------------------
    testing: ................/gap4r5/tst/zlattice.tst
    zlattice.tst               0
    testing: ................/gap4r5/tst/gaussian.tst
    gaussian.tst              10
    [ further lines deleted ]

If you want to run a more advanced check (this is not required and make take up to an hour), you can read `teststandard.g` which is an extended test script performing all tests from the `tst` directory.

    gap> Read( Filename( DirectoriesLibrary( "tst" ), "teststandard.g" ) );

##### 7.10-2 Test

`‣ Test`( fname[, optrec] ) | ( function )

Returns: `true` or `false`.

The argument fname must be the name of a file or an open input stream. The content of this file or stream should contain GAP input and output. The function `Test` runs the input lines, compares the actual output with the output stored in fname and reports differences. With an optional record as argument optrec details of this process can be adjusted. Note that the `rewriteToFile` option is especially useful for generating test files.

More precisely, the content of fname must have the following format.
Lines starting with `"gap> "` are considered as GAP input, they can be followed by lines starting with `"> "` if the input is continued over several lines.
To allow for comments in fname the following lines are ignored by default: lines at the beginning of fname that start with `"#"` or are empty, and one empty line together with one or more lines starting with `"#"`.
All other lines are considered as GAP output from the preceding GAP input.

Lines which begin "#@" define special configuration options for tests. The `#@local` and `#@exec` options can only be used before any GAP input, and the other commands can only be used between individual tests (just before a line starting `gap>`, or at end of the file). Currently defined options are:

#@local identifierlist

  Run all the tests in the input as if it is in a function with local variable list `identifierlist`, which is a comma-separated list of identifiers. Multiple #@local lines may be used. These lines should not end with a comma or semicolon. If this option is used then an error will occur unless all the variables used are included in the local list.

  As an example, the Utils package has a test file `tst/iterator.tst` which starts with the lines:

      #@local  c3c3, cart, G, h, it1, it2, iter, iter0, iter4, iterL
      #@local  L, n, pairs0, pairs4, pairsL, s3, s4

#@exec gapcode

  Execute the code `gapcode` before any test in the input is run. This allows defining global variables when using `#@local`.

#@if EXPR ... {#@elif EXPR ...} [#@else ...] #@fi

  A `#@if` allows to conditionally skip parts of the test input depending on the value of a boolean expression. The exact behavior is done as follows:

  If the first GAP expression `EXPR` evaluates to `true`, then the lines after the `#@if` are used until either a `#@elif`, `#@else` or `#@fi` is reached. If an `#@elif` is present, then the lines after `#@elif` are used if and only if its `EXPR` evaluates to `true` and all previous `#@if` and `#@elif` clauses had expressions evaluating to `false`. In this case the lines after `#@elif` are used until either a `#@elif`, `#@else` or `#@fi` is reached. If an `#@else` is present then the lines after the `#@else` are used if and only if `EXPR` evaluated to `false` in all `#@if` and `#@elif` clauses. Finally, once `#fi` is reached, evaluation continues normally.

  Note that each `EXPR` is evaluated after all `#@exec` lines have been executed but before any tests are run. Thus, it cannot depend on test results or packages loaded in tests, but it can depend on packages loaded via `#@exec`.

  In addition `#@if` clauses cannot be nested within each other.

  As an example, the GAP test suite contains the test file `tst/testinstall/pperm.tst` which contains the lines:

      #@if GAPInfo.BytesPerVariable = 8
      gap> HASH_FUNC_FOR_PPERM(f, 10 ^ 6) in [260581, 402746];
      true
      #@else
      gap> HASH_FUNC_FOR_PPERM(f, 10 ^ 6);
      953600
      #@fi

By default the actual GAP output is compared exactly with the stored output, and if these are different some information about the differences is printed.

If any differences are found then `Test` returns `false`, otherwise `true`.

If the optional argument optrec is given it must be a record. The following components of optrec are recognized and can change the default behaviour of `Test`:

`ignoreComments`

  If set to `false` then no lines in fname are ignored as explained above (default is `true`).

`width`

  The screen width used for the new output (default is `80`).

`compareFunction`

  This must be a function that gets two strings as input, the newly generated and the stored output of some GAP input. The function must return `true` or `false`, indicating if the strings should be considered equivalent or not. By default `\=` (31.11-1) is used.
  Two strings are recognized as abbreviations in this component: `"uptowhitespace"` checks if the two strings become equal after removing all white space. And `"uptonl"` compares the string up to trailing newline characters.

`transformFunction`

  This must be a function that gets one string as input, either the newly generated or the stored output of some GAP input. The function must return a new string which will be used to compare the actual and the expected output. By default `IdFunc` (5.4-6) is used.
  Two strings are recognized as abbreviations in this component: `"removewhitespace"` removes all white space. And `"removenl"` removes all trailing newline characters.

`reportDiff`

  A function that gets six arguments and reports a difference in the output: the GAP input, the expected GAP output, the newly generated output, the name of tested file, the line number of the input, the time to run the input. (The default is demonstrated in the example below.)

`rewriteToFile`

  If this is bound to a string it is considered as a file name and that file is written with the same input and comment lines as fname but the output substituted by the newly generated version; if it is bound to `true`, then this is treated as if it was bound to fname (default is `false`). This is especially useful for generating test files because it ensures that the test files are formatted exactly as `Test` expects them to be.

`writeTimings`

  If this is bound to a string it is considered as a file name, that file is written and contains timing information for each input in fname.

`compareTimings`

  If this is bound to a string it is considered as name of a file to which timing information was stored via `writeTimings` in a previous call. The new timings are compared to the stored ones. By default only commands which take more than a threshold of 100 milliseconds are considered, and only differences of more than 20% are considered significant. These defaults can be overwritten by assigning a list `[timingfile, threshold, percentage]` to this component. (The default of `compareTimings` is `false`.)

`reportTimeDiff`

  This component can be used to overwrite the default function to display timing differences. It must be a function with 5 arguments: GAP input, name of test file, line number, stored time, new time.

`ignoreSTOP_TEST`

  By default set to `true`, in that case the output of GAP input starting with `"STOP_TEST"` is not checked.

`showProgress`

  If this is `true` then GAP prints position information and the input line before it is processed; if set to `"some"`, then GAP shows the current line number of the test being processed; if set to `false`, no progress updates are displayed (default is `"some"` if GAP's output goes to a terminal, otherwise `false`).

`subsWindowsLineBreaks`

  If this is `true` then GAP substitutes DOS/Windows style line breaks "\r\n" by UNIX style line breaks "\n" after reading the test file. (default is `true`).

`returnNumFailures`

  If this is `true` then GAP returns the number of input lines of the test file which had differences in their output, instead of returning `true` or `false`.

    gap> tnam := Filename(DirectoriesLibrary(), "../doc/ref/demo.tst");;
    gap> mask := function(str) return Concatenation("| ",
    >          JoinStringsWithSeparator(SplitString(str, "\n", ""), "\n| "),
    >          "\n"); end;;
    gap> Print(mask(StringFile(tnam)));
    | # this is a demo file for the 'Test' function
    | #
    | gap> g := Group((1,2), (1,2,3));
    | Group([ (1,2), (1,2,3) ])
    |
    | # another comment following an empty line
    | # the following fails:
    | gap> a := 13+29;
    | 41
    gap> ss := InputTextString(StringFile(tnam));;
    gap> Test(ss);
    ########> Diff in test stream, line 8:
    # Input is:
    a := 13+29;
    # Expected output:
    41
    # But found:
    42
    ########
    false
    gap> RewindStream(ss);
    true
    gap> dtmp := DirectoryTemporary();;
    gap> ftmp := Filename(dtmp,"demo.tst");;
    gap> Test(ss, rec(reportDiff := Ignore, rewriteToFile := ftmp));
    false
    gap> Test(ftmp);
    true
    gap> Print(mask(StringFile(ftmp)));
    | # this is a demo file for the 'Test' function
    | #
    | gap> g := Group((1,2), (1,2,3));
    | Group([ (1,2), (1,2,3) ])
    |
    | # another comment following an empty line
    | # the following fails:
    | gap> a := 13+29;
    | 42

##### 7.10-3 TestDirectory

`‣ TestDirectory`( inlist[, optrec] ) | ( function )

Returns: `true` or `false`.

The argument inlist must be either a single filename or directory name, or a list of filenames and directories. The function `TestDirectory` will create a list of files to be tested by taking any files in inlist, and recursively searching any directories in inlist for files ending in `.tst`. Each of these files is then run through `Test` (7.10-2), and the results printed, and `true` returned if all tests passed.

If the optional argument optrec is given it must be a record. Note that the `rewriteToFile` option is especially useful for generating test files. The following components of optrec are recognized and can change the default behaviour of `TestDirectory`:

`testOptions`

  A record which will be passed on as the second argument of `Test` (7.10-2) if present.

`earlyStop`

  If `true`, stop as soon as any `Test` (7.10-2) fails (defaults to `false`).

`showProgress`

  Print information about how tests are progressing (defaults to `"some"` if GAP's output goes to a terminal, otherwise `false`).

`suppressStatusMessage`

  suppress displaying status messages `#I Errors detected while testing` and `#I No errors detected while testing` after the test (defaults to `false`).

`rewriteToFile`

  If `true`, then rewrite each test file to disc, with the output substituted by the results of running the test (defaults to `false`). This is especially useful for generating test files because it ensures that the test files are formatted exactly as `Test` (7.10-2) expects them to be.

`exclude`

  A list of file and directory names which will be excluded from testing (defaults to `[]`).

`exitGAP`

  Rather than returning `true` or `false`, exit GAP with the return value of GAP set to success or fail, depending on if all tests passed (defaults to `false`).

See also `TestPackage` (76.3-5) for the information on running standard tests for GAP packages.

#### 7.11 Debugging Recursion

The GAP interpreter monitors the level of nesting of GAP functions during execution. By default, whenever this nesting reaches a multiple of 5000, GAP enters a break loop (6.4) allowing you to terminate the calculation, or enter Return`;` to continue it.

    gap> dive:= function(depth) if depth>1 then dive(depth-1); fi; return; end;
    function( depth ) ... end
    gap> dive(100);
    gap> OnBreak:= function() Where(2); end;; # shorter traceback
    gap> dive(6000);
    Error, recursion depth trap (5000)
    *[1] dive( depth - 1 );
       @ *stdin*:1
     [2] dive( depth - 1 );
       @ *stdin*:1
    ...  at *stdin*:4
    you may 'return;'
    brk> return;
    gap> dive(11000);
    Error, recursion depth trap (5000)
    *[1] dive( depth - 1 );
       @ *stdin*:1
     [2] dive( depth - 1 );
       @ *stdin*:1
    ...  at *stdin*:5
    you may 'return;'
    brk> return;
    Error, recursion depth trap (10000)
    *[1] dive( depth - 1 );
       @ *stdin*:1
     [2] dive( depth - 1 );
       @ *stdin*:1
    ...  at *stdin*:5
    you may 'return;'
    brk> return;gap>

This behaviour can be controlled using the following procedures.

##### 7.11-1 SetRecursionTrapInterval

`‣ SetRecursionTrapInterval`( interval ) | ( function )

`‣ GetRecursionDepth`( ) | ( function )

`GetRecursionDepth` returns the nesting level of the GAP interpreter. This is reset to 0 every time the break loop is entered. `SetRecursionTrapInterval` sets the depth of the stack at which GAP will enter the Break loop. interval must be a non-negative small integer (between 0 and 2^28). An interval of 0 suppresses the monitoring of recursion altogether. In this case excessive recursion may cause GAP to crash.

    gap> GetRecursionDepth();
    0
    gap> dive := function(depth)
    >  if depth>1 then
    >    dive(depth-1);
    >  else
    >    Print("Depth ", GetRecursionDepth());
    >  fi;
    > end;;
    gap> SetRecursionTrapInterval(1000);
    gap> OnBreak:= function() Where(2); end;; # shorter traceback
    gap> dive(100);
    Depth 100
    gap> dive(2500);
    Error, recursion depth trap (1000)
    *[1] dive( depth - 1 );
       @ *stdin*:4
     [2] dive( depth - 1 );
       @ *stdin*:4
    ...  at *stdin*:12
    you may 'return;'
    brk> return;
    Error, recursion depth trap (2000)
    *[1] dive( depth - 1 );
       @ *stdin*:4
     [2] dive( depth - 1 );
       @ *stdin*:4
    ...  at *stdin*:12
    you may 'return;'
    brk> GetRecursionDepth();
    0
    brk> return;
    gap> SetRecursionTrapInterval(2^50);
    gap> dive(20000);
    Depth 20000
    gap> dive(2000000);
    Segmentation fault

#### 7.12 Global Memory Information

##### 7.12-1 Garbage Collection

The GAP environment provides automatic memory management, so that the programmer does not need to concern themselves with allocating space for objects, or recovering space when objects are no longer needed. The memory manager that shall be used by GAP is specified at compile time. One of the choices is called `GASMAN` (GAP Storage MANager). (The name of the currently used garbage collector is stored in the variable `GAPInfo.KernelInfo.GC`.)

If GAP uses `GASMAN` then messages reporting garbage collections performed by `GASMAN` can be switched on by the `-g` command line option (see section 3.1). There are also some facilities to access information from `GASMAN` from GAP programs, see below.

##### 7.12-2 CollectGarbage

`‣ CollectGarbage`( full ) | ( function )

Returns: nothing.

This function forces a garbage collection. If full is `true` then it triggers a full garbage collection, otherwise a partial one.

GAP invokes its garbage collector automatically, thus there is normally no need to call `CollectGarbage`.

The function `CollectGarbage` was introduced in GAP 4.12. In older GAP versions, one can use `GASMAN( "collect" )` (if full is `true`) or `GASMAN( "partial" )` (if full is not `true`) instead.

    gap> CollectGarbage( false );
    gap> CollectGarbage( true );

##### 7.12-3 GasmanStatistics

`‣ GasmanStatistics`( ) | ( function )

This function is meaningful only if `GASMAN` is the garbage collector used by GAP, see Section 7.12-1.

`GasmanStatistics` returns a record containing some information from the garbage collection mechanism. The record may contain up to four components: `full`, `partial`, `npartial`, and `nfull`.

The `full` component will be present if a full garbage collection has taken place since GAP started. It contains information about the most recent full garbage collection. It is a record, with eight components: `livebags` contains the number of bags which survived the garbage collection; `livekb` contains the total number of kilobytes occupied by those bags; `deadbags` contains the total number of bags which were reclaimed by that garbage collection and all the partial garbage collections preceding it, since the previous full garbage collection; `deadkb` contains the total number of kilobytes occupied by those bags; `freekb` reports the total number of kilobytes available in the GAP workspace for new objects; `totalkb` reports the actual size of the workspace; `time` reports the CPU time in milliseconds spent on the last garbage collection and `cumulative` the total CPU time in milliseconds spent on that type of garbage collection since GAP started.

These figures should be viewed with some caution. They are stored internally in fixed length integer formats, and `deadkb` and `deadbags` are liable to overflow if there are many partial collections before a full collection. Also, note that `livekb` and `freekb` will not usually add up to `totalkb`. The difference is essentially the space overhead of the memory management system.

The `partial` component will be present if there has been a partial garbage collection since the last full one. It is also a record with the same six components as `full`. In this case `deadbags` and `deadkb` refer only to the number and total size of the garbage bags reclaimed in this partial garbage collection and `livebags`and `livekb` only to the numbers and total size of the young bags that were considered for garbage collection, and survived.

The `npartial` and `nfull` components will contain the number of full and partial garbage collections performed since GAP started.

##### 7.12-4 GasmanMessageStatus

`‣ GasmanMessageStatus`( ) | ( function )

`‣ SetGasmanMessageStatus`( stat ) | ( function )

This function is meaningful only if `GASMAN` is the garbage collector used by GAP, see Section 7.12-1.

`GasmanMessageStatus` returns one of the strings `"none"`, `"full"`, or `"all"`, depending on whether the garbage collector is currently set to print messages on no collections, full collections only, or all collections, respectively.

Calling `SetGasmanMessageStatus` with the argument stat, which should be one of the three strings mentioned above, sets the garbage collector messaging level.

##### 7.12-5 GasmanLimits

`‣ GasmanLimits`( ) | ( function )

This function is meaningful only if `GASMAN` is the garbage collector used by GAP, see Section 7.12-1.

`GasmanLimits` returns a record with three components: `min` is the minimum workspace size as set by the `-m` command line option in kilobytes. The workspace size will never be reduced below this by the garbage collector. `max` is the maximum workspace size, as set by the `-o` command line option, also in kilobytes. If the workspace would need to grow past this point, GAP will enter a break loop to warn the user. A value of 0 indicates no limit. `kill` is the absolute maximum, set by the `-K` command line option. The workspace will never be allowed to grow past this limit.

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 Bib Ind

generated by GAPDoc2HTML