<html><head><title>[ref] 7 Debugging and Profiling Facilities</title></head>
<body text="#000000" bgcolor="#ffffff">
[<a href="../index.htm">Top</a>] [<a href = "chapters.htm">Up</a>] [<a href ="CHAP006.htm">Previous</a>] [<a href ="CHAP008.htm">Next</a>] [<a href = "theindex.htm">Index</a>]
<h1>7 Debugging and Profiling Facilities</h1><p>
<P>
<H3>Sections</H3>
<oL>
<li> <A HREF="CHAP007.htm#SECT001">Recovery from NoMethodFound-Errors</a>
<li> <A HREF="CHAP007.htm#SECT002">ApplicableMethod</a>
<li> <A HREF="CHAP007.htm#SECT003">Tracing Methods</a>
<li> <A HREF="CHAP007.htm#SECT004">Info Functions</a>
<li> <A HREF="CHAP007.htm#SECT005">Assertions</a>
<li> <A HREF="CHAP007.htm#SECT006">Timing</a>
<li> <A HREF="CHAP007.htm#SECT007">Profiling</a>
<li> <A HREF="CHAP007.htm#SECT008">Information about the version used</a>
<li> <A HREF="CHAP007.htm#SECT009">Test Files</a>
<li> <A HREF="CHAP007.htm#SECT010">Debugging Recursion</a>
<li> <A HREF="CHAP007.htm#SECT011">Global Memory Information</a>
</ol><p>
<p>
This chapter describes some functions that are useful mainly for
debugging and profiling purposes.
<p>
The sections <a href="CHAP007.htm#SSEC002.1">ApplicableMethod</a> and <a href="CHAP007.htm#SECT003">Tracing Methods</a> show how to get
information about the methods chosen by the method selection mechanism
(see chapter <a href="../prg/CHAP002.htm">Method Selection</a> in the programmer's manual).
<p>
The final sections describe functions for collecting statistics about
computations (see <a href="CHAP007.htm#SSEC006.2">Runtime</a>, <a href="CHAP007.htm#SECT007">Profiling</a>).
<p>
<p>
<h2><a name="SECT001">7.1 Recovery from NoMethodFound-Errors</a></h2>
<p><p>
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:
<p>
<pre>
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 called from
<function>( <arguments> ) called from read-eval-loop
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
brk>
</pre>
<p>
This only says, that the method selection tried to find a method for
<code>IsNormal</code> 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 <code>quit</code> command (see <a href="CHAP006.htm#SSEC004.1">quit</a>)
and that the information about the incident is no longer accessible
afterwards.
<p>
<a name = "SSEC001.1"></a>
<li><code>ShowArguments( ) F</code>
<p>
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.
<p>
<a name = "SSEC001.2"></a>
<li><code>ShowArgument( </code><var>nr</var><code> ) F</code>
<p>
This function is only available within a break loop caused by a ``No
Method Found''-error. It prints the <var>nr</var>-th arguments of the operation call
for which no method was found. <code>ShowArgument</code> needs exactly one
argument which is an integer between 0 and the number of arguments the
operation was called with.
<p>
<a name = "SSEC001.3"></a>
<li><code>ShowDetails( ) F</code>
<p>
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 <code>TryNextMethod</code>. The last number is called
<code>Choice</code> and is printed as an ordinal. So if exactly <i>k</i> methods were
found but called <code>TryNextMethod</code> and there were no more methods it says
<code>Choice: <i>k</i>th</code>.
<p>
<a name = "SSEC001.4"></a>
<li><code>ShowMethods( ) F</code>
<li><code>ShowMethods( </code><var>verbosity</var><code> ) F</code>
<p>
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
<code>ApplicableMethod</code>, see <a href="CHAP007.htm#SSEC002.1">ApplicableMethod</a>). The verbosity can be
controlled by the optional integer parameter <var>verbosity</var>. The default
is 2, which lists all applicable methods. With verbosity 1
<code>ShowMethods</code> 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 <code>TryNextMethod</code>. With verbosity 3 not only
all installed methods but also the reasons why they do not match are
displayed.
<p>
<a name = "SSEC001.5"></a>
<li><code>ShowOtherMethods( ) F</code>
<li><code>ShowOtherMethods( </code><var>verbosity</var><code> ) F</code>
<p>
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 <code>ApplicableMethod</code>, see
<a href="CHAP007.htm#SSEC002.1">ApplicableMethod</a>). The verbosity can be controlled by the optional
integer parameter <var>verbosity</var>. The default is 1 which lists only the
number of applicable methods. With verbosity 2 <code>ShowOtherMethods</code> lists
all installed methods and with verbosity 3 also the reasons, why they
are not applicable. Calling <code>ShowOtherMethods</code> 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.
<p>
<p>
<h2><a name="SECT002">7.2 ApplicableMethod</a></h2>
<p><p>
<a name = "SSEC002.1"></a>
<li><code>ApplicableMethod( </code><var>opr</var><code>, </code><var>args</var><code> [, </code><var>printlevel</var><code> ] ) F</code>
<li><code>ApplicableMethod( </code><var>opr</var><code>, </code><var>args</var><code>, </code><var>printlevel</var><code>, </code><var>nr</var><code> ) F</code>
<li><code>ApplicableMethod( </code><var>opr</var><code>, </code><var>args</var><code>, </code><var>printlevel</var><code>, "all" ) F</code>
<a name = "SSEC002.1"></a>
<li><code>ApplicableMethodTypes( </code><var>opr</var><code>, </code><var>args</var><code> [, </code><var>printlevel</var><code> ] ) F</code>
<li><code>ApplicableMethodTypes( </code><var>opr</var><code>, </code><var>args</var><code>, </code><var>printlevel</var><code>, </code><var>nr</var><code> ) F</code>
<li><code>ApplicableMethodTypes( </code><var>opr</var><code>, </code><var>args</var><code>, </code><var>printlevel</var><code>, "all" ) F</code>
<p>
In the first form, <code>ApplicableMethod</code> returns the method of highest rank
that is applicable for the operation <var>opr</var> with the arguments in the
list <var>args</var>.
The default <var>printlevel</var> is <code>0</code>.
If no method is applicable then <code>fail</code> is returned.
<p>
In the second form, if <var>nr</var> is a positive integer then
<code>ApplicableMethod</code> returns the <var>nr</var>-th applicable method for the
operation <var>opr</var> with the arguments in the list <var>args</var>, where the methods
are ordered according to descending rank. If less than <var>nr</var> methods are
applicable then <code>fail</code> is returned.
<p>
If the fourth argument is the string <code>"all"</code> then <code>ApplicableMethod</code>
returns a list of all applicable methods for <var>opr</var> with arguments
<var>args</var>, ordered according to descending rank.
<p>
Depending on the integer value <var>printlevel</var>, additional information is
printed. Admissible values and their meaning are as follows.
<p>
<dl compact>
<dt>0<dd>
no information,
<p>
<dt>1<dd>
information about the applicable method,
<p>
<dt>2<dd>
also information about the not applicable methods of higher rank,
<p>
<dt>3<dd>
also for each not applicable method the first reason why it is not
applicable,
<p>
<dt>4<dd>
also for each not applicable method all reasons why it is not
applicable.
<p>
<dt>6<dd>
also the function body of the selected method(s)
</dl>
<p>
When a method returned by <code>ApplicableMethod</code> is called then it returns
either the desired result or the string <code>TRY_NEXT_METHOD</code>, which
corresponds to a call to <code>TryNextMethod</code> in the method and means that
the method selection would call the next applicable method.
<p>
<strong>Note:</strong> The kernel provides special treatment for the infix operations
<code>\+</code>, <code>\-</code>, <code>\*</code>, <code>\/</code>, <code>\^</code>, <code>\mod</code> and <code>\in</code>. For some kernel
objects (notably cyclotomic numbers, finite field elements and vectors
thereof) it calls kernel methods circumventing the method selection
mechanism. Therefore for these operations <code>ApplicableMethod</code> may return
a method which is not the kernel method actually used.
<p>
<code>ApplicableMethod</code> does not work for constructors (for example
<code>GeneralLinearGroupCons</code> is a constructor).
<p>
The function <code>ApplicableMethodTypes</code> takes the <strong>types</strong> or <strong>filters</strong> of
the arguments as argument (if only filters are given of course family
predicates cannot be tested).
<p>
<p>
<h2><a name="SECT003">7.3 Tracing Methods</a></h2>
<p><p>
<a name = "SSEC003.1"></a>
<li><code>TraceMethods( </code><var>oprs</var><code> ) F</code>
<p>
After the call of <code>TraceMethods</code> with a list <var>oprs</var> of operations,
whenever a method of one of the operations in <var>oprs</var> is called the
information string used in the installation of the method is printed.
<p>
<a name = "SSEC003.2"></a>
<li><code>UntraceMethods( </code><var>oprs</var><code> ) F</code>
<p>
turns the tracing off for all operations in <var>oprs</var>.
<p>
<pre>
gap> TraceMethods( [ Size ] );
gap> g:= Group( (1,2,3), (1,2) );;
gap> Size( g );
#I Size: for a permutation group
#I Setter(Size): system setter
#I Size: system getter
#I Size: system getter
6
gap> UntraceMethods( [ Size ] );
</pre>
<p>
<a name = "SSEC003.3"></a>
<li><code>TraceImmediateMethods( </code><var>flag</var><code> ) F</code>
<p>
If <var>flag</var> is true, tracing for all immediate methods is turned on.
If <var>flag</var> is false it is turned off.
(There is no facility to trace <strong>specific</strong> immediate methods.)
<p>
<pre>
gap> TraceImmediateMethods( true );
gap> g:= Group( (1,2,3), (1,2) );;
#I immediate: Size
#I immediate: IsCyclic
#I immediate: IsCommutative
#I immediate: IsTrivial
gap> Size( g );
#I immediate: IsNonTrivial
#I immediate: Size
#I immediate: IsNonTrivial
#I immediate: GeneralizedPcgs
#I immediate: IsPerfectGroup
#I immediate: IsEmpty
6
gap> TraceImmediateMethods( false );
gap> UntraceMethods( [ Size ] );
</pre>
<p>
This example gives an explanation for the two calls of the
``system getter'' for <code>Size</code>.
Namely, there are immediate methods that access the known size
of the group.
Note that the group <code>g</code> was known to be finitely generated already
before the size was computed,
the calls of the immediate method for <code>IsFinitelyGeneratedGroup</code>
after the call of <code>Size</code> have other arguments than <code>g</code>.
<p>
<p>
<h2><a name="SECT004">7.4 Info Functions</a></h2>
<p><p>
The <code>Info</code> mechanism permits operations to display intermediate results or
information about the progress of the algorithms.
Information is always given according to one or more <strong>info classes</strong>. Each of the
info classes defined in the <font face="Gill Sans,Helvetica,Arial">GAP</font> library usually covers a certain range
of algorithms, so for example <code>InfoLattice</code> covers all the cyclic extension
algorithms for the computation of a subgroup lattice.
<p>
The amount of information to be displayed can be specified by the user for
each info class separately by a <strong>level</strong>, the higher the level the more
information will be displayed.
Ab initio all info classes have level zero except <code>InfoWarning</code>
(see <a href="CHAP007.htm#SSEC004.6">InfoWarning</a>) which initially has level 1.
<p>
<a name = "SSEC004.1"></a>
<li><code>NewInfoClass( </code><var>name</var><code> ) O</code>
<p>
creates a new info class with name <var>name</var>.
<p>
<a name = "SSEC004.2"></a>
<li><code>DeclareInfoClass( </code><var>name</var><code> ) F</code>
<p>
creates a new info class with name <var>name</var> and binds it to the global
variable <var>name</var>. The variable must previously be writable, and is made
readonly by this function.
<p>
<a name = "SSEC004.3"></a>
<li><code>SetInfoLevel( </code><var>infoclass</var><code>, </code><var>level</var><code> ) O</code>
<p>
Sets the info level for <var>infoclass</var> to <var>level</var>.
<p>
<a name = "SSEC004.4"></a>
<li><code>InfoLevel( </code><var>infoclass</var><code> ) O</code>
<p>
returns the info level of <var>infoclass</var>.
<p>
<a name = "SSEC004.5"></a>
<li><code>Info( </code><var>infoclass</var><code>, </code><var>level</var><code>, </code><var>info</var><code> [,</code><var>moreinfo</var><code> . . .] )</code>
<p>
If the info level of <var>infoclass</var> is at least <var>level</var> the remaining
arguments (<var>info</var> and possibly <var>moreinfo</var> and so on) are evaluated and
viewed, preceded by '#I ' and followed by a newline. Otherwise the
third and subsequent arguments are not evaluated. (The latter can save
substantial time when displaying difficult results.)
<p>
<pre>
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])));
</pre>
<p>
Note that the last <code>Info</code> call is executed without problems,
since the actual level <code>2</code> of <code>InfoExample</code> causes <code>Info</code> to ignore
the last argument, which prevents <code>Length(Combinations([1..9999]))</code>
from being evaluated;
note that an evaluation would be impossible due to memory restrictions.
<p>
A set of info classes (called an <strong>info selector</strong>) may be passed to a
single <code>Info</code> statement. As a shorthand, info classes and selectors
may be combined with <code>+</code> rather than <code>Union</code>. In this case, the
message is triggered if the level of <strong>any</strong> of the classes is high enough.
<p>
<pre>
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
</pre>
<p>
<a name = "SSEC004.6"></a>
<li><code>InfoWarning V</code>
<p>
is an info class to which general warnings are sent at level 1, which is
its default level. More specialised warnings are <code>Info</code>-ed at <code>InfoWarning</code>
level 2, e.g. information about the autoloading of <font face="Gill Sans,Helvetica,Arial">GAP</font> packages and the
initial line matched when displaying an on-line help topic.
<p>
<p>
<h2><a name="SECT005">7.5 Assertions</a></h2>
<p><p>
Assertions are used to find errors in algorithms.
They test whether intermediate results conform to required conditions
and issue an error if not.
<p>
<a name = "SSEC005.1"></a>
<li><code>SetAssertionLevel( </code><var>lev</var><code> ) F</code>
<p>
assigns the global assertion level to <var>lev</var>. By default it is zero.
<p>
<a name = "SSEC005.2"></a>
<li><code>AssertionLevel() F</code>
<p>
returns the current assertion level.
<p>
<a name = "SSEC005.3"></a>
<li><code>Assert( </code><var>lev</var><code>, </code><var>cond</var><code> ) F</code>
<li><code>Assert( </code><var>lev</var><code>, </code><var>cond</var><code>, </code><var>message</var><code> ) F</code>
<p>
With two arguments, if the global assertion level is at least <var>lev</var>,
condition <var>cond</var> is tested and if it does not return <code>true</code> an error is
raised.
Thus <code>Assert(lev, </code><var>cond</var><code>)</code> is equivalent to the code
<pre>
if AssertionLevel() >= lev and not <cond> then
Error("Assertion failure");
fi;
</pre>
<p>
With the <var>message</var> argument form of the <code>Assert</code> statement, if the global
assertion level is at least <var>lev</var>, condition <var>cond</var> is tested and if it
does not return <code>true</code> then <var>message</var> is evaluated and printed.
<p>
Assertions are used at various places in the library.
Thus turning assertions on can slow code execution significantly.
<p>
<p>
<h2><a name="SECT006">7.6 Timing</a></h2>
<p><p>
<a name = "SSEC006.1"></a>
<li><code>Runtimes() F</code>
<p>
<code>Runtimes</code> returns a record with components bound to integers or <code>fail</code>.
Each integer
is the cpu time (processor time) in milliseconds spent by <font face="Gill Sans,Helvetica,Arial">GAP</font> in a
certain status:
<p>
<dl compact>
<dt><dd><code>user_time</code> cpu time spent with <font face="Gill Sans,Helvetica,Arial">GAP</font> functions (without child
processes).
<dt><dd><code>system_time</code> cpu time spent in system calls, e.g., file access
(<code>fail</code> if not available).
<dt><dd><code>user_time_children</code> cpu time spent in child processes (<code>fail</code> if not available).
<dt><dd><code>system_time_children</code> cpu time spent in system calls by child
processes (<code>fail</code> if not available).
</dl>
<p>
Note that this function is not fully supported on all systems. Only the
<code>user_time</code> component is (and may on some systems include the system
time).
<p>
The following example demonstrates tasks which contribute to the different
time components:
<p>
<pre>
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 )
</pre>
<p>
<a name = "SSEC006.2"></a>
<li><code>Runtime() F</code>
<p>
<code>Runtime</code> returns the time spent by <font face="Gill Sans,Helvetica,Arial">GAP</font> in milliseconds as an integer.
It is the same as the value of the <code>user_time</code> component given by <code>Runtimes</code>,
as explained above.
<p>
See <code>StringTime</code> (<a href="CHAP026.htm#SSEC008.9">StringTime</a>) for a translation from milliseconds into
hour/minute format.
<p>
<a name = "SSEC006.3"></a>
<li><code>time;</code>
<p>
in the read-eval-print loop returns the time the last command took.
<p>
<p>
<h2><a name="SECT007">7.7 Profiling</a></h2>
<p><p>
Profiling of code can be used to determine in which parts of a program how
much time has been spent during runtime.
<p>
<a name = "SSEC007.1"></a>
<li><code>ProfileOperations( [</code><var>true/false</var><code>] ) F</code>
<p>
When called with argument <var>true</var>, this function starts profiling of all
operations.
Old profiling information is cleared.
When called with <var>false</var> it stops profiling of all operations.
Recorded information is still kept,
so you can display it even after turning the profiling off.
<p>
When called without argument, profiling information for all profiled
operations is displayed (see <a href="CHAP007.htm#SSEC007.8">DisplayProfile</a>).
<p>
<a name = "SSEC007.2"></a>
<li><code>ProfileOperationsAndMethods( [</code><var>true/false</var><code>] ) F</code>
<p>
When called with argument <var>true</var>, this function starts profiling of all
operations and their methods.
Old profiling information is cleared.
When called with <var>false</var> it stops profiling of all operations and their
methods.
Recorded information is still kept,
so you can display it even after turning the profiling off.
<p>
When called without argument, profiling information for all profiled
operations and their methods is displayed (see <a href="CHAP007.htm#SSEC007.8">DisplayProfile</a>).
<p>
<a name = "SSEC007.3"></a>
<li><code>ProfileMethods( </code><var>ops</var><code> ) F</code>
<p>
starts profiling of the methods for all operations in <var>ops</var>.
<p>
<a name = "SSEC007.4"></a>
<li><code>UnprofileMethods( </code><var>ops</var><code> ) F</code>
<p>
stops profiling of the methods for all operations in <var>ops</var>. Recorded
information is still kept, so you can display it even after turning the
profiling off.
<p>
<a name = "SSEC007.5"></a>
<li><code>ProfileFunctions( </code><var>funcs</var><code> ) F</code>
<p>
turns profiling on for all function in <var>funcs</var>. You can use
<code>ProfileGlobalFunctions</code> (see <a href="CHAP007.htm#SSEC007.7">ProfileGlobalFunctions</a>) to turn
profiling on for all globally declared functions simultaneously.
<p>
<a name = "SSEC007.6"></a>
<li><code>UnprofileFunctions( </code><var>funcs</var><code> ) F</code>
<p>
turns profiling off for all function in <var>funcs</var>. Recorded information is
still kept, so you can display it even after turning the profiling off.
<p>
<a name = "SSEC007.7"></a>
<li><code>ProfileGlobalFunctions( true ) F</code>
<li><code>ProfileGlobalFunctions( false ) F</code>
<p>
<code>ProfileGlobalFunctions(true)</code> turns on profiling for all functions that
have been declared via <code>DeclareGlobalFunction</code>. A function call with the
argument <code>false</code> turns it off again.
<p>
<a name = "SSEC007.8"></a>
<li><code>DisplayProfile( ) F</code>
<li><code>DisplayProfile( </code><var>funcs</var><code> ) F</code>
<p>
In the first form, <code>DisplayProfile</code> displays the profiling information
for profiled operations, methods and functions. If an argument
<var>funcs</var> is given, only profiling information for the functions in
<var>funcs</var> is given. The information for a profiled function is only
displayed if the number of calls to the function or the total time spent
in the function exceeds a given threshold (see <a href="CHAP007.htm#SSEC007.9">PROFILETHRESHOLD</a>).
<p>
Profiling information is displayed in a list of lines for all functions
(also operations and methods) which are profiled. For each function,
``count'' gives the number of times the function has been called.
``self'' gives the time spent in the function itself, ``child'' the time
spent in profiled functions called from within this function.
The list is sorted according to the total time spent, that is the sum
``self''+``child''.
<p>
<a name = "SSEC007.9"></a>
<li><code>PROFILETHRESHOLD V</code>
<p>
This variable is a list [<i>cnt</i> ,<i>time</i> ] of length two. <code>DisplayProfile</code>
will only display lines for functions which are called at least <var>cnt</var>
times or whose <strong>total</strong> time (``self''+``child'') is at least <var>time</var>.
The default value of <code>PROFILETHRESHOLD</code> is [10000,30].
<p>
<a name = "SSEC007.10"></a>
<li><code>ClearProfile( ) F</code>
<p>
clears all stored profiling information.
<p>
<pre>
gap> ProfileOperationsAndMethods(true);
gap> ConjugacyClasses(PrimitiveGroup(24,1));;
gap> ProfileOperationsAndMethods(false);
gap> DisplayProfile();
count self/ms chld/ms function
[the following is excerpted from a much longer list]
1620 170 90 CycleStructurePerm: default method
1620 20 260 CycleStructurePerm
114658 280 0 Size: for a list that is a collection
287 20 290 Meth(CyclesOp)
287 0 310 CyclesOp
26 0 330 Size: for a conjugacy class
2219 50 380 Size
2 0 670 IsSubset: for two collections (loop over the ele*
32 0 670 IsSubset
48 10 670 IN: for a permutation, and a permutation group
2 20 730 Meth(ClosureGroup)
2 0 750 ClosureGroup
1 0 780 DerivedSubgroup
1 0 780 Meth(DerivedSubgroup)
4 0 810 Meth(StabChainMutable)
29 0 810 StabChainOp
3 700 110 Meth(StabChainOp)
1 0 820 Meth(IsSimpleGroup)
1 0 820 Meth(IsSimple)
552 10 830 Meth(StabChainImmutable)
26 490 480 CentralizerOp: perm group,elm
26 0 970 Meth(StabilizerOfExternalSet)
107 0 970 CentralizerOp
926 10 970 Meth(CentralizerOp)
819 2100 2340 Meth(IN)
1 10 4890 ConjugacyClasses: by random search
1 0 5720 ConjugacyClasses: perm group
2 0 5740 ConjugacyClasses
6920 TOTAL
gap> DisplayProfile(StabChainOp,DerivedSubgroup); # only two functions
count self/ms chld/ms function
1 0 780 DerivedSubgroup
29 0 810 StabChainOp
6920 OTHER
6920 TOTAL
</pre>
<p>
Note that profiling (even the command <code>ProfileOperationsAndMethods(true)</code>)
can take substantial time and <font face="Gill Sans,Helvetica,Arial">GAP</font> will perform much more slowly
when profiling than when not.
<p>
<a name = "SSEC007.11"></a>
<li><code>DisplayCacheStats( ) F</code>
<p>
displays statistics about the different caches used by the method
selection.
<p>
<a name = "SSEC007.12"></a>
<li><code>ClearCacheStats( ) F</code>
<p>
clears all statistics about the different caches used by the method
selection.
<p>
<p>
<h2><a name="SECT008">7.8 Information about the version used</a></h2>
<p><p>
<a name = "SSEC008.1"></a>
<li><code>DisplayRevision( ) F</code>
<p>
Displays the revision numbers of all loaded files from the library.
<p>
<p>
<h2><a name="SECT009">7.9 Test Files</a></h2>
<p><p>
Test files are used to check that <font face="Gill Sans,Helvetica,Arial">GAP</font> produces correct results in
certain computations. A selection of test files for the library can be
found in the <code>tst</code> directory of the <font face="Gill Sans,Helvetica,Arial">GAP</font> distribution.
<p>
<a name = "SSEC009.1"></a>
<li><code>ReadTest( </code><var>name-file</var><code> ) O</code>
<p>
reads a test file.
A test file starts with a line
<p>
<pre>
gap> START_TEST("arbitrary identifier string");
</pre>
<p>
(Note that the <code>gap></code> prompt is part of the line!)
It continues by lines of <font face="Gill Sans,Helvetica,Arial">GAP</font> input and corresponding output.
The input lines again start with the <code>gap></code> prompt (or the <code>></code> prompt if
commands exceed one line). The output is exactly as would result from typing
in the input interactively to a <font face="Gill Sans,Helvetica,Arial">GAP</font> session
(on a screen with 80 characters per line).
<p>
The test file stops with a line
<p>
<pre>
gap> STOP_TEST( "filename", 10000 );
</pre>
<p>
Here the string <code>"filename"</code> should give the name of the test file. The
number is a proportionality factor that is used to output a ``<font face="Gill Sans,Helvetica,Arial">GAP</font>stone''
speed ranking after the file has been completely processed. For the files
provided with the distribution this scaling is roughly equalized to yield
the same numbers as produced by <code>combinat.tst</code>.
<p>
<p>
<h2><a name="SECT010">7.10 Debugging Recursion</a></h2>
<p><p>
The <font face="Gill Sans,Helvetica,Arial">GAP</font> interpreter monitors the level of nesting of <font face="Gill Sans,Helvetica,Arial">GAP</font>
functions during execution. By default, whenever this nesting reaches
a multiple of 5000, <font face="Gill Sans,Helvetica,Arial">GAP</font> enters a break loop (<a href="CHAP006.htm#SECT004">break loops</a>) allowing
you to terminate the calculation, or enter <code>return;</code> to continue it.
<p>
<pre>
gap> dive:= function(depth) if depth>1 then dive(depth-1); fi; return; end;
function( depth ) ... end
gap> dive(100);
gap> OnBreak:= function() Where(1); end; # shorter traceback
function( ) ... end
gap> dive(6000);
recursion depth trap (5000)
at
dive( depth - 1 );
called from
dive( depth - 1 ); called from
...
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you may 'return;' to continue
brk> return;
gap> dive(11000);
recursion depth trap (5000)
at
dive( depth - 1 );
called from
dive( depth - 1 ); called from
...
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you may 'return;' to continue
brk> return;
recursion depth trap (10000)
at
dive( depth - 1 );
called from
dive( depth - 1 ); called from
...
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you may 'return;' to continue
brk> return;
gap>
</pre>
<p>
This behaviour can be controlled using the procedure
<p>
<a name = "SSEC010.1"></a>
<li><code>SetRecursionTrapInterval( </code><var>interval</var><code> ) F</code>
<p>
<var>interval</var> must be a non-negative small integer (between 0 and
2<sup>28</sup>). An <var>interval</var> of 0 suppresses the monitoring of recursion
altogether. In this case excessive recursion may cause <font face="Gill Sans,Helvetica,Arial">GAP</font> to crash.
<p>
<pre>
gap> dive:= function(depth) if depth>1 then dive(depth-1); fi; return; end;
function( depth ) ... end
gap> SetRecursionTrapInterval(1000);
gap> dive(2500);
recursion depth trap (1000)
at
dive( depth - 1 );
called from
dive( depth - 1 ); called from
...
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you may 'return;' to continue
brk> return;
recursion depth trap (2000)
at
dive( depth - 1 );
called from
dive( depth - 1 ); called from
...
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you may 'return;' to continue
brk> return;
gap> SetRecursionTrapInterval(-1);
SetRecursionTrapInterval( <interval> ): <interval> must be a non-negative smal\
l integer
not in any function
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you can replace <interval> via 'return <interval>;' to continue
brk> return ();
SetRecursionTrapInterval( <interval> ): <interval> must be a non-negative smal\
l integer
not in any function
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you can replace <interval> via 'return <interval>;' to continue
brk> return 0;
gap> dive(20000);
gap> dive(2000000);
Segmentation fault
</pre>
<p>
<p>
<h2><a name="SECT011">7.11 Global Memory Information</a></h2>
<p><p>
The <font face="Gill Sans,Helvetica,Arial">GAP</font> 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 component of the kernel which provides this is called
<code>GASMAN</code> (<font face="Gill Sans,Helvetica,Arial">GAP</font> Storage MANager). Messages reporting garbage
collections performed by GASMAN can be switched on by the <code>-g</code> command
line option (see section <a href="CHAP003.htm#SECT001">command line options</a>). There are also some
facilities to access information from GASMAN from <font face="Gill Sans,Helvetica,Arial">GAP</font> programs.
<p>
<a name = "SSEC011.1"></a>
<li><code>GasmanStatistics( ) F</code>
<p>
<code>GasmanStatistics()</code> returns a record containing some information
from the garbage collection mechanism. The record may contain up to
two components: <code>full</code> and <code>partial</code>
<p>
The <code>full</code> 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 six
components: <code>livebags</code> contains the number of bags which survived
the garbage collection; <code>livekb</code> contains the total number of
kilobytes occupied by those bags; <code>deadbags</code> contains the total
number of bags which were reclaimed by that garbage collection and
all the partial garbage collections preceeding it, since the
previous full garbage collection; <code>deadkb</code> contains the total
number of kilobytes occupied by those bags; <code>freekb</code> reports the
total number of kilobytes available in the GAP workspace for new
objects and <code>totalkb</code> the actual size of the workspace.
<p>
These figures shouold be viewed with some caution. They are
stored internally in fixed length integer formats, and <code>deadkb</code>
and <code>deadbags</code> are liable to overflow if there are many partial
collections before a full collection. Also, note that <code>livekb</code> and
<code>freekb</code> will not usually add up to <code>totalkb</code>. The difference is
essentially the space overhead of the memory management system.
<p>
The <code>partial</code> 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 <code>full</code>. In this case
<code>deadbags</code> and <code>deadkb</code> refer only to the number and total size of
the garbage bags reclaimed in this partial garbage collection and
<code>livebags</code>and <code>livekb</code> only to the numbers and total size of the
young bags that were considered for garbage collection, and
survived.
<p>
<a name = "SSEC011.2"></a>
<li><code>GasmanMessageStatus( ) F</code>
<a name = "SSEC011.2"></a>
<li><code>SetGasmanMessageStatus( </code><var>stat</var><code> ) F</code>
<p>
<code>GasmanMessageStatus()</code> returns one of the string "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.
<p>
<code>SetGasmanMessageStatus( </code><var>stat</var><code> )</code> sets the garbage collector
messaging level. <var>stat</var> should be one of the strings "none",
"full" or "all".
<p>
<a name = "SSEC011.3"></a>
<li><code>GasmanLimits( ) F</code>
<p>
<code>GasmanLimits()</code> returns a record with three components: <code>min</code> is
the minimum workspace size as set by the <code>-m</code> command line option
in kilobytes. The workspace size will never be reduced below this
by the garbage collector. <code>max</code> 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.<code>kill</code> is the absolute maximum, set by the <code>-K</code> command line
option. The workspace will never be allowed to grow past this
limit.
<p>
<p>
[<a href="../index.htm">Top</a>] [<a href = "chapters.htm">Up</a>] [<a href ="CHAP006.htm">Previous</a>] [<a href ="CHAP008.htm">Next</a>] [<a href = "theindex.htm">Index</a>]
<P>
<font face="Gill Sans,Helvetica,Arial">GAP 4 manual<br>December 2008
</font></body></html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
5e1854624d3bc613bdd0dd13d1ef9ac7
>
files
>
149
