This file is indexed.

/usr/share/gap/doc/ref/chap7.html is in gap-doc 4r6p5-3.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>GAP (ref) - Chapter 7: Debugging and Profiling Facilities</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<meta name="generator" content="GAPDoc2HTML" />
<link rel="stylesheet" type="text/css" href="manual.css" />
<script src="manual.js" type="text/javascript"></script>
<script type="text/javascript">overwriteStyle();</script>
</head>
<body class="chap7"  onload="jscontent()">


<div class="chlinktop"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a>  <a href="chap1.html">1</a>  <a href="chap2.html">2</a>  <a href="chap3.html">3</a>  <a href="chap4.html">4</a>  <a href="chap5.html">5</a>  <a href="chap6.html">6</a>  <a href="chap7.html">7</a>  <a href="chap8.html">8</a>  <a href="chap9.html">9</a>  <a href="chap10.html">10</a>  <a href="chap11.html">11</a>  <a href="chap12.html">12</a>  <a href="chap13.html">13</a>  <a href="chap14.html">14</a>  <a href="chap15.html">15</a>  <a href="chap16.html">16</a>  <a href="chap17.html">17</a>  <a href="chap18.html">18</a>  <a href="chap19.html">19</a>  <a href="chap20.html">20</a>  <a href="chap21.html">21</a>  <a href="chap22.html">22</a>  <a href="chap23.html">23</a>  <a href="chap24.html">24</a>  <a href="chap25.html">25</a>  <a href="chap26.html">26</a>  <a href="chap27.html">27</a>  <a href="chap28.html">28</a>  <a href="chap29.html">29</a>  <a href="chap30.html">30</a>  <a href="chap31.html">31</a>  <a href="chap32.html">32</a>  <a href="chap33.html">33</a>  <a href="chap34.html">34</a>  <a href="chap35.html">35</a>  <a href="chap36.html">36</a>  <a href="chap37.html">37</a>  <a href="chap38.html">38</a>  <a href="chap39.html">39</a>  <a href="chap40.html">40</a>  <a href="chap41.html">41</a>  <a href="chap42.html">42</a>  <a href="chap43.html">43</a>  <a href="chap44.html">44</a>  <a href="chap45.html">45</a>  <a href="chap46.html">46</a>  <a href="chap47.html">47</a>  <a href="chap48.html">48</a>  <a href="chap49.html">49</a>  <a href="chap50.html">50</a>  <a href="chap51.html">51</a>  <a href="chap52.html">52</a>  <a href="chap53.html">53</a>  <a href="chap54.html">54</a>  <a href="chap55.html">55</a>  <a href="chap56.html">56</a>  <a href="chap57.html">57</a>  <a href="chap58.html">58</a>  <a href="chap59.html">59</a>  <a href="chap60.html">60</a>  <a href="chap61.html">61</a>  <a href="chap62.html">62</a>  <a href="chap63.html">63</a>  <a href="chap64.html">64</a>  <a href="chap65.html">65</a>  <a href="chap66.html">66</a>  <a href="chap67.html">67</a>  <a href="chap68.html">68</a>  <a href="chap69.html">69</a>  <a href="chap70.html">70</a>  <a href="chap71.html">71</a>  <a href="chap72.html">72</a>  <a href="chap73.html">73</a>  <a href="chap74.html">74</a>  <a href="chap75.html">75</a>  <a href="chap76.html">76</a>  <a href="chap77.html">77</a>  <a href="chap78.html">78</a>  <a href="chap79.html">79</a>  <a href="chap80.html">80</a>  <a href="chap81.html">81</a>  <a href="chap82.html">82</a>  <a href="chap83.html">83</a>  <a href="chap84.html">84</a>  <a href="chap85.html">85</a>  <a href="chap86.html">86</a>  <a href="chap87.html">87</a>  <a href="chapBib.html">Bib</a>  <a href="chapInd.html">Ind</a>  </div>

<div class="chlinkprevnexttop">&nbsp;<a href="chap0.html">[Top of Book]</a>&nbsp;  <a href="chap0.html#contents">[Contents]</a>&nbsp;  &nbsp;<a href="chap6.html">[Previous Chapter]</a>&nbsp;  &nbsp;<a href="chap8.html">[Next Chapter]</a>&nbsp;  </div>

<p id="mathjaxlink" class="pcenter"><a href="chap7_mj.html">[MathJax on]</a></p>
<p><a id="X8345F6817DFD6394" name="X8345F6817DFD6394"></a></p>
<div class="ChapSects"><a href="chap7.html#X8345F6817DFD6394">7 <span class="Heading">Debugging and Profiling Facilities</span></a>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap7.html#X83C45B0A797AAF96">7.1 <span class="Heading">Recovery from NoMethodFound-Errors</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X86B5FEC67A9394DC">7.1-1 ShowArguments</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X834BD9928773DCC1">7.1-2 ShowArgument</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X7D25D904800D5CBA">7.1-3 ShowDetails</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X7F6996CA872478B8">7.1-4 ShowMethods</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X7E5E2E7B85029E34">7.1-5 ShowOtherMethods</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap7.html#X7FDA1D4B87BD25A8">7.2 <span class="Heading">Inspecting Applicable Methods</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X80848FF486BD6F9F">7.2-1 ApplicableMethod</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap7.html#X7D43A2D885B37739">7.3 <span class="Heading">Tracing Methods</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X80B044017C9E4137">7.3-1 TraceMethods</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X7EB04D387C53E4C1">7.3-2 UntraceMethods</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X81078D3387A38E31">7.3-3 TraceImmediateMethods</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap7.html#X7A9C902479CB6F7C">7.4 <span class="Heading">Info Functions</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X7AA1A1CF79F20790">7.4-1 NewInfoClass</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X7B3709C584B3DA1E">7.4-2 DeclareInfoClass</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X7A43B9E68765EE9E">7.4-3 SetInfoLevel</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X7B2ADC37783104B9">7.4-4 InfoLevel</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X864E4B6886E2697D">7.4-5 Info</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X7A06511778457311">7.4-6 <span class="Heading">Customizing <code class="func">Info</code> (<a href="chap7.html#X864E4B6886E2697D"><span class="RefLink">7.4-5</span></a>) statements</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X7A28F77C82D6A3E0">7.4-7 InfoWarning</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap7.html#X86425F067FC63A4C">7.5 <span class="Heading">Assertions</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X7C7596418423660B">7.5-1 SetAssertionLevel</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X876C83707F13A0FD">7.5-2 AssertionLevel</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X830E443284780FB9">7.5-3 Assert</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap7.html#X792BA9A67E64CDED">7.6 <span class="Heading">Timing</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X80355C9282B35673">7.6-1 Runtimes</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X7E32B27F81870D24">7.6-2 Runtime</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X7C0F91F982189624">7.6-3 time</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap7.html#X7FDF923D7D2937A1">7.7 <span class="Heading">Profiling</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X79D6CB927BBEB940">7.7-1 ProfileGlobalFunctions</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X7C893F68841B990B">7.7-2 ProfileOperations</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X79D41E977DCA2BEE">7.7-3 ProfileOperationsAndMethods</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X81E8A8627C34FD3B">7.7-4 ProfileFunctions</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X79D394EC7BE8D008">7.7-5 UnprofileFunctions</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X787AC3BE7F991344">7.7-6 ProfileMethods</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X87A05F977F033693">7.7-7 UnprofileMethods</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X80FEA6A08775A48E">7.7-8 DisplayProfile</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X7DAF9AB9793AE203">7.7-9 ClearProfile</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X7940BCF2812C6186">7.7-10 <span class="Heading">An Example of Profiling</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X83D8A42B7BB92F5B">7.7-11 DisplayCacheStats</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X79C58704838232CC">7.7-12 ClearCacheStats</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap7.html#X7EE874867C0BEEDD">7.8 <span class="Heading">Information about the version used</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap7.html#X801051CC86594630">7.9 <span class="Heading">Test Files</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X7DBA18E38405A147">7.9-1 ReadTest</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X8213757B7ACC76E6">7.9-2 <span class="Heading">Starting and stopping test</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X87712F9D8732193C">7.9-3 Test</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap7.html#X85FF55448787CCA0">7.10 <span class="Heading">Debugging Recursion</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X7D8968FC7E24A4E5">7.10-1 SetRecursionTrapInterval</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap7.html#X85679F17791D9B63">7.11 <span class="Heading">Global Memory Information</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X836977DE80416F3D">7.11-1 GasmanStatistics</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X85327FA5872E0356">7.11-2 GasmanMessageStatus</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap7.html#X80C683247E94769F">7.11-3 GasmanLimits</a></span>
</div></div>
</div>

<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.html#X8593B49F8705B486"><span class="RefLink">6.4</span></a>) which can be entered by putting an <code class="func">Error</code> (<a href="chap6.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.html#X79E66DA2875303B0"><span class="RefLink">6.5-1</span></a>), <code class="func">UpEnv</code> (<a href="chap6.html#X79E66DA2875303B0"><span class="RefLink">6.5-1</span></a>) and <code class="func">Where</code> (<a href="chap6.html#X7A7FFA2B7C1EF5A3"><span class="RefLink">6.4-5</span></a>) functions.</p>

<p>Sections <a href="chap7.html#X7FDA1D4B87BD25A8"><span class="RefLink">7.2</span></a> and <a href="chap7.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.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.html#X7E32B27F81870D24"><span class="RefLink">7.6-2</span></a>), <a href="chap7.html#X7FDF923D7D2937A1"><span class="RefLink">7.7</span></a>).</p>

<p><a id="X83C45B0A797AAF96" name="X83C45B0A797AAF96"></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&gt;</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 called from
&lt;function&gt;( &lt;arguments&gt; ) called from read-eval-loop
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput"></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.html#X83033EEB81CF4F49"><span class="RefLink">6.4-1</span></a>) and that the information about the incident is no longer accessible afterwards.</p>

<p><a id="X86B5FEC67A9394DC" name="X86B5FEC67A9394DC"></a></p>

<h5>7.1-1 ShowArguments</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ShowArguments</code>(  )</td><td class="tdright">( function )</td></tr></table></div>
<p>This function is only available within a break loop caused by a "No Method Found"-error. It prints as a list the arguments of the operation call for which no method was found.</p>

<p><a id="X834BD9928773DCC1" name="X834BD9928773DCC1"></a></p>

<h5>7.1-2 ShowArgument</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; 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 "No Method Found"-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>

<p><a id="X7D25D904800D5CBA" name="X7D25D904800D5CBA"></a></p>

<h5>7.1-3 ShowDetails</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ShowDetails</code>(  )</td><td class="tdright">( function )</td></tr></table></div>
<p>This function is only available within a break loop caused by a "No Method Found"-error. It prints the details of this error: The operation, the number of arguments, a flag which indicates whether the operation is being traced, a flag which indicates whether the operation is a constructor method, and the number of methods that refused to apply by calling <code class="func">TryNextMethod</code> (<a href="chap78.html#X7EED949B83046A7F"><span class="RefLink">78.4-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.html#X7EED949B83046A7F"><span class="RefLink">78.4-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>

<p><a id="X7F6996CA872478B8" name="X7F6996CA872478B8"></a></p>

<h5>7.1-4 ShowMethods</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; 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 "No Method Found"-error. It prints an overview about the installed methods for those arguments the operation was called with (using <a href="chap7.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.html#X7EED949B83046A7F"><span class="RefLink">78.4-1</span></a>). With verbosity 3 not only all installed methods but also the reasons why they do not match are displayed.</p>

<p><a id="X7E5E2E7B85029E34" name="X7E5E2E7B85029E34"></a></p>

<h5>7.1-5 ShowOtherMethods</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; 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 "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 <a href="chap7.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>

<p><a id="X7FDA1D4B87BD25A8" name="X7FDA1D4B87BD25A8"></a></p>

<h4>7.2 <span class="Heading">Inspecting Applicable Methods</span></h4>

<p><a id="X80848FF486BD6F9F" name="X80848FF486BD6F9F"></a></p>

<h5>7.2-1 ApplicableMethod</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; 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">&#8227; 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>


<dl>
<dt><strong class="Mark">0</strong></dt>
<dd><p>no information,</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.html#X7EED949B83046A7F"><span class="RefLink">78.4-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>

<p><a id="X7D43A2D885B37739" name="X7D43A2D885B37739"></a></p>

<h4>7.3 <span class="Heading">Tracing Methods</span></h4>

<p><a id="X80B044017C9E4137" name="X80B044017C9E4137"></a></p>

<h5>7.3-1 TraceMethods</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; 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">&#8227; 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>

<p><a id="X7EB04D387C53E4C1" name="X7EB04D387C53E4C1"></a></p>

<h5>7.3-2 UntraceMethods</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; 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">&#8227; 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&gt;</span> <span class="GAPinput">TraceMethods( [ Size ] );</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">g:= Group( (1,2,3), (1,2) );;</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Size( g );</span>
#I  Size: for a permutation group
#I  Setter(Size): system setter
#I  Size: system getter
#I  Size: system getter
6
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">UntraceMethods( [ Size ] );</span>
</pre></div>

<p><a id="X81078D3387A38E31" name="X81078D3387A38E31"></a></p>

<h5>7.3-3 TraceImmediateMethods</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; TraceImmediateMethods</code>( <var class="Arg">flag</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>If <var class="Arg">flag</var> is true, tracing for all immediate methods is turned on. If <var class="Arg">flag</var> is false it is turned off. (There is no facility to trace <em>specific</em> immediate methods.)</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">TraceImmediateMethods( true );</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">g:= Group( (1,2,3), (1,2) );;</span>
#I  immediate: Size
#I  immediate: IsCyclic
#I  immediate: IsCommutative
#I  immediate: IsTrivial
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Size( g );</span>
#I  immediate: IsNonTrivial
#I  immediate: Size
#I  immediate: IsFreeAbelian
#I  immediate: IsTorsionFree
#I  immediate: IsNonTrivial
#I  immediate: GeneralizedPcgs
#I  immediate: IsPerfectGroup
#I  immediate: IsEmpty
6
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">TraceImmediateMethods( false );</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">UntraceMethods( [ Size ] );</span>
</pre></div>

<p>This example gives an explanation for the two calls of the "system getter" for <code class="func">Size</code> (<a href="chap30.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.html#X81E22D07871DF37E"><span class="RefLink">39.15-17</span></a>) after the call of <code class="func">Size</code> (<a href="chap30.html#X858ADA3B7A684421"><span class="RefLink">30.4-6</span></a>) have other arguments than <code class="code">g</code>.</p>

<p><a id="X7A9C902479CB6F7C" name="X7A9C902479CB6F7C"></a></p>

<h4>7.4 <span class="Heading">Info Functions</span></h4>

<p>The <code class="func">Info</code> (<a href="chap7.html#X864E4B6886E2697D"><span class="RefLink">7.4-5</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>The amount of information to be displayed can be specified by the user for each info class separately by a <em>level</em>, the higher the level the more information will be displayed. Ab initio all info classes have level zero except <code class="func">InfoWarning</code> (<a href="chap7.html#X7A28F77C82D6A3E0"><span class="RefLink">7.4-7</span></a>) which initially has level 1.</p>

<p><a id="X7AA1A1CF79F20790" name="X7AA1A1CF79F20790"></a></p>

<h5>7.4-1 NewInfoClass</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; 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>

<p><a id="X7B3709C584B3DA1E" name="X7B3709C584B3DA1E"></a></p>

<h5>7.4-2 DeclareInfoClass</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; 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 readonly by this function.</p>

<p><a id="X7A43B9E68765EE9E" name="X7A43B9E68765EE9E"></a></p>

<h5>7.4-3 SetInfoLevel</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; SetInfoLevel</code>( <var class="Arg">infoclass</var>, <var class="Arg">level</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<p>Sets the info level for <var class="Arg">infoclass</var> to <var class="Arg">level</var>.</p>

<p><a id="X7B2ADC37783104B9" name="X7B2ADC37783104B9"></a></p>

<h5>7.4-4 InfoLevel</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; InfoLevel</code>( <var class="Arg">infoclass</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<p>returns the info level of <var class="Arg">infoclass</var>.</p>

<p><a id="X864E4B6886E2697D" name="X864E4B6886E2697D"></a></p>

<h5>7.4-5 Info</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; 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> 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, they are viewed, preceded by the string <code class="code">"#I "</code> and followed by a newline. Otherwise the third and subsequent arguments are not evaluated. (The latter can save substantial time when displaying difficult results.)</p>

<p>The behaviour can be customized with <code class="func">SetInfoHandler</code> (<a href="chap7.html#X7A06511778457311"><span class="RefLink">7.4-6</span></a>).</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">InfoExample:=NewInfoClass("InfoExample");;</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Info(InfoExample,1,"one");Info(InfoExample,2,"two");</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">SetInfoLevel(InfoExample,1);</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Info(InfoExample,1,"one");Info(InfoExample,2,"two");</span>
#I  one
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">SetInfoLevel(InfoExample,2);</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Info(InfoExample,1,"one");Info(InfoExample,2,"two");</span>
#I  one
#I  two
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">InfoLevel(InfoExample);</span>
2
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Info(InfoExample,3,Length(Combinations([1..9999])));</span>
</pre></div>

<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.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>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">InfoExample:=NewInfoClass("InfoExample");;</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">SetInfoLevel(InfoExample,0);</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Info(InfoExample + InfoWarning, 1, "hello");</span>
#I  hello
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Info(InfoExample + InfoWarning, 2, "hello");</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">SetInfoLevel(InfoExample,2);</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Info(InfoExample + InfoWarning, 2, "hello");</span>
#I  hello
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">InfoLevel(InfoWarning);</span>
1
</pre></div>

<p><a id="X7A06511778457311" name="X7A06511778457311"></a></p>

<h5>7.4-6 <span class="Heading">Customizing <code class="func">Info</code> (<a href="chap7.html#X864E4B6886E2697D"><span class="RefLink">7.4-5</span></a>) statements</span></h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; SetInfoHandler</code>( <var class="Arg">infoclass</var>, <var class="Arg">handler</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">&#8227; SetInfoOutput</code>( <var class="Arg">infoclass</var>, <var class="Arg">out</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">&#8227; SetDefaultInfoOutput</code>( <var class="Arg">out</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Returns: nothing</p>

<p>This allows 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 to last argument of the <code class="func">Info</code> (<a href="chap7.html#X864E4B6886E2697D"><span class="RefLink">7.4-5</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.html#X864E4B6886E2697D"><span class="RefLink">7.4-5</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.html#X864E4B6886E2697D"><span class="RefLink">7.4-5</span></a>) statements for individual <code class="func">Info</code> (<a href="chap7.html#X864E4B6886E2697D"><span class="RefLink">7.4-5</span></a>) classes print can be changed with <code class="func">SetInfoOutput</code>. The initial default for all <code class="func">Info</code> (<a href="chap7.html#X864E4B6886E2697D"><span class="RefLink">7.4-5</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*</code> and <code class="code">"*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.html#X864E4B6886E2697D"><span class="RefLink">7.4-5</span></a>) output to standard error, which can be interesting if <strong class="pkg">GAP</strong>s output is redirected.</p>

<p><a id="X7A28F77C82D6A3E0" name="X7A28F77C82D6A3E0"></a></p>

<h5>7.4-7 InfoWarning</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; InfoWarning</code></td><td class="tdright">( global variable )</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.html#X864E4B6886E2697D"><span class="RefLink">7.4-5</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><a id="X86425F067FC63A4C" name="X86425F067FC63A4C"></a></p>

<h4>7.5 <span class="Heading">Assertions</span></h4>

<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>

<p><a id="X7C7596418423660B" name="X7C7596418423660B"></a></p>

<h5>7.5-1 SetAssertionLevel</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; 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>

<p><a id="X876C83707F13A0FD" name="X876C83707F13A0FD"></a></p>

<h5>7.5-2 AssertionLevel</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; AssertionLevel</code>(  )</td><td class="tdright">( function )</td></tr></table></div>
<p>returns the current assertion level.</p>

<p><a id="X830E443284780FB9" name="X830E443284780FB9"></a></p>

<h5>7.5-3 Assert</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; 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() &gt;= lev and not &lt;cond&gt; then
  Error("Assertion failure");
fi;
</pre></div>

<p>With the <var class="Arg">message</var> argument form of the <code class="func">Assert</code> statement, 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> then <var class="Arg">message</var> is evaluated and printed.</p>

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

<p><a id="X792BA9A67E64CDED" name="X792BA9A67E64CDED"></a></p>

<h4>7.6 <span class="Heading">Timing</span></h4>

<p><a id="X80355C9282B35673" name="X80355C9282B35673"></a></p>

<h5>7.6-1 Runtimes</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; 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&gt;</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&gt;</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&gt;</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&gt;</span> <span class="GAPinput">a:=0;;for i in [1..100000000] do a:=a+1; od; # GAP user time</span>
<span class="GAPprompt">gap&gt;</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&gt;</span> <span class="GAPinput">?blabla  # first call of help, a lot of file access</span>
Help: no matching entry found
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Runtimes();</span>
rec( user_time := 13500, system_time := 440, user_time_children := 1590, 
  system_time_children := 600 )
</pre></div>

<p><a id="X7E32B27F81870D24" name="X7E32B27F81870D24"></a></p>

<h5>7.6-2 Runtime</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; 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.html#X80355C9282B35673"><span class="RefLink">7.6-1</span></a>), as explained above.</p>

<p>See <code class="func">StringTime</code> (<a href="chap27.html#X802469C47F886A59"><span class="RefLink">27.9-9</span></a>) for a translation from milliseconds into hour/minute format.</p>

<p><a id="X7C0F91F982189624" name="X7C0F91F982189624"></a></p>

<h5>7.6-3 time</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; 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 time the last command took.</p>

<p><a id="X7FDF923D7D2937A1" name="X7FDF923D7D2937A1"></a></p>

<h4>7.7 <span class="Heading">Profiling</span></h4>

<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. 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.html#X7DAF9AB9793AE203"><span class="RefLink">7.7-9</span></a>)),</p>

</li>
<li><p>and finally one switches off profiling.</p>

</li>
</ul>
<p>For switching on and off profiling, <strong class="pkg">GAP</strong> supports entering a list of functions (see <code class="func">ProfileFunctions</code> (<a href="chap7.html#X81E8A8627C34FD3B"><span class="RefLink">7.7-4</span></a>), <code class="func">UnprofileFunctions</code> (<a href="chap7.html#X79D394EC7BE8D008"><span class="RefLink">7.7-5</span></a>)) or a list of operations whose methods shall be (un)profiled (<code class="func">ProfileMethods</code> (<a href="chap7.html#X787AC3BE7F991344"><span class="RefLink">7.7-6</span></a>), <code class="func">UnprofileMethods</code> (<a href="chap7.html#X87A05F977F033693"><span class="RefLink">7.7-7</span></a>)), and <code class="func">DisplayProfile</code> (<a href="chap7.html#X80FEA6A08775A48E"><span class="RefLink">7.7-8</span></a>) can be used to show profile information about functions in a given list.</p>

<p>Besides these functions, <code class="func">ProfileGlobalFunctions</code> (<a href="chap7.html#X79D6CB927BBEB940"><span class="RefLink">7.7-1</span></a>), <code class="func">ProfileOperations</code> (<a href="chap7.html#X7C893F68841B990B"><span class="RefLink">7.7-2</span></a>), and <code class="func">ProfileOperationsAndMethods</code> (<a href="chap7.html#X79D41E977DCA2BEE"><span class="RefLink">7.7-3</span></a>) can be used for switching on or off profiling for <em>all</em> global functions, operations, and operations together with all their methods, respectively, and for showing profile information about these functions.</p>

<p>Note that <strong class="pkg">GAP</strong> will perform more slowly when profiling than when not.</p>

<p><a id="X79D6CB927BBEB940" name="X79D6CB927BBEB940"></a></p>

<h5>7.7-1 ProfileGlobalFunctions</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ProfileGlobalFunctions</code>( [<var class="Arg">bool</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>Called with argument <code class="keyw">true</code>, <code class="func">ProfileGlobalFunctions</code> starts profiling of all functions that have been declared via <code class="func">DeclareGlobalFunction</code> (<a href="chap79.html#X834A8CC587A609BE"><span class="RefLink">79.17-7</span></a>). Old profile information for all these functions is cleared. A function call with the argument <code class="keyw">false</code> stops profiling of all these functions. Recorded information is still kept, so you can display it even after turning the profiling off.</p>

<p>When <code class="func">ProfileGlobalFunctions</code> is called without argument, profile information for all global functions is displayed, see <code class="func">DisplayProfile</code> (<a href="chap7.html#X80FEA6A08775A48E"><span class="RefLink">7.7-8</span></a>).</p>

<p><a id="X7C893F68841B990B" name="X7C893F68841B990B"></a></p>

<h5>7.7-2 ProfileOperations</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ProfileOperations</code>( [<var class="Arg">bool</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>Called with argument <code class="keyw">true</code>, <code class="func">ProfileOperations</code> starts profiling of all operations. Old profile information for all operations is cleared. A function call with the argument <code class="keyw">false</code> stops profiling of all operations. Recorded information is still kept, so you can display it even after turning the profiling off.</p>

<p>When <code class="func">ProfileOperations</code> is called without argument, profile information for all operations is displayed (see <code class="func">DisplayProfile</code> (<a href="chap7.html#X80FEA6A08775A48E"><span class="RefLink">7.7-8</span></a>)).</p>

<p><a id="X79D41E977DCA2BEE" name="X79D41E977DCA2BEE"></a></p>

<h5>7.7-3 ProfileOperationsAndMethods</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ProfileOperationsAndMethods</code>( [<var class="Arg">bool</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>Called with argument <code class="keyw">true</code>, <code class="func">ProfileOperationsAndMethods</code> starts profiling of all operations and their methods. Old profile information for these functions is cleared. A function call with the argument <code class="keyw">false</code> stops profiling of all operations and their methods. Recorded information is still kept, so you can display it even after turning the profiling off.</p>

<p>When <code class="func">ProfileOperationsAndMethods</code> is called without argument, profile information for all operations and their methods is displayed, see <code class="func">DisplayProfile</code> (<a href="chap7.html#X80FEA6A08775A48E"><span class="RefLink">7.7-8</span></a>).</p>

<p><a id="X81E8A8627C34FD3B" name="X81E8A8627C34FD3B"></a></p>

<h5>7.7-4 ProfileFunctions</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ProfileFunctions</code>( <var class="Arg">funcs</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>starts profiling for all function in the list <var class="Arg">funcs</var>. You can use <code class="func">ProfileGlobalFunctions</code> (<a href="chap7.html#X79D6CB927BBEB940"><span class="RefLink">7.7-1</span></a>) to turn profiling on for all globally declared functions simultaneously.</p>

<p><a id="X79D394EC7BE8D008" name="X79D394EC7BE8D008"></a></p>

<h5>7.7-5 UnprofileFunctions</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; UnprofileFunctions</code>( <var class="Arg">funcs</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>stops profiling for all function in the list <var class="Arg">funcs</var>. Recorded information is still kept, so you can display it even after turning the profiling off.</p>

<p><a id="X787AC3BE7F991344" name="X787AC3BE7F991344"></a></p>

<h5>7.7-6 ProfileMethods</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ProfileMethods</code>( <var class="Arg">ops</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>starts profiling of the methods for all operations in the list <var class="Arg">ops</var>.</p>

<p><a id="X87A05F977F033693" name="X87A05F977F033693"></a></p>

<h5>7.7-7 UnprofileMethods</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; UnprofileMethods</code>( <var class="Arg">ops</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>stops profiling of the methods for all operations in the list <var class="Arg">ops</var>. Recorded information is still kept, so you can display it even after turning the profiling off.</p>

<p><a id="X80FEA6A08775A48E" name="X80FEA6A08775A48E"></a></p>

<h5>7.7-8 DisplayProfile</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; DisplayProfile</code>( [<var class="Arg">functions</var>, ][<var class="Arg">mincount</var>, <var class="Arg">mintime</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">&#8227; GAPInfo.ProfileThreshold</code></td><td class="tdright">( global variable )</td></tr></table></div>
<p>Called without arguments, <code class="func">DisplayProfile</code> displays the profile information for profiled operations, methods and functions. If an argument <var class="Arg">functions</var> is given, only profile information for the functions in the list <var class="Arg">functions</var> is shown. If two integer values <var class="Arg">mincount</var>, <var class="Arg">mintime</var> are given as arguments then the output is restricted to those functions that were called at least <var class="Arg">mincount</var> times or for which the total time spent (see below) was at least <var class="Arg">mintime</var> milliseconds. The defaults for <var class="Arg">mincount</var> and <var class="Arg">mintime</var> are the entries of the list stored in the global variable <code class="func">GAPInfo.ProfileThreshold</code>.</p>

<p>The default value of <code class="func">GAPInfo.ProfileThreshold</code> is <code class="code">[ 10000, 30 ]</code>.</p>

<p>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 <strong class="pkg">GAP</strong> package to which the function belongs; the entry "GAP" in this column means that the function belongs to the <strong class="pkg">GAP</strong> library, the entry "(oprt.)" means that the function is an operation (which may belong to several packages), and an empty entry means that <code class="func">FilenameFunc</code> (<a href="chap5.html#X80E108C57F90FAA3"><span class="RefLink">5.1-4</span></a>) cannot determine in which file the function is defined.</p>

<p>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".</p>

<p>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 <code class="code">OTHER</code>) and by all profiled functions (label <code class="code">TOTAL</code>), respectively.</p>

<p>An interactive variant of <code class="func">DisplayProfile</code> is the function <code class="func">BrowseProfile</code> (<span class="RefLink">???</span>) that is provided by the <strong class="pkg">GAP</strong> package <strong class="pkg">Browse</strong>.</p>

<p><a id="X7DAF9AB9793AE203" name="X7DAF9AB9793AE203"></a></p>

<h5>7.7-9 ClearProfile</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ClearProfile</code>(  )</td><td class="tdright">( function )</td></tr></table></div>
<p>clears all stored profile information.</p>

<p><a id="X7940BCF2812C6186" name="X7940BCF2812C6186"></a></p>

<h5>7.7-10 <span class="Heading">An Example of Profiling</span></h5>

<p>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.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">g:= PrimitiveGroup( 24, 1 );;</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">ProfileGlobalFunctions( true );</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">ProfileOperationsAndMethods( true );</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">ConjugacyClasses( g );;</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">ProfileGlobalFunctions( false );</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">ProfileOperationsAndMethods( false );</span>
</pre></div>

<p>Now the profile information is available. We can list the information for all profiled functions with <code class="func">DisplayProfile</code> (<a href="chap7.html#X80FEA6A08775A48E"><span class="RefLink">7.7-8</span></a>).</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">DisplayProfile();</span>
  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                 
</pre></div>

<p>We can restrict the list to global functions with <code class="func">ProfileGlobalFunctions</code> (<a href="chap7.html#X79D6CB927BBEB940"><span class="RefLink">7.7-1</span></a>).</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">ProfileGlobalFunctions();</span>
  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                 
</pre></div>

<p>We can restrict the list to operations with <code class="func">ProfileOperations</code> (<a href="chap7.html#X7C893F68841B990B"><span class="RefLink">7.7-2</span></a>).</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">ProfileOperations();</span>
  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                 
</pre></div>

<p>We can restrict the list to operations and their methods with <code class="func">ProfileOperationsAndMethods</code> (<a href="chap7.html#X79D41E977DCA2BEE"><span class="RefLink">7.7-3</span></a>).</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">ProfileOperationsAndMethods();</span>
  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                 
</pre></div>

<p>Finally, we can restrict the list to explicitly given functions with <code class="func">DisplayProfile</code> (<a href="chap7.html#X80FEA6A08775A48E"><span class="RefLink">7.7-8</span></a>), by entering the list of functions as an argument.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">DisplayProfile( [ StabChainOp, Centralizer ] );</span>
  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                 
</pre></div>

<p><a id="X83D8A42B7BB92F5B" name="X83D8A42B7BB92F5B"></a></p>

<h5>7.7-11 DisplayCacheStats</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; DisplayCacheStats</code>(  )</td><td class="tdright">( function )</td></tr></table></div>
<p>displays statistics about the different caches used by the method selection.</p>

<p><a id="X79C58704838232CC" name="X79C58704838232CC"></a></p>

<h5>7.7-12 ClearCacheStats</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ClearCacheStats</code>(  )</td><td class="tdright">( function )</td></tr></table></div>
<p>clears all statistics about the different caches used by the method selection.</p>

<p><a id="X7EE874867C0BEEDD" name="X7EE874867C0BEEDD"></a></p>

<h4>7.8 <span class="Heading">Information about the version used</span></h4>

<p>The global variable <code class="code">GAPInfo.Version</code> (see <code class="func">GAPInfo</code> (<a href="chap3.html#X8354754E7935F935"><span class="RefLink">3.5-1</span></a>)) contains the version number of the version of <strong class="pkg">GAP</strong>. Its value can be checked other version number using <code class="func">CompareVersionNumbers</code> (<a href="chap76.html#X787DFEB383545A49"><span class="RefLink">76.3-6</span></a>).</p>

<p><a id="X801051CC86594630" name="X801051CC86594630"></a></p>

<h4>7.9 <span class="Heading">Test Files</span></h4>

<p>Test files are used to check that <strong class="pkg">GAP</strong> produces correct results in certain computations. A selection of test files for the library can be found in the <code class="file">tst</code> directory of the <strong class="pkg">GAP</strong> distribution.</p>

<p><a id="X7DBA18E38405A147" name="X7DBA18E38405A147"></a></p>

<h5>7.9-1 ReadTest</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ReadTest</code>( <var class="Arg">string</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<p>reads the test file with name <var class="Arg">string</var>. The test file should contain lines of <strong class="pkg">GAP</strong> input and corresponding output. The input lines start with the <code class="code">gap&gt; </code> prompt (or with the <code class="code">&gt; </code> prompt if commands exceed one line). The output is exactly as would result from typing in the input interactively to a <strong class="pkg">GAP</strong> session (on a screen with 80 characters per line).</p>

<p>Optionally, <code class="func">START_TEST</code> (<a href="chap7.html#X8213757B7ACC76E6"><span class="RefLink">7.9-2</span></a>) and <code class="func">STOP_TEST</code> (<a href="chap7.html#X8213757B7ACC76E6"><span class="RefLink">7.9-2</span></a>) may be used in the beginning and end of test files to reinitialize the caches and the global random number generator in order to be independent of the reading order of several test files. Furthermore, <code class="func">START_TEST</code> (<a href="chap7.html#X8213757B7ACC76E6"><span class="RefLink">7.9-2</span></a>) increases the assertion level for the time of the test, and <code class="func">STOP_TEST</code> (<a href="chap7.html#X8213757B7ACC76E6"><span class="RefLink">7.9-2</span></a>) sets the proportionality factor that is used to output a "<strong class="pkg">GAP</strong>stone" speed ranking after the file has been completely processed.</p>

<p><a id="X8213757B7ACC76E6" name="X8213757B7ACC76E6"></a></p>

<h5>7.9-2 <span class="Heading">Starting and stopping test</span></h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; START_TEST</code>( <var class="Arg">id</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">&#8227; STOP_TEST</code>( <var class="Arg">file</var>, <var class="Arg">fac</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">START_TEST</code> and <code class="func">STOP_TEST</code> may be optionally used in files that are read via <code class="func">ReadTest</code> (<a href="chap7.html#X7DBA18E38405A147"><span class="RefLink">7.9-1</span></a>). If used, <code class="func">START_TEST</code> 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 <code class="func">Assert</code> (<a href="chap7.html#X830E443284780FB9"><span class="RefLink">7.5-3</span></a>)) is set to <span class="SimpleMath">2</span> by <code class="func">START_TEST</code> and set back to the previous value in the subsequent <code class="func">STOP_TEST</code> call.</p>

<p>To use these options, a test file should be started with a line</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">START_TEST( "arbitrary identifier string" );</span>
</pre></div>

<p>(Note that the <code class="code">gap&gt; </code> prompt is part of the line!)</p>

<p>and should be finished with a line</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">STOP_TEST( "filename", 10000 );</span>
</pre></div>

<p>Here the string <code class="code">"filename"</code> should give the name of the test file. The number is a proportionality factor that is used to output a "<strong class="pkg">GAP</strong>stone" speed ranking after the file has been completely processed. For the files provided with the distribution this scaling is roughly equalized to yield the same numbers as produced by the test file <code class="file">tst/combinat.tst</code>.</p>

<p>Note that the functions in <code class="file">tst/testutil.g</code> temporarily replace <code class="func">STOP_TEST</code> before they call <code class="func">ReadTest</code> (<a href="chap7.html#X7DBA18E38405A147"><span class="RefLink">7.9-1</span></a>).</p>

<p>If you want to run a quick test of your <strong class="pkg">GAP</strong> installation (though this is not required), you can read in a test script that exercises some <strong class="pkg">GAP</strong>'s capabilities.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Read( Filename( DirectoriesLibrary( "tst" ), "testinstall.g" ) );</span>
</pre></div>

<p>The test requires about 512MB of memory and runs about one minute on an Intel Core 2 Duo / 2.53 GHz machine. You will get a large number of lines with output about the progress of the tests.</p>


<div class="example"><pre>
test file         GAP4stones     time(msec)
-------------------------------------------
testing: ................/gap4r5/tst/zlattice.tst
zlattice.tst               0              0
testing: ................/gap4r5/tst/gaussian.tst
gaussian.tst               0             10
[ further lines deleted ]
</pre></div>

<p>If you want to run a more advanced check (this is not required and make take up to an hour), you can read <code class="file">testall.g</code> which is an extended test script performing all tests from the <code class="file">tst</code> directory.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Read( Filename( DirectoriesLibrary( "tst" ), "testall.g" ) );</span>
</pre></div>

<p>The test requires about 512MB of memory and runs about one hour on an Intel Core 2 Duo / 2.53 GHz machine, and produces an output similar to the <code class="file">testinstall.g</code> test.</p>

<p><a id="X87712F9D8732193C" name="X87712F9D8732193C"></a></p>

<h5>7.9-3 Test</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; Test</code>( <var class="Arg">fname</var>[, <var class="Arg">optrec</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>Returns: <code class="keyw">true</code> or <code class="keyw">false</code>.</p>

<p>The argument <var class="Arg">fname</var> must be the name of a file or an open input stream. The content of this file or stream should contain <strong class="pkg">GAP</strong> input and output. The function <code class="func">Test</code> runs the input lines, compares the actual output with the output stored in <var class="Arg">fname</var> and reports differences. With an optional record as argument <var class="Arg">optrec</var> details of this process can be adjusted.</p>

<p>More precisely, the content of <var class="Arg">fname</var> must have the following format. <br /> Lines starting with <code class="code">"gap&gt; "</code> are considered as <strong class="pkg">GAP</strong> input, they can be followed by lines starting with <code class="code">"&gt; "</code> if the input is continued over several lines. <br /> To allow for comments in <var class="Arg">fname</var> the following lines are ignored by default: lines at the beginning of <var class="Arg">fname</var> that start with <code class="code">"#"</code>, and one empty line together with one or more lines starting with <code class="code">"#"</code>.<br /> All other lines are considered as <strong class="pkg">GAP</strong> output from the preceding <strong class="pkg">GAP</strong> input.</p>

<p>By default the actual <strong class="pkg">GAP</strong> output is compared exactly with the stored output, and if these are different some information about the differences is printed.</p>

<p>If any differences are found then <code class="func">Test</code> returns <code class="keyw">false</code>, otherwise <code class="keyw">true</code>.</p>

<p>If the optional argument <var class="Arg">optrec</var> is given it must be a record. The following components of <var class="Arg">optrec</var> are recognized and can change the default behaviour of <code class="func">Test</code>:</p>


<dl>
<dt><strong class="Mark"><code class="code">ignoreComments</code></strong></dt>
<dd><p>If set to <code class="keyw">false</code> then no lines in <var class="Arg">fname</var> are ignored as explained above (default is <code class="keyw">true</code>).</p>

</dd>
<dt><strong class="Mark"><code class="code">width</code></strong></dt>
<dd><p>The screen width used for the new output (default is <code class="code">80</code>).</p>

</dd>
<dt><strong class="Mark"><code class="code">compareFunction</code></strong></dt>
<dd><p>This must be a function that gets two strings as input, the newly generated and the stored output of some <strong class="pkg">GAP</strong> input. The function must return <code class="keyw">true</code> or <code class="keyw">false</code>, indicating if the strings should be considered equivalent or not. By default <code class="func">\=</code> (<a href="chap31.html#X7EF67D047F03CA6F"><span class="RefLink">31.11-1</span></a>) is used. <br /> Two strings are recognized as abbreviations in this component: <code class="code">"uptowhitespace"</code> checks if the two strings become equal after removing all white space. And <code class="code">"uptonl"</code> compares the string up to trailing newline characters.</p>

</dd>
<dt><strong class="Mark"><code class="code">reportDiff</code></strong></dt>
<dd><p>A function that gets six arguments and reports a difference in the output: the <strong class="pkg">GAP</strong> input, the expected <strong class="pkg">GAP</strong> 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.)</p>

</dd>
<dt><strong class="Mark"><code class="code">rewriteToFile</code></strong></dt>
<dd><p>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 <var class="Arg">fname</var> but the output substituted by the newly generated version (default is <code class="keyw">false</code>).</p>

</dd>
<dt><strong class="Mark"><code class="code">writeTimings</code></strong></dt>
<dd><p>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 <var class="Arg">fname</var>.</p>

</dd>
<dt><strong class="Mark"><code class="code">compareTimings</code></strong></dt>
<dd><p>If this is bound to a string it is considered as name of a file to which timing information was stored via <code class="code">writeTimings</code> 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 <code class="code">[timingfile, threshold, percentage]</code> to this component. (The default of <code class="code">compareTimings</code> is <code class="keyw">false</code>.)</p>

</dd>
<dt><strong class="Mark"><code class="code">reportTimeDiff</code></strong></dt>
<dd><p>This component can be used to overwrite the default function to display timing differences. It must be a function with 5 arguments: <strong class="pkg">GAP</strong> input, name of test file, line number, stored time, new time.</p>

</dd>
<dt><strong class="Mark"><code class="code">ignoreSTOP_TEST</code></strong></dt>
<dd><p>By default set to <code class="keyw">true</code>, in that case the output of <strong class="pkg">GAP</strong> input starting with <code class="code">"STOP_TEST"</code> is not checked.</p>

</dd>
<dt><strong class="Mark"><code class="code">showProgress</code></strong></dt>
<dd><p>If this is <code class="keyw">true</code> then <strong class="pkg">GAP</strong> prints position information and the input line before it is processed (default is <code class="keyw">false</code>).</p>

</dd>
<dt><strong class="Mark"><code class="code">subsWindowsLineBreaks</code></strong></dt>
<dd><p>If this is <code class="keyw">true</code> then <strong class="pkg">GAP</strong> substitutes DOS/Windows style line breaks "\r\n" by UNIX style line breaks "\n" after reading the test file. (default is <code class="keyw">true</code>).</p>

</dd>
</dl>

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

<p><a id="X85FF55448787CCA0" name="X85FF55448787CCA0"></a></p>

<h4>7.10 <span class="Heading">Debugging Recursion</span></h4>

<p>The <strong class="pkg">GAP</strong> interpreter monitors the level of nesting of <strong class="pkg">GAP</strong> functions during execution. By default, whenever this nesting reaches a multiple of <span class="SimpleMath">5000</span>, <strong class="pkg">GAP</strong> enters a break loop (<a href="chap6.html#X8593B49F8705B486"><span class="RefLink">6.4</span></a>) allowing you to terminate the calculation, or enter <strong class="button">Return</strong><code class="code">;</code> to continue it.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">dive:= function(depth) if depth&gt;1 then dive(depth-1); fi; return; end;</span>
function( depth ) ... end
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">dive(100);</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">OnBreak:= function() Where(1); end; # shorter traceback</span>
function(  ) ... end
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">dive(6000);</span>
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
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">return;</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">dive(11000);</span>
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
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">return;</span>
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
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">return;</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput"></span>
</pre></div>

<p>This behaviour can be controlled using the following procedure.</p>

<p><a id="X7D8968FC7E24A4E5" name="X7D8968FC7E24A4E5"></a></p>

<h5>7.10-1 SetRecursionTrapInterval</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; SetRecursionTrapInterval</code>( <var class="Arg">interval</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><var class="Arg">interval</var> must be a non-negative small integer (between 0 and <span class="SimpleMath">2^28</span>). An <var class="Arg">interval</var> of 0 suppresses the monitoring of recursion altogether. In this case excessive recursion may cause <strong class="pkg">GAP</strong> to crash.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">dive:= function(depth) if depth&gt;1 then dive(depth-1); fi; return; end;</span>
function( depth ) ... end
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">SetRecursionTrapInterval(1000);</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">dive(2500);</span>
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
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">return;</span>
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
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">return;</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">SetRecursionTrapInterval(-1);</span>
SetRecursionTrapInterval( &lt;interval&gt; ): &lt;interval&gt; 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 &lt;interval&gt; via 'return &lt;interval&gt;;' to continue
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">return ();</span>
SetRecursionTrapInterval( &lt;interval&gt; ): &lt;interval&gt; 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 &lt;interval&gt; via 'return &lt;interval&gt;;' to continue
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">return 0;</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">dive(20000);</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">dive(2000000);</span>
Segmentation fault
</pre></div>

<p><a id="X85679F17791D9B63" name="X85679F17791D9B63"></a></p>

<h4>7.11 <span class="Heading">Global Memory Information</span></h4>

<p>The <strong class="pkg">GAP</strong> environment provides automatic memory management, so that the programmer does not need to concern themselves with allocating space for objects, or recovering space when objects are no longer needed. The component of the kernel which provides this is called <code class="code">GASMAN</code> (<strong class="pkg">GAP</strong> Storage MANager). Messages reporting garbage collections performed by <code class="code">GASMAN</code> can be switched on by the <code class="code">-g</code> command line option (see section <a href="chap3.html#X782751D5858A6EAF"><span class="RefLink">3.1</span></a>). There are also some facilities to access information from <code class="code">GASMAN</code> from <strong class="pkg">GAP</strong> programs.</p>

<p><a id="X836977DE80416F3D" name="X836977DE80416F3D"></a></p>

<h5>7.11-1 GasmanStatistics</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; GasmanStatistics</code>(  )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">GasmanStatistics</code> returns a record containing some information from the garbage collection mechanism. The record may contain up to four components: <code class="code">full</code>, <code class="code">partial</code>, <code class="code">npartial</code>, and <code class="code">nfull</code>.</p>

<p>The <code class="code">full</code> component will be present if a full garbage collection has taken place since <strong class="pkg">GAP</strong> started. It contains information about the most recent full garbage collection. It is a record, with six components: <code class="code">livebags</code> contains the number of bags which survived the garbage collection; <code class="code">livekb</code> contains the total number of kilobytes occupied by those bags; <code class="code">deadbags</code> 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; <code class="code">deadkb</code> contains the total number of kilobytes occupied by those bags; <code class="code">freekb</code> reports the total number of kilobytes available in the <strong class="pkg">GAP</strong> workspace for new objects and <code class="code">totalkb</code> the actual size of the workspace.</p>

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

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

<p>The <code class="code">npartial</code> and <code class="code">nfull</code> components will contain the number of full and partial garbage collections performed since <strong class="pkg">GAP</strong> started.</p>

<p><a id="X85327FA5872E0356" name="X85327FA5872E0356"></a></p>

<h5>7.11-2 GasmanMessageStatus</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; GasmanMessageStatus</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">&#8227; SetGasmanMessageStatus</code>( <var class="Arg">stat</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">GasmanMessageStatus</code> returns one of the strings <code class="code">"none"</code>, <code class="code">"full"</code>, or <code class="code">"all"</code>, depending on whether the garbage collector is currently set to print messages on no collections, full collections only, or all collections, respectively.</p>

<p>Calling <code class="func">SetGasmanMessageStatus</code> with the argument <var class="Arg">stat</var>, which should be one of the three strings mentioned above, sets the garbage collector messaging level.</p>

<p><a id="X80C683247E94769F" name="X80C683247E94769F"></a></p>

<h5>7.11-3 GasmanLimits</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; GasmanLimits</code>(  )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">GasmanLimits</code> returns a record with three components: <code class="code">min</code> is the minimum workspace size as set by the <code class="code">-m</code> command line option in kilobytes. The workspace size will never be reduced below this by the garbage collector. <code class="code">max</code> is the maximum workspace size, as set by the '-o' command line option, also in kilobytes. If the workspace would need to grow past this point, <strong class="pkg">GAP</strong> will enter a break loop to warn the user. A value of 0 indicates no limit. <code class="code">kill</code> is the absolute maximum, set by the <code class="code">-K</code> command line option. The workspace will never be allowed to grow past this limit.</p>


<div class="chlinkprevnextbot">&nbsp;<a href="chap0.html">[Top of Book]</a>&nbsp;  <a href="chap0.html#contents">[Contents]</a>&nbsp;  &nbsp;<a href="chap6.html">[Previous Chapter]</a>&nbsp;  &nbsp;<a href="chap8.html">[Next Chapter]</a>&nbsp;  </div>


<div class="chlinkbot"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a>  <a href="chap1.html">1</a>  <a href="chap2.html">2</a>  <a href="chap3.html">3</a>  <a href="chap4.html">4</a>  <a href="chap5.html">5</a>  <a href="chap6.html">6</a>  <a href="chap7.html">7</a>  <a href="chap8.html">8</a>  <a href="chap9.html">9</a>  <a href="chap10.html">10</a>  <a href="chap11.html">11</a>  <a href="chap12.html">12</a>  <a href="chap13.html">13</a>  <a href="chap14.html">14</a>  <a href="chap15.html">15</a>  <a href="chap16.html">16</a>  <a href="chap17.html">17</a>  <a href="chap18.html">18</a>  <a href="chap19.html">19</a>  <a href="chap20.html">20</a>  <a href="chap21.html">21</a>  <a href="chap22.html">22</a>  <a href="chap23.html">23</a>  <a href="chap24.html">24</a>  <a href="chap25.html">25</a>  <a href="chap26.html">26</a>  <a href="chap27.html">27</a>  <a href="chap28.html">28</a>  <a href="chap29.html">29</a>  <a href="chap30.html">30</a>  <a href="chap31.html">31</a>  <a href="chap32.html">32</a>  <a href="chap33.html">33</a>  <a href="chap34.html">34</a>  <a href="chap35.html">35</a>  <a href="chap36.html">36</a>  <a href="chap37.html">37</a>  <a href="chap38.html">38</a>  <a href="chap39.html">39</a>  <a href="chap40.html">40</a>  <a href="chap41.html">41</a>  <a href="chap42.html">42</a>  <a href="chap43.html">43</a>  <a href="chap44.html">44</a>  <a href="chap45.html">45</a>  <a href="chap46.html">46</a>  <a href="chap47.html">47</a>  <a href="chap48.html">48</a>  <a href="chap49.html">49</a>  <a href="chap50.html">50</a>  <a href="chap51.html">51</a>  <a href="chap52.html">52</a>  <a href="chap53.html">53</a>  <a href="chap54.html">54</a>  <a href="chap55.html">55</a>  <a href="chap56.html">56</a>  <a href="chap57.html">57</a>  <a href="chap58.html">58</a>  <a href="chap59.html">59</a>  <a href="chap60.html">60</a>  <a href="chap61.html">61</a>  <a href="chap62.html">62</a>  <a href="chap63.html">63</a>  <a href="chap64.html">64</a>  <a href="chap65.html">65</a>  <a href="chap66.html">66</a>  <a href="chap67.html">67</a>  <a href="chap68.html">68</a>  <a href="chap69.html">69</a>  <a href="chap70.html">70</a>  <a href="chap71.html">71</a>  <a href="chap72.html">72</a>  <a href="chap73.html">73</a>  <a href="chap74.html">74</a>  <a href="chap75.html">75</a>  <a href="chap76.html">76</a>  <a href="chap77.html">77</a>  <a href="chap78.html">78</a>  <a href="chap79.html">79</a>  <a href="chap80.html">80</a>  <a href="chap81.html">81</a>  <a href="chap82.html">82</a>  <a href="chap83.html">83</a>  <a href="chap84.html">84</a>  <a href="chap85.html">85</a>  <a href="chap86.html">86</a>  <a href="chap87.html">87</a>  <a href="chapBib.html">Bib</a>  <a href="chapInd.html">Ind</a>  </div>

<hr />
<p class="foot">generated by <a href="http://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc">GAPDoc2HTML</a></p>
</body>
</html>