<h3>7 <span class="Heading">Debugging and Profiling Facilities</span></h3>
<p>This chapter describes some functions that are useful mainly for debugging and profiling purposes.</p>
<p>Probably the most important debugging tool in <strong class="pkg">GAP</strong> is the break loop (see Section <a href="chap6_mj.html#X8593B49F8705B486"><span class="RefLink">6.4</span></a>) which can be entered by putting an <code class="func">Error</code> (<a href="chap6_mj.html#X7E7AD8D87EBA1A08"><span class="RefLink">6.6-1</span></a>) 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 <strong class="pkg">GAP</strong> session. See also the <code class="func">DownEnv</code> (<a href="chap6_mj.html#X79E66DA2875303B0"><span class="RefLink">6.5-1</span></a>), <code class="func">UpEnv</code> (<a href="chap6_mj.html#X79E66DA2875303B0"><span class="RefLink">6.5-1</span></a>), <code class="func">Where</code> (<a href="chap6_mj.html#X7A7FFA2B7C1EF5A3"><span class="RefLink">6.4-5</span></a>) and <code class="func">WhereWithVars</code> (<a href="chap6_mj.html#X7A7FFA2B7C1EF5A3"><span class="RefLink">6.4-5</span></a>) functions.</p>
<p>Sections <a href="chap7_mj.html#X7FDA1D4B87BD25A8"><span class="RefLink">7.2</span></a> and <a href="chap7_mj.html#X7D43A2D885B37739"><span class="RefLink">7.3</span></a> show how to get information about the methods chosen by the method selection mechanism (see chapter <a href="chap78_mj.html#X8058CC8187162644"><span class="RefLink">78</span></a>).</p>
<p>The final sections describe functions for collecting statistics about computations (see <code class="func">Runtime</code> (<a href="chap7_mj.html#X7E32B27F81870D24"><span class="RefLink">7.6-2</span></a>), <a href="chap7_mj.html#X7FDF923D7D2937A1"><span class="RefLink">7.8</span></a>).</p>
<h4>7.1 <span class="Heading">Recovery from NoMethodFound-Errors</span></h4>
<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>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">IsNormal(2,2);</span>
Error, no method found! For debugging hints type ?Recovery from NoMethodFound
Error, no 1st choice method found for `IsNormal' on 2 arguments at GAPROOT/lib/methsel2.g:250 called from
<function "HANDLE_METHOD_NOT_FOUND">( <arguments> )
called from read-eval loop at *stdin*:1
type 'quit;' to quit to outer loop
<span class="GAPbrkprompt">brk></span>
</pre></div>
<p>This only says, that the method selection tried to find a method for <code class="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 class="keyw">quit</code> command (see <a href="chap6_mj.html#X83033EEB81CF4F49"><span class="RefLink">6.4-1</span></a>) and that the information about the incident is no longer accessible afterwards.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ShowArguments</code>( )</td><td class="tdright">( function )</td></tr></table></div>
<p>This function is only available within a break loop caused by a <q>No Method Found</q>-error. It prints as a list the arguments of the operation call for which no method was found.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ShowArgument</code>( <var class="Arg">nr</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>This function is only available within a break loop caused by a <q>No Method Found</q>-error. It prints the <var class="Arg">nr</var>-th arguments of the operation call for which no method was found. <code class="func">ShowArgument</code> needs exactly one argument which is an integer between 0 and the number of arguments the operation was called with.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ShowDetails</code>( )</td><td class="tdright">( function )</td></tr></table></div>
<p>This function is only available within a break loop caused by a <q>No Method Found</q>-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 class="func">TryNextMethod</code> (<a href="chap78_mj.html#X7EED949B83046A7F"><span class="RefLink">78.5-1</span></a>). The last number is called <code class="code">Choice</code> and is printed as an ordinal. So if exactly <span class="SimpleMath">\(k\)</span> methods were found but called <code class="func">TryNextMethod</code> (<a href="chap78_mj.html#X7EED949B83046A7F"><span class="RefLink">78.5-1</span></a>) and there were no more methods it says <code class="code">Choice: </code><span class="SimpleMath">\(k\)</span><code class="code">th</code>.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ShowMethods</code>( [<var class="Arg">verbosity</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>This function is only available within a break loop caused by a <q>No Method Found</q>-error. It prints an overview about the installed methods for those arguments the operation was called with (using <a href="chap7_mj.html#X7FDA1D4B87BD25A8"><span class="RefLink">7.2</span></a>. The verbosity can be controlled by the optional integer parameter <var class="Arg">verbosity</var>. The default is 2, which lists all applicable methods. With verbosity 1 <code class="func">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 class="func">TryNextMethod</code> (<a href="chap78_mj.html#X7EED949B83046A7F"><span class="RefLink">78.5-1</span></a>). With verbosity 3 not only all installed methods but also the reasons why they do not match are displayed.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ShowOtherMethods</code>( [<var class="Arg">verbosity</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>This function is only available within a break loop caused by a <q>No Method Found</q>-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 <a href="chap7_mj.html#X7FDA1D4B87BD25A8"><span class="RefLink">7.2</span></a>. The verbosity can be controlled by the optional integer parameter <var class="Arg">verbosity</var>. The default is 1 which lists only the number of applicable methods. With verbosity 2 <code class="func">ShowOtherMethods</code> lists all installed methods and with verbosity 3 also the reasons, why they are not applicable. Calling <code class="func">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>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ApplicableMethod</code>( <var class="Arg">opr</var>, <var class="Arg">args</var>[, <var class="Arg">printlevel</var>[, <var class="Arg">nr</var>]] )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ApplicableMethodTypes</code>( <var class="Arg">opr</var>, <var class="Arg">args</var>[, <var class="Arg">printlevel</var>[, <var class="Arg">nr</var>]] )</td><td class="tdright">( function )</td></tr></table></div>
<p>Called with two arguments, <code class="func">ApplicableMethod</code> returns the method of highest rank that is applicable for the operation <var class="Arg">opr</var> with the arguments in the list <var class="Arg">args</var>. The default <var class="Arg">printlevel</var> is <code class="code">0</code>. If no method is applicable then <code class="keyw">fail</code> is returned.</p>
<p>If a positive integer is given as the fourth argument <var class="Arg">nr</var> then <code class="func">ApplicableMethod</code> returns the <var class="Arg">nr</var>-th applicable method for the operation <var class="Arg">opr</var> with the arguments in the list <var class="Arg">args</var>, where the methods are ordered according to descending rank. If less than <var class="Arg">nr</var> methods are applicable then <code class="keyw">fail</code> is returned.</p>
<p>If the fourth argument <var class="Arg">nr</var> is the string <code class="code">"all"</code> then <code class="func">ApplicableMethod</code> returns a list of all applicable methods for <var class="Arg">opr</var> with arguments <var class="Arg">args</var>, ordered according to descending rank.</p>
<p>Depending on the integer value <var class="Arg">printlevel</var>, additional information is printed. Admissible values and their meaning are as follows.</p>
</dd>
<dt><strong class="Mark">1</strong></dt>
<dd><p>information about the applicable method,</p>
</dd>
<dt><strong class="Mark">2</strong></dt>
<dd><p>also information about the not applicable methods of higher rank,</p>
</dd>
<dt><strong class="Mark">3</strong></dt>
<dd><p>also for each not applicable method the first reason why it is not applicable,</p>
</dd>
<dt><strong class="Mark">4</strong></dt>
<dd><p>also for each not applicable method all reasons why it is not applicable.</p>
</dd>
<dt><strong class="Mark">6</strong></dt>
<dd><p>also the function body of the selected method(s)</p>
</dd>
</dl>
<p>When a method returned by <code class="func">ApplicableMethod</code> is called then it returns either the desired result or the string <code class="code">"TRY_NEXT_METHOD"</code>, which corresponds to a call to <code class="func">TryNextMethod</code> (<a href="chap78_mj.html#X7EED949B83046A7F"><span class="RefLink">78.5-1</span></a>) in the method and means that the method selection would call the next applicable method.</p>
<p><em>Note:</em> The <strong class="pkg">GAP</strong> kernel provides special treatment for the infix operations <code class="code">\+</code>, <code class="code">\-</code>, <code class="code">\*</code>, <code class="code">\/</code>, <code class="code">\^</code>, <code class="code">\mod</code> and <code class="code">\in</code>. 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 <code class="func">ApplicableMethod</code> may return a method which is not the kernel method actually used.</p>
<p>The function <code class="func">ApplicableMethodTypes</code> takes the <em>types</em> or <em>filters</em> of the arguments as argument (if only filters are given of course family predicates cannot be tested).</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ TraceMethods</code>( <var class="Arg">opr1</var>, <var class="Arg">opr2</var>, <var class="Arg">...</var> )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ TraceMethods</code>( <var class="Arg">oprs</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>After the call of <code class="code">TraceMethods</code>, whenever a method of one of the operations <var class="Arg">opr1</var>, <var class="Arg">opr2</var>, ... 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 <var class="Arg">oprs</var> of operations.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ UntraceMethods</code>( <var class="Arg">opr1</var>, <var class="Arg">opr2</var>, <var class="Arg">...</var> )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ UntraceMethods</code>( <var class="Arg">oprs</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>turns the tracing off for all operations <var class="Arg">opr1</var>, <var class="Arg">opr2</var>, ... or in the second form, for all operations in the list <var class="Arg">oprs</var>.</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">TraceMethods( [ Size ] );</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">g:= Group( (1,2,3), (1,2) );;</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">Size( g );</span>
#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
<span class="GAPprompt">gap></span> <span class="GAPinput">UntraceMethods( [ Size ] );</span>
</pre></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ UntraceAllMethods</code>( )</td><td class="tdright">( function )</td></tr></table></div>
<p>Equivalent to calling <code class="code">UntraceMethods</code> for all operations.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ TraceImmediateMethods</code>( [<var class="Arg">flag</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ UntraceImmediateMethods</code>( )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">TraceImmediateMethods</code> enables tracing for all immediate methods if <var class="Arg">flag</var> is either <code class="keyw">true</code>, or not present. <code class="func">UntraceImmediateMethods</code>, or <code class="func">TraceImmediateMethods</code> with <var class="Arg">flag</var> equal <code class="keyw">false</code> turns tracing off. (There is no facility to trace <em>specific</em> immediate methods.)</p>
<p>This example gives an explanation for the two calls of the <q>system getter</q> for <code class="func">Size</code> (<a href="chap30_mj.html#X858ADA3B7A684421"><span class="RefLink">30.4-6</span></a>). Namely, there are immediate methods that access the known size of the group. Note that the group <code class="code">g</code> was known to be finitely generated already before the size was computed, the calls of the immediate method for <code class="func">IsFinitelyGeneratedGroup</code> (<a href="chap39_mj.html#X81E22D07871DF37E"><span class="RefLink">39.15-18</span></a>) after the call of <code class="func">Size</code> (<a href="chap30_mj.html#X858ADA3B7A684421"><spanclass="RefLink">30.4-6</span></a>) have other arguments than <code class="code">g</code>.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ TraceInternalMethods</code>( )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ UntraceInternalMethods</code>( )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ GetTraceInternalMethodsCounts</code>( )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ClearTraceInternalMethodsCounts</code>( )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">TraceInternalMethods</code> 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:</p>
</dd>
</dl>
<p><code class="func">UntraceInternalMethods</code> 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.
<p>The <code class="func">Info</code> (<a href="chap7_mj.html#X864E4B6886E2697D"><span class="RefLink">7.4-6</span></a>) mechanism permits operations to display intermediate results or information about the progress of the algorithms. Information is always given according to one or more <em>info classes</em>. Each of the info classes defined in the <strong class="pkg">GAP</strong> library usually covers a certain range of algorithms, so for example <code class="code">InfoLattice</code> covers all the cyclic extension algorithms for the computation of a subgroup lattice.</p>
<p>Note that not all info classes defined in the <strong class="pkg">GAP</strong> library are currently documented. Many <strong class="pkg">GAP</strong> packages define additional info classes, which are typically documented in the corresponding package documentation. The function <code class="func">ShowUsedInfoClasses</code> (<a href="chap7_mj.html#X7BA636EF80A1435A"><spanclass="RefLink">7.4-5</span></a>) will show all info classes which <strong class="pkg">GAP</strong> considers while executing code.</p>
<p>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 <em>level</em> 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:</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ NewInfoClass</code>( <var class="Arg">name</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<p>creates a new info class with name <var class="Arg">name</var>.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ DeclareInfoClass</code>( <var class="Arg">name</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>creates a new info class with name <var class="Arg">name</var> and binds it to the global variable <var class="Arg">name</var>. The variable must previously be writable, and is made read-only by this function.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ShowUsedInfoClasses</code>( <var class="Arg">infoclass</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Called with argument <code class="keyw">true</code>, this makes <strong class="pkg">GAP</strong> print the info class and level of any executed <code class="func">Info</code> (<a href="chap7_mj.html#X864E4B6886E2697D"><span class="RefLink">7.4-6</span></a>) statement. Calling with the argument <code class="keyw">false</code> stops this printing. Each level of each info class is only printed once. The history of printed info classes and levels is reset whenever <code class="keyw">true</code> is passed.</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">ShowUsedInfoClasses(true);</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">Intersection(Group((1,3,2,4,5,6)), Group((1,2,3,4,5,6)));</span>
#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(())
<span class="GAPprompt">gap></span> <span class="GAPinput">Intersection(Group((1,3,2,4,5,6)), Group((1,2,3,4,5,6)));</span>
Group(())
<span class="GAPprompt">gap></span> <span class="GAPinput">ShowUsedInfoClasses(false);</span>
</pre></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ Info</code>( <var class="Arg">infoclass</var>, <var class="Arg">level</var>, <var class="Arg">info</var>[, <var class="Arg">moreinfo</var>, <var class="Arg">...</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>If the info level of <var class="Arg">infoclass</var> is at least <var class="Arg">level</var>, then the remaining arguments, <var class="Arg">info</var>, and possibly <var class="Arg">moreinfo</var> and so on, are evaluated. (Technically, <code class="func">Info</code> is a keyword and not a function.)</p>
<p>By default, the results of these evaluations are viewed, preceded by the string <code class="code">"#I "</code> and followed by a newline.</p>
<p>If the info level of <var class="Arg">infoclass</var> is strictly less than <var class="Arg">level</var>, then the third and subsequent arguments are not evaluated. (The latter can save substantial time when displaying difficult results.)</p>
<p>The behaviour can be customized with <code class="func">SetInfoHandler</code> (<a href="chap7_mj.html#X800234B5815CAC97"><span class="RefLink">7.4-7</span></a>).</p>
<p>Note that the last <code class="func">Info</code> call is executed without problems, since the actual level <code class="code">2</code> of <code class="code">InfoExample</code> causes <code class="func">Info</code> to ignore the last argument, which prevents <code class="code">Length(Combinations([1..9999]))</code> from being evaluated; note that an evaluation would be impossible due to memory restrictions.</p>
<p>A set of info classes (called an <em>info selector</em>) may be passed to a single <code class="func">Info</code> statement. As a shorthand, info classes and selectors may be combined with <code class="code">+</code> rather than <code class="func">Union</code> (<a href="chap30_mj.html#X799F0E2F7A502DBA"><span class="RefLink">30.5-3</span></a>). In this case, the message is triggered if the level of <em>any</em> of the classes is high enough.</p>
<p>This allows one to customize what happens in an <code class="code">Info(<var class="Arg">infoclass</var>, <var class="Arg">level</var>, ...)</code> statement.</p>
<p>In the first function, <var class="Arg">handler</var> must be a function with three arguments <var class="Arg">infoclass</var>, <var class="Arg">level</var>, <var class="Arg">list</var>. Here <var class="Arg">list</var> is the list containing the third argument and any subsequent optional arguments of the <code class="func">Info</code> (<a href="chap7_mj.html#X864E4B6886E2697D"><span class="RefLink">7.4-6</span></a>) call.</p>
<p>The default handler is the function <code class="code">DefaultInfoHandler</code>. It prints <code class="code">"#I "</code>, then the third and further arguments of the info statement, and finally a <code class="code">"\n"</code>.</p>
<p>If the first argument of an <code class="func">Info</code> (<a href="chap7_mj.html#X864E4B6886E2697D"><span class="RefLink">7.4-6</span></a>) statement is a sum of Info classes, the handler of the first summand is used.</p>
<p>The file or stream to which <code class="func">Info</code> (<a href="chap7_mj.html#X864E4B6886E2697D"><span class="RefLink">7.4-6</span></a>) statements for individual <code class="func">Info</code> (<a href="chap7_mj.html#X864E4B6886E2697D"><span class="RefLink">7.4-6</span></a>) classes print can be overridden with <code class="func">SetInfoOutput</code>, retrieved with <codeclass="func">InfoOutput</code> and reset to the default with <code class="func">UnbindInfoOutput</code>. The initial default for all <code class="func">Info</code> (<a href="chap7_mj.html#X864E4B6886E2697D"><span class="RefLink">7.4-6</span></a>) classes is the string <code class="code">"*Print*"</code> which means the current output file. The default can be changed with <code class="func">SetDefaultInfoOutput</code>. The argument <var class="Arg">out</var> can be a filename or an open stream, the special names <code class="code">"*Print*"</code>, <code class="code">"*errout* and "*stdout*</code> are also recognized.</p>
<p>For example, <code class="code">SetDefaultInfoOutput("*errout*");</code> would send <code class="func">Info</code> (<a href="chap7_mj.html#X864E4B6886E2697D"><span class="RefLink">7.4-6</span></a>) output to standard error, which can be interesting if <strong class="pkg">GAP</strong>s output is redirected.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ InfoWarning</code></td><td class="tdright">( info class )</td></tr></table></div>
<p>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 <code class="func">Info</code> (<a href="chap7_mj.html#X864E4B6886E2697D"><span class="RefLink">7.4-6</span></a>) at <code class="func">InfoWarning</code> level 2, e.g. information about the autoloading of <strong class="pkg">GAP</strong> packages and the initial line matched when displaying an on-line help topic.</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>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ SetAssertionLevel</code>( <var class="Arg">lev</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>assigns the global assertion level to <var class="Arg">lev</var>. By default it is zero.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ Assert</code>( <var class="Arg">lev</var>, <var class="Arg">cond</var>[, <var class="Arg">message</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>With two arguments, if the global assertion level is at least <var class="Arg">lev</var>, condition <var class="Arg">cond</var> is tested and if it does not return <code class="keyw">true</code> an error is raised. Thus <code class="code">Assert(lev, <var class="Arg">cond</var>)</code> is equivalent to the code</p>
<div class="example"><pre>
if AssertionLevel() >= lev and not <cond> then
Error("Assertion failure");
fi;
</pre></div>
<p>If the <var class="Arg">message</var> argument form of the <code class="func">Assert</code> statement is provided, and if an error is raised, then this message is printed as part of the error.</p>
<p>Assertions are used at various places in the library. Thus turning assertions on can slow codeexecution significantly.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ Runtimes</code>( )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">Runtimes</code> returns a record with components bound to integers or <code class="keyw">fail</code>. Each integer is the cpu time (processor time) in milliseconds spent by <strong class="pkg">GAP</strong> in a certain status:</p>
<dl>
<dt><strong class="Mark"><code class="code">user_time</code></strong></dt>
<dd><p>cpu time spent with <strong class="pkg">GAP</strong> functions (without child processes).</p>
</dd>
<dt><strong class="Mark"><code class="code">system_time</code></strong></dt>
<dd><p>cpu time spent in system calls, e.g., file access (<code class="keyw">fail</code> if not available).</p>
</dd>
<dt><strong class="Mark"><code class="code">user_time_children</code></strong></dt>
<dd><p>cpu time spent in child processes (<code class="keyw">fail</code> if not available).</p>
</dd>
<dt><strong class="Mark"><code class="code">system_time_children</code></strong></dt>
<dd><p>cpu time spent in system calls by child processes (<code class="keyw">fail</code> if not available).</p>
</dd>
</dl>
<p>Note that this function is not fully supported on all systems. Only the <code class="code">user_time</code> component is (and may on some systems include the system time).</p>
<p>The following example demonstrates tasks which contribute to the different time components:</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">Runtimes(); # after startup</span>
rec( user_time := 3980, system_time := 60, user_time_children := 0,
system_time_children := 0 )
<span class="GAPprompt">gap></span> <span class="GAPinput">Exec("cat /usr/bin/*||wc"); # child process with a lot of file access</span>
893799 7551659 200928302
<span class="GAPprompt">gap></span> <span class="GAPinput">Runtimes();</span>
rec( user_time := 3990, system_time := 60, user_time_children := 1590,
system_time_children := 600 )
<span class="GAPprompt">gap></span> <span class="GAPinput">a:=0;;for i in [1..100000000] do a:=a+1; od; # GAP user time</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">Runtimes();</span>
rec( user_time := 12980, system_time := 70, user_time_children := 1590,
system_time_children := 600 )
<span class="GAPprompt">gap></span> <span class="GAPinput">?blabla # first call of help, a lot of file access</span>
Help: no matching entry found
<span class="GAPprompt">gap></span> <span class="GAPinput">Runtimes();</span>
rec( user_time := 13500, system_time := 440, user_time_children := 1590,
system_time_children := 600 )
</pre></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ Runtime</code>( )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">Runtime</code> returns the time spent by <strong class="pkg">GAP</strong> in milliseconds as an integer. It is the same as the value of the <code class="code">user_time</code> component given by <code class="func">Runtimes</code> (<a href="chap7_mj.html#X80355C9282B35673"><span class="RefLink">7.6-1</span></a>), as explained above.</p>
<p>See <code class="func">StringTime</code> (<a href="chap27_mj.html#X802469C47F886A59"><spanclass="RefLink">27.10-9</span></a>) for a translation from milliseconds into hour/minute format.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ NanosecondsSinceEpoch</code>( )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ NanosecondsSinceEpochInfo</code>( )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">NanosecondsSinceEpoch</code> 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 <strong class="pkg">GAP</strong> is run on. Information about the used timers can be obtained by calling <code class="func">NanosecondsSinceEpochInfo</code>, which returns a record containing members <code class="code">Method</code>, <code class="code">Monotonic</code>, <code class="code">Reliable</code> and <code class="code">Resolution</code>.</p>
<p><code class="code">Method</code> is a string describing the method used to obtain timer values. This will usually contain the name of the syscall used.</p>
<p><code class="code">Monotonic</code> is a boolean. If it is <code class="keyw">true</code>, then the values returned by <code class="func">NanosecondsSinceEpoch</code> are guaranteed to be strictly monotonically increasing between two calls, if it is <code class="keyw">false</code> then there is no such guarantee.</p>
<p><code class="code">Resolution</code> is an integer reflecting the resolution of the timer used in nanoseconds.</p>
<p><code class="code">Reliable</code> is a boolean. If it is <code class="keyw">true</code> then the value <code class="code">Resolution</code> is deemed reliable in the sense that it was obtained by querying the operating system, otherwise <code class="code">Resolution</code> should be treated as an estimate.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ time</code></td><td class="tdright">( global variable )</td></tr></table></div>
<p>In the read-eval-print loop, <code class="func">time</code> stores the number of milliseconds the last command took (see also <code class="func">memory_allocated</code> (<a href="chap7_mj.html#X8156D7208591460F"><span class="RefLink">7.7-2</span></a>) for the number of bytes of memory it allocated).</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ Sleep</code>( <var class="Arg">time</var> )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ MicroSleep</code>( <var class="Arg">time</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>These functions make GAP stop execution for a given period of time. The time to stop is given to <code class="func">Sleep</code> in seconds and <code class="func">MicroSleep</code> in microseconds.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ TotalMemoryAllocated</code>( )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">TotalMemoryAllocated</code> returns the total amount of memory in bytes allocated by the <strong class="pkg">GAP</strong> memory manager since <strong class="pkg">GAP</strong> started.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ memory_allocated</code></td><td class="tdright">( global variable )</td></tr></table></div>
<p>In the read-eval-print loop, <code class="func">memory_allocated</code> stores the number of bytes of memory allocated by the last completed statement (see also <code class="func">time</code> (<a href="chap7_mj.html#X7C0F91F982189624"><span class="RefLink">7.6-4</span></a>) for the number of milliseconds it took).</p>
<p>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.</p>
<p>This section describes how to profiling at the function level. The idea is that</p>
<ul>
<li><p>first one switches on profiling for those <strong class="pkg">GAP</strong> functions the performance of which one wants to check,</p>
</li>
<li><p>then one runs some <strong class="pkg">GAP</strong> computations,</p>
</li>
<li><p>then one looks at the profile information collected during these computations,</p>
</li>
<li><p>then one runs more computations (perhaps clearing all profile information before, see <code class="func">ClearProfile</code> (<a href="chap7_mj.html#X7DAF9AB9793AE203"><span class="RefLink">7.8-10</span></a>)),</p>
</li>
<li><p>and finally one switches off profiling.</p>
</li>
</ul>
--> --------------------
--> maximum size reached
--> --------------------
¤ Dauer der Verarbeitung: 0.26 Sekunden
(vorverarbeitet)
¤
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung ist noch experimentell.
