Welcome To Our Shell

Mister Spy & Souheyl Bypass Shell

  
  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) and Where (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:
  
    Example  
    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 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
    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.4-1).  The last number is called Choice and is printed as an ordinal. So
  if  exactly k methods were found but called TryNextMethod (78.4-1) and there
  were no more methods it says Choice: kth.
  
  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.4-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.4-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.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.
  
    Example  
    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.)
  
    Example  
    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-17)  after  the  call of Size (30.4-6) have
  other arguments than g.
  
  
  7.4 Info Functions
  
  The  Info  (7.4-5)  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  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-7),
  
      InfoPackageLoading (76.2-5),
  
      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 readonly 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 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-6).
  
    Example  
    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.
  
    Example  
    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-6 Customizing Info (7.4-5) 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-5) 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-5) statement is a sum of Info classes,
  the handler of the first summand is used.
  
  The  file  or  stream  to  which Info (7.4-5) statements for individual Info
  (7.4-5)  classes  print  can be overriden with SetInfoOutput, retrieved with
  InfoOutput  and  reset  to  the  default  with UnbindInfoOutput. The initial
  default for all Info (7.4-5) 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-5)
  output  to  standard  error,  which  can  be  interesting  if GAPs output is
  redirected.
  
  7.4-7 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-5)
  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
  
    Example  
    if AssertionLevel() >= lev and not <cond> then
      Error("Assertion failure");
    fi;
  
  
  With  the  message  argument  form  of  the  Assert statement, if the global
  assertion level is at least lev, condition cond is tested and if it does not
  return true then message is evaluated and printed.
  
  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:
  
    Example  
    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
  NanoSleep( 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 NanoSleep in nanoseconds.
  
  
  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.18-14). 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
  (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.
  
    Example  
    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).
  
    Example  
    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).
  
    Example  
    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).
  
    Example  
    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).
  
    Example  
    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.
  
    Example  
    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:
  
    Example  
    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.
  
  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 ActivateProfileColour
  
  ActivateProfileColour(  )  function
  
  Called  with argument true, ActivateProfileColour makes GAP colour functions
  when  printing  them  to show which lines have been executed while profiling
  was  active  via  ProfileLineByLine  (7.8-14)  at  any  time during this GAP
  session. Passing false disables this behaviour.
  
  7.8-19 IsLineByLineProfileActive
  
  IsLineByLineProfileActive(  )  function
  
  IsLineByLineProfileActive  returns  if  line-by-line  profiling is currently
  activated.
  
  7.8-20 DisplayCacheStats
  
  DisplayCacheStats(  )  function
  
  displays statistics about the different caches used by the method selection.
  
  7.8-21 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-17).
  
  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( id )  function
  STOP_TEST( file )  function
  
  START_TEST  and  STOP_TEST may be optionally used in files that are read via
  Test  (7.10-2).  If  used, START_TEST reinitialize the caches and the global
  random  number generator, 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.
  
  To use these options, a test file should be started with a line
  
    Example  
    gap> START_TEST( "arbitrary identifier string" );
  
  
  (Note that the gap>  prompt is part of the line!)
  
  and should be finished with a line
  
    Example  
    gap> STOP_TEST( "filename" );
  
  
  Here the string "filename" should give the name of the test file.
  
  Note  that  the  functions  in  tst/testutil.g temporarily replace STOP_TEST
  before they call Test (7.10-2).
  
  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.
  
    Example  
    gap> Read( Filename( DirectoriesLibrary( "tst" ), "testinstall.g" ) );
  
  
    Example  
    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.
  
    Example  
    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.
  
  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.
  
  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.
  
  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).
  
  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.
  
    Example  
    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 take
  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. 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).
  
  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.
  
    Example  
    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> 
  
  
  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.
  
    Example  
    gap> GetRecursionDepth();
    0
    gap> dive := function(depth)
    >  if depth>1 then
    >    dive(depth-1);
    >  else
    >    Print("Depth ", GetRecursionDepth());
    >  fi;
    > end;;
    gap> SetRecursionTrapInterval(1000);
    gap> dive(100);
    Depth 100
    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> GetRecursionDepth();
    0
    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 0;
    gap> dive(20000);
    Depth 20000
    gap> dive(2000000);
    Segmentation fault
  
  
  
  7.12 Global Memory Information
  
  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
  component  of  the  kernel which provides this is called GASMAN (GAP Storage
  MANager).  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.
  
  7.12-1 GasmanStatistics
  
  GasmanStatistics(  )  function
  
  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 livebagsand 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-2 GasmanMessageStatus
  
  GasmanMessageStatus(  )  function
  SetGasmanMessageStatus( stat )  function
  
  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-3 GasmanLimits
  
  GasmanLimits(  )  function
  
  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.