1.. |with| replace:: *with* 2.. |withs| replace:: *with*\ s 3.. |withed| replace:: *with*\ ed 4.. |withing| replace:: *with*\ ing 5 6.. -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit 7 8 9.. _GNAT_and_Program_Execution: 10 11************************** 12GNAT and Program Execution 13************************** 14 15This chapter covers several topics: 16 17* `Running and Debugging Ada Programs`_ 18* `Code Coverage and Profiling`_ 19* `Improving Performance`_ 20* `Overflow Check Handling in GNAT`_ 21* `Performing Dimensionality Analysis in GNAT`_ 22* `Stack Related Facilities`_ 23* `Memory Management Issues`_ 24 25.. _Running_and_Debugging_Ada_Programs: 26 27Running and Debugging Ada Programs 28================================== 29 30.. index:: Debugging 31 32This section discusses how to debug Ada programs. 33 34An incorrect Ada program may be handled in three ways by the GNAT compiler: 35 36* The illegality may be a violation of the static semantics of Ada. In 37 that case GNAT diagnoses the constructs in the program that are illegal. 38 It is then a straightforward matter for the user to modify those parts of 39 the program. 40 41* The illegality may be a violation of the dynamic semantics of Ada. In 42 that case the program compiles and executes, but may generate incorrect 43 results, or may terminate abnormally with some exception. 44 45* When presented with a program that contains convoluted errors, GNAT 46 itself may terminate abnormally without providing full diagnostics on 47 the incorrect user program. 48 49.. index:: Debugger 50 51.. index:: ! gdb 52 53.. _The_GNAT_Debugger_GDB: 54 55The GNAT Debugger GDB 56--------------------- 57 58`GDB` is a general purpose, platform-independent debugger that 59can be used to debug mixed-language programs compiled with *gcc*, 60and in particular is capable of debugging Ada programs compiled with 61GNAT. The latest versions of `GDB` are Ada-aware and can handle 62complex Ada data structures. 63 64See :title:`Debugging with GDB`, 65for full details on the usage of `GDB`, including a section on 66its usage on programs. This manual should be consulted for full 67details. The section that follows is a brief introduction to the 68philosophy and use of `GDB`. 69 70When GNAT programs are compiled, the compiler optionally writes debugging 71information into the generated object file, including information on 72line numbers, and on declared types and variables. This information is 73separate from the generated code. It makes the object files considerably 74larger, but it does not add to the size of the actual executable that 75will be loaded into memory, and has no impact on run-time performance. The 76generation of debug information is triggered by the use of the 77-g switch in the *gcc* or *gnatmake* command 78used to carry out the compilations. It is important to emphasize that 79the use of these options does not change the generated code. 80 81The debugging information is written in standard system formats that 82are used by many tools, including debuggers and profilers. The format 83of the information is typically designed to describe C types and 84semantics, but GNAT implements a translation scheme which allows full 85details about Ada types and variables to be encoded into these 86standard C formats. Details of this encoding scheme may be found in 87the file exp_dbug.ads in the GNAT source distribution. However, the 88details of this encoding are, in general, of no interest to a user, 89since `GDB` automatically performs the necessary decoding. 90 91When a program is bound and linked, the debugging information is 92collected from the object files, and stored in the executable image of 93the program. Again, this process significantly increases the size of 94the generated executable file, but it does not increase the size of 95the executable program itself. Furthermore, if this program is run in 96the normal manner, it runs exactly as if the debug information were 97not present, and takes no more actual memory. 98 99However, if the program is run under control of `GDB`, the 100debugger is activated. The image of the program is loaded, at which 101point it is ready to run. If a run command is given, then the program 102will run exactly as it would have if `GDB` were not present. This 103is a crucial part of the `GDB` design philosophy. `GDB` is 104entirely non-intrusive until a breakpoint is encountered. If no 105breakpoint is ever hit, the program will run exactly as it would if no 106debugger were present. When a breakpoint is hit, `GDB` accesses 107the debugging information and can respond to user commands to inspect 108variables, and more generally to report on the state of execution. 109 110.. _Running_GDB: 111 112Running GDB 113----------- 114 115This section describes how to initiate the debugger. 116 117The debugger can be launched from a `GPS` menu or 118directly from the command line. The description below covers the latter use. 119All the commands shown can be used in the `GPS` debug console window, 120but there are usually more GUI-based ways to achieve the same effect. 121 122The command to run `GDB` is 123 124 :: 125 126 $ gdb program 127 128where `program` is the name of the executable file. This 129activates the debugger and results in a prompt for debugger commands. 130The simplest command is simply `run`, which causes the program to run 131exactly as if the debugger were not present. The following section 132describes some of the additional commands that can be given to `GDB`. 133 134 135.. _Introduction_to_GDB_Commands: 136 137Introduction to GDB Commands 138---------------------------- 139 140`GDB` contains a large repertoire of commands. 141See :title:`Debugging with GDB` for extensive documentation on the use 142of these commands, together with examples of their use. Furthermore, 143the command *help* invoked from within GDB activates a simple help 144facility which summarizes the available commands and their options. 145In this section we summarize a few of the most commonly 146used commands to give an idea of what `GDB` is about. You should create 147a simple program with debugging information and experiment with the use of 148these `GDB` commands on the program as you read through the 149following section. 150 151* *set args `arguments`* 152 The `arguments` list above is a list of arguments to be passed to 153 the program on a subsequent run command, just as though the arguments 154 had been entered on a normal invocation of the program. The `set args` 155 command is not needed if the program does not require arguments. 156 157 158* *run* 159 The `run` command causes execution of the program to start from 160 the beginning. If the program is already running, that is to say if 161 you are currently positioned at a breakpoint, then a prompt will ask 162 for confirmation that you want to abandon the current execution and 163 restart. 164 165 166* *breakpoint `location`* 167 The breakpoint command sets a breakpoint, that is to say a point at which 168 execution will halt and `GDB` will await further 169 commands. `location` is 170 either a line number within a file, given in the format `file:linenumber`, 171 or it is the name of a subprogram. If you request that a breakpoint be set on 172 a subprogram that is overloaded, a prompt will ask you to specify on which of 173 those subprograms you want to breakpoint. You can also 174 specify that all of them should be breakpointed. If the program is run 175 and execution encounters the breakpoint, then the program 176 stops and `GDB` signals that the breakpoint was encountered by 177 printing the line of code before which the program is halted. 178 179 180* *catch exception `name`* 181 This command causes the program execution to stop whenever exception 182 `name` is raised. If `name` is omitted, then the execution is 183 suspended when any exception is raised. 184 185 186* *print `expression`* 187 This will print the value of the given expression. Most simple 188 Ada expression formats are properly handled by `GDB`, so the expression 189 can contain function calls, variables, operators, and attribute references. 190 191 192* *continue* 193 Continues execution following a breakpoint, until the next breakpoint or the 194 termination of the program. 195 196 197* *step* 198 Executes a single line after a breakpoint. If the next statement 199 is a subprogram call, execution continues into (the first statement of) 200 the called subprogram. 201 202 203* *next* 204 Executes a single line. If this line is a subprogram call, executes and 205 returns from the call. 206 207 208* *list* 209 Lists a few lines around the current source location. In practice, it 210 is usually more convenient to have a separate edit window open with the 211 relevant source file displayed. Successive applications of this command 212 print subsequent lines. The command can be given an argument which is a 213 line number, in which case it displays a few lines around the specified one. 214 215 216* *backtrace* 217 Displays a backtrace of the call chain. This command is typically 218 used after a breakpoint has occurred, to examine the sequence of calls that 219 leads to the current breakpoint. The display includes one line for each 220 activation record (frame) corresponding to an active subprogram. 221 222 223* *up* 224 At a breakpoint, `GDB` can display the values of variables local 225 to the current frame. The command `up` can be used to 226 examine the contents of other active frames, by moving the focus up 227 the stack, that is to say from callee to caller, one frame at a time. 228 229 230* *down* 231 Moves the focus of `GDB` down from the frame currently being 232 examined to the frame of its callee (the reverse of the previous command), 233 234 235* *frame `n`* 236 Inspect the frame with the given number. The value 0 denotes the frame 237 of the current breakpoint, that is to say the top of the call stack. 238 239 240* *kill* 241 Kills the child process in which the program is running under GDB. 242 This may be useful for several purposes: 243 244 * It allows you to recompile and relink your program, since on many systems 245 you cannot regenerate an executable file while it is running in a process. 246 247 * You can run your program outside the debugger, on systems that do not 248 permit executing a program outside GDB while breakpoints are set 249 within GDB. 250 251 * It allows you to debug a core dump rather than a running process. 252 253The above list is a very short introduction to the commands that 254`GDB` provides. Important additional capabilities, including conditional 255breakpoints, the ability to execute command sequences on a breakpoint, 256the ability to debug at the machine instruction level and many other 257features are described in detail in :title:`Debugging with GDB`. 258Note that most commands can be abbreviated 259(for example, c for continue, bt for backtrace). 260 261 262.. _Using_Ada_Expressions: 263 264Using Ada Expressions 265--------------------- 266 267.. index:: Ada expressions (in gdb) 268 269`GDB` supports a fairly large subset of Ada expression syntax, with some 270extensions. The philosophy behind the design of this subset is 271 272 * That `GDB` should provide basic literals and access to operations for 273 arithmetic, dereferencing, field selection, indexing, and subprogram calls, 274 leaving more sophisticated computations to subprograms written into the 275 program (which therefore may be called from `GDB`). 276 277 * That type safety and strict adherence to Ada language restrictions 278 are not particularly relevant in a debugging context. 279 280 * That brevity is important to the `GDB` user. 281 282Thus, for brevity, the debugger acts as if there were 283implicit `with` and `use` clauses in effect for all user-written 284packages, thus making it unnecessary to fully qualify most names with 285their packages, regardless of context. Where this causes ambiguity, 286`GDB` asks the user's intent. 287 288For details on the supported Ada syntax, see :title:`Debugging with GDB`. 289 290 291.. _Calling_User-Defined_Subprograms: 292 293Calling User-Defined Subprograms 294-------------------------------- 295 296An important capability of `GDB` is the ability to call user-defined 297subprograms while debugging. This is achieved simply by entering 298a subprogram call statement in the form: 299 300 :: 301 302 call subprogram-name (parameters) 303 304The keyword `call` can be omitted in the normal case where the 305`subprogram-name` does not coincide with any of the predefined 306`GDB` commands. 307 308The effect is to invoke the given subprogram, passing it the 309list of parameters that is supplied. The parameters can be expressions and 310can include variables from the program being debugged. The 311subprogram must be defined 312at the library level within your program, and `GDB` will call the 313subprogram within the environment of your program execution (which 314means that the subprogram is free to access or even modify variables 315within your program). 316 317The most important use of this facility is in allowing the inclusion of 318debugging routines that are tailored to particular data structures 319in your program. Such debugging routines can be written to provide a suitably 320high-level description of an abstract type, rather than a low-level dump 321of its physical layout. After all, the standard 322`GDB print` command only knows the physical layout of your 323types, not their abstract meaning. Debugging routines can provide information 324at the desired semantic level and are thus enormously useful. 325 326For example, when debugging GNAT itself, it is crucial to have access to 327the contents of the tree nodes used to represent the program internally. 328But tree nodes are represented simply by an integer value (which in turn 329is an index into a table of nodes). 330Using the `print` command on a tree node would simply print this integer 331value, which is not very useful. But the PN routine (defined in file 332treepr.adb in the GNAT sources) takes a tree node as input, and displays 333a useful high level representation of the tree node, which includes the 334syntactic category of the node, its position in the source, the integers 335that denote descendant nodes and parent node, as well as varied 336semantic information. To study this example in more detail, you might want to 337look at the body of the PN procedure in the stated file. 338 339Another useful application of this capability is to deal with situations of 340complex data which are not handled suitably by GDB. For example, if you specify 341Convention Fortran for a multi-dimensional array, GDB does not know that 342the ordering of array elements has been switched and will not properly 343address the array elements. In such a case, instead of trying to print the 344elements directly from GDB, you can write a callable procedure that prints 345the elements in the desired format. 346 347 348.. _Using_the_Next_Command_in_a_Function: 349 350Using the *next* Command in a Function 351-------------------------------------- 352 353When you use the `next` command in a function, the current source 354location will advance to the next statement as usual. A special case 355arises in the case of a `return` statement. 356 357Part of the code for a return statement is the 'epilogue' of the function. 358This is the code that returns to the caller. There is only one copy of 359this epilogue code, and it is typically associated with the last return 360statement in the function if there is more than one return. In some 361implementations, this epilogue is associated with the first statement 362of the function. 363 364The result is that if you use the `next` command from a return 365statement that is not the last return statement of the function you 366may see a strange apparent jump to the last return statement or to 367the start of the function. You should simply ignore this odd jump. 368The value returned is always that from the first return statement 369that was stepped through. 370 371 372.. _Stopping_When_Ada_Exceptions_Are_Raised: 373 374Stopping When Ada Exceptions Are Raised 375--------------------------------------- 376 377.. index:: Exceptions (in gdb) 378 379You can set catchpoints that stop the program execution when your program 380raises selected exceptions. 381 382 383* *catch exception* 384 Set a catchpoint that stops execution whenever (any task in the) program 385 raises any exception. 386 387 388* *catch exception `name`* 389 Set a catchpoint that stops execution whenever (any task in the) program 390 raises the exception `name`. 391 392 393* *catch exception unhandled* 394 Set a catchpoint that stops executing whenever (any task in the) program 395 raises an exception for which there is no handler. 396 397 398* *info exceptions*, *info exceptions `regexp`* 399 The `info exceptions` command permits the user to examine all defined 400 exceptions within Ada programs. With a regular expression, `regexp`, as 401 argument, prints out only those exceptions whose name matches `regexp`. 402 403 404.. index:: Tasks (in gdb) 405 406.. _Ada_Tasks: 407 408Ada Tasks 409--------- 410 411`GDB` allows the following task-related commands: 412 413 414* *info tasks* 415 This command shows a list of current Ada tasks, as in the following example: 416 417 :: 418 419 (gdb) info tasks 420 ID TID P-ID Thread Pri State Name 421 1 8088000 0 807e000 15 Child Activation Wait main_task 422 2 80a4000 1 80ae000 15 Accept/Select Wait b 423 3 809a800 1 80a4800 15 Child Activation Wait a 424 * 4 80ae800 3 80b8000 15 Running c 425 426 427 In this listing, the asterisk before the first task indicates it to be the 428 currently running task. The first column lists the task ID that is used 429 to refer to tasks in the following commands. 430 431 432.. index:: Breakpoints and tasks 433 434* *break `linespec` task `taskid`*, *break `linespec` task `taskid` if ...* 435 436 These commands are like the `break ... thread ...`. 437 `linespec` specifies source lines. 438 439 Use the qualifier :samp:`task {taskid}` with a breakpoint command 440 to specify that you only want `GDB` to stop the program when a 441 particular Ada task reaches this breakpoint. `taskid` is one of the 442 numeric task identifiers assigned by `GDB`, shown in the first 443 column of the ``info tasks`` display. 444 445 If you do not specify :samp:`task {taskid}` when you set a 446 breakpoint, the breakpoint applies to *all* tasks of your 447 program. 448 449 You can use the `task` qualifier on conditional breakpoints as 450 well; in this case, place :samp:`task {taskid}` before the 451 breakpoint condition (before the `if`). 452 453.. index:: Task switching (in gdb) 454 455* *task `taskno`* 456 457 This command allows switching to the task referred by `taskno`. In 458 particular, this allows browsing of the backtrace of the specified 459 task. It is advisable to switch back to the original task before 460 continuing execution otherwise the scheduling of the program may be 461 perturbed. 462 463For more detailed information on the tasking support, 464see :title:`Debugging with GDB`. 465 466 467.. index:: Debugging Generic Units 468.. index:: Generics 469 470.. _Debugging_Generic_Units: 471 472Debugging Generic Units 473----------------------- 474 475GNAT always uses code expansion for generic instantiation. This means that 476each time an instantiation occurs, a complete copy of the original code is 477made, with appropriate substitutions of formals by actuals. 478 479It is not possible to refer to the original generic entities in 480`GDB`, but it is always possible to debug a particular instance of 481a generic, by using the appropriate expanded names. For example, if we have 482 483 .. code-block:: ada 484 485 procedure g is 486 487 generic package k is 488 procedure kp (v1 : in out integer); 489 end k; 490 491 package body k is 492 procedure kp (v1 : in out integer) is 493 begin 494 v1 := v1 + 1; 495 end kp; 496 end k; 497 498 package k1 is new k; 499 package k2 is new k; 500 501 var : integer := 1; 502 503 begin 504 k1.kp (var); 505 k2.kp (var); 506 k1.kp (var); 507 k2.kp (var); 508 end; 509 510Then to break on a call to procedure kp in the k2 instance, simply 511use the command: 512 513 :: 514 515 (gdb) break g.k2.kp 516 517When the breakpoint occurs, you can step through the code of the 518instance in the normal manner and examine the values of local variables, as for 519other units. 520 521 522.. index:: Remote Debugging with gdbserver 523 524.. _Remote_Debugging_with_gdbserver: 525 526Remote Debugging with gdbserver 527------------------------------- 528 529On platforms where gdbserver is supported, it is possible to use this tool 530to debug your application remotely. This can be useful in situations 531where the program needs to be run on a target host that is different 532from the host used for development, particularly when the target has 533a limited amount of resources (either CPU and/or memory). 534 535To do so, start your program using gdbserver on the target machine. 536gdbserver then automatically suspends the execution of your program 537at its entry point, waiting for a debugger to connect to it. The 538following commands starts an application and tells gdbserver to 539wait for a connection with the debugger on localhost port 4444. 540 541 542 :: 543 544 $ gdbserver localhost:4444 program 545 Process program created; pid = 5685 546 Listening on port 4444 547 548Once gdbserver has started listening, we can tell the debugger to establish 549a connection with this gdbserver, and then start the same debugging session 550as if the program was being debugged on the same host, directly under 551the control of GDB. 552 553 :: 554 555 $ gdb program 556 (gdb) target remote targethost:4444 557 Remote debugging using targethost:4444 558 0x00007f29936d0af0 in ?? () from /lib64/ld-linux-x86-64.so. 559 (gdb) b foo.adb:3 560 Breakpoint 1 at 0x401f0c: file foo.adb, line 3. 561 (gdb) continue 562 Continuing. 563 564 Breakpoint 1, foo () at foo.adb:4 565 4 end foo; 566 567It is also possible to use gdbserver to attach to an already running 568program, in which case the execution of that program is simply suspended 569until the connection between the debugger and gdbserver is established. 570 571For more information on how to use gdbserver, see the *Using the gdbserver Program* 572section in :title:`Debugging with GDB`. 573GNAT provides support for gdbserver on x86-linux, x86-windows and x86_64-linux. 574 575 576.. index:: Abnormal Termination or Failure to Terminate 577 578.. _GNAT_Abnormal_Termination_or_Failure_to_Terminate: 579 580GNAT Abnormal Termination or Failure to Terminate 581------------------------------------------------- 582 583When presented with programs that contain serious errors in syntax 584or semantics, 585GNAT may on rare occasions experience problems in operation, such 586as aborting with a 587segmentation fault or illegal memory access, raising an internal 588exception, terminating abnormally, or failing to terminate at all. 589In such cases, you can activate 590various features of GNAT that can help you pinpoint the construct in your 591program that is the likely source of the problem. 592 593The following strategies are presented in increasing order of 594difficulty, corresponding to your experience in using GNAT and your 595familiarity with compiler internals. 596 597* Run *gcc* with the *-gnatf*. This first 598 switch causes all errors on a given line to be reported. In its absence, 599 only the first error on a line is displayed. 600 601 The *-gnatdO* switch causes errors to be displayed as soon as they 602 are encountered, rather than after compilation is terminated. If GNAT 603 terminates prematurely or goes into an infinite loop, the last error 604 message displayed may help to pinpoint the culprit. 605 606* Run *gcc* with the *-v (verbose)* switch. In this 607 mode, *gcc* produces ongoing information about the progress of the 608 compilation and provides the name of each procedure as code is 609 generated. This switch allows you to find which Ada procedure was being 610 compiled when it encountered a code generation problem. 611 612.. index:: -gnatdc switch 613 614* Run *gcc* with the *-gnatdc* switch. This is a GNAT specific 615 switch that does for the front-end what *-v* does 616 for the back end. The system prints the name of each unit, 617 either a compilation unit or nested unit, as it is being analyzed. 618 619* Finally, you can start 620 `gdb` directly on the `gnat1` executable. `gnat1` is the 621 front-end of GNAT, and can be run independently (normally it is just 622 called from *gcc*). You can use `gdb` on `gnat1` as you 623 would on a C program (but :ref:`The_GNAT_Debugger_GDB` for caveats). The 624 `where` command is the first line of attack; the variable 625 `lineno` (seen by `print lineno`), used by the second phase of 626 `gnat1` and by the *gcc* backend, indicates the source line at 627 which the execution stopped, and `input_file name` indicates the name of 628 the source file. 629 630 631.. _Naming_Conventions_for_GNAT_Source_Files: 632 633Naming Conventions for GNAT Source Files 634---------------------------------------- 635 636In order to examine the workings of the GNAT system, the following 637brief description of its organization may be helpful: 638 639* Files with prefix :file:`sc` contain the lexical scanner. 640 641* All files prefixed with :file:`par` are components of the parser. The 642 numbers correspond to chapters of the Ada Reference Manual. For example, 643 parsing of select statements can be found in :file:`par-ch9.adb`. 644 645* All files prefixed with :file:`sem` perform semantic analysis. The 646 numbers correspond to chapters of the Ada standard. For example, all 647 issues involving context clauses can be found in :file:`sem_ch10.adb`. In 648 addition, some features of the language require sufficient special processing 649 to justify their own semantic files: sem_aggr for aggregates, sem_disp for 650 dynamic dispatching, etc. 651 652* All files prefixed with :file:`exp` perform normalization and 653 expansion of the intermediate representation (abstract syntax tree, or AST). 654 these files use the same numbering scheme as the parser and semantics files. 655 For example, the construction of record initialization procedures is done in 656 :file:`exp_ch3.adb`. 657 658* The files prefixed with :file:`bind` implement the binder, which 659 verifies the consistency of the compilation, determines an order of 660 elaboration, and generates the bind file. 661 662* The files :file:`atree.ads` and :file:`atree.adb` detail the low-level 663 data structures used by the front-end. 664 665* The files :file:`sinfo.ads` and :file:`sinfo.adb` detail the structure of 666 the abstract syntax tree as produced by the parser. 667 668* The files :file:`einfo.ads` and :file:`einfo.adb` detail the attributes of 669 all entities, computed during semantic analysis. 670 671* Library management issues are dealt with in files with prefix 672 :file:`lib`. 673 674 .. index:: Annex A (in Ada Reference Manual) 675 676* Ada files with the prefix :file:`a-` are children of `Ada`, as 677 defined in Annex A. 678 679 .. index:: Annex B (in Ada reference Manual) 680 681* Files with prefix :file:`i-` are children of `Interfaces`, as 682 defined in Annex B. 683 684 .. index:: System (package in Ada Reference Manual) 685 686* Files with prefix :file:`s-` are children of `System`. This includes 687 both language-defined children and GNAT run-time routines. 688 689 .. index:: GNAT (package) 690 691* Files with prefix :file:`g-` are children of `GNAT`. These are useful 692 general-purpose packages, fully documented in their specs. All 693 the other :file:`.c` files are modifications of common *gcc* files. 694 695 696.. _Getting_Internal_Debugging_Information: 697 698Getting Internal Debugging Information 699-------------------------------------- 700 701Most compilers have internal debugging switches and modes. GNAT 702does also, except GNAT internal debugging switches and modes are not 703secret. A summary and full description of all the compiler and binder 704debug flags are in the file :file:`debug.adb`. You must obtain the 705sources of the compiler to see the full detailed effects of these flags. 706 707The switches that print the source of the program (reconstructed from 708the internal tree) are of general interest for user programs, as are the 709options to print 710the full internal tree, and the entity table (the symbol table 711information). The reconstructed source provides a readable version of the 712program after the front-end has completed analysis and expansion, 713and is useful when studying the performance of specific constructs. 714For example, constraint checks are indicated, complex aggregates 715are replaced with loops and assignments, and tasking primitives 716are replaced with run-time calls. 717 718 719.. index:: traceback 720.. index:: stack traceback 721.. index:: stack unwinding 722 723.. _Stack_Traceback: 724 725Stack Traceback 726--------------- 727 728Traceback is a mechanism to display the sequence of subprogram calls that 729leads to a specified execution point in a program. Often (but not always) 730the execution point is an instruction at which an exception has been raised. 731This mechanism is also known as *stack unwinding* because it obtains 732its information by scanning the run-time stack and recovering the activation 733records of all active subprograms. Stack unwinding is one of the most 734important tools for program debugging. 735 736The first entry stored in traceback corresponds to the deepest calling level, 737that is to say the subprogram currently executing the instruction 738from which we want to obtain the traceback. 739 740Note that there is no runtime performance penalty when stack traceback 741is enabled, and no exception is raised during program execution. 742 743.. index:: traceback, non-symbolic 744 745.. _Non-Symbolic_Traceback: 746 747Non-Symbolic Traceback 748^^^^^^^^^^^^^^^^^^^^^^ 749 750Note: this feature is not supported on all platforms. See 751:samp:`GNAT.Traceback` spec in :file:`g-traceb.ads` 752for a complete list of supported platforms. 753 754.. rubric:: Tracebacks From an Unhandled Exception 755 756A runtime non-symbolic traceback is a list of addresses of call instructions. 757To enable this feature you must use the *-E* 758`gnatbind`'s option. With this option a stack traceback is stored as part 759of exception information. You can retrieve this information using the 760`addr2line` tool. 761 762Here is a simple example: 763 764 .. code-block:: ada 765 766 procedure STB is 767 768 procedure P1 is 769 begin 770 raise Constraint_Error; 771 end P1; 772 773 procedure P2 is 774 begin 775 P1; 776 end P2; 777 778 begin 779 P2; 780 end STB; 781 782 :: 783 784 $ gnatmake stb -bargs -E 785 $ stb 786 787 Execution terminated by unhandled exception 788 Exception name: CONSTRAINT_ERROR 789 Message: stb.adb:5 790 Call stack traceback locations: 791 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 792 793As we see the traceback lists a sequence of addresses for the unhandled 794exception `CONSTRAINT_ERROR` raised in procedure P1. It is easy to 795guess that this exception come from procedure P1. To translate these 796addresses into the source lines where the calls appear, the 797`addr2line` tool, described below, is invaluable. The use of this tool 798requires the program to be compiled with debug information. 799 800 :: 801 802 $ gnatmake -g stb -bargs -E 803 $ stb 804 805 Execution terminated by unhandled exception 806 Exception name: CONSTRAINT_ERROR 807 Message: stb.adb:5 808 Call stack traceback locations: 809 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 810 811 $ addr2line --exe=stb 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 812 0x4011f1 0x77e892a4 813 814 00401373 at d:/stb/stb.adb:5 815 0040138B at d:/stb/stb.adb:10 816 0040139C at d:/stb/stb.adb:14 817 00401335 at d:/stb/b~stb.adb:104 818 004011C4 at /build/.../crt1.c:200 819 004011F1 at /build/.../crt1.c:222 820 77E892A4 in ?? at ??:0 821 822The `addr2line` tool has several other useful options: 823 824 ======================== ======================================================== 825 :samp:`--functions` to get the function name corresponding to any location 826 :samp:`--demangle=gnat` to use the gnat decoding mode for the function names. 827 Note that for binutils version 2.9.x the option is 828 simply :samp:`--demangle`. 829 ======================== ======================================================== 830 831 :: 832 833 $ addr2line --exe=stb --functions --demangle=gnat 0x401373 0x40138b 834 0x40139c 0x401335 0x4011c4 0x4011f1 835 836 00401373 in stb.p1 at d:/stb/stb.adb:5 837 0040138B in stb.p2 at d:/stb/stb.adb:10 838 0040139C in stb at d:/stb/stb.adb:14 839 00401335 in main at d:/stb/b~stb.adb:104 840 004011C4 in <__mingw_CRTStartup> at /build/.../crt1.c:200 841 004011F1 in <mainCRTStartup> at /build/.../crt1.c:222 842 843From this traceback we can see that the exception was raised in 844:file:`stb.adb` at line 5, which was reached from a procedure call in 845:file:`stb.adb` at line 10, and so on. The :file:`b~std.adb` is the binder file, 846which contains the call to the main program. 847:ref:`Running_gnatbind`. The remaining entries are assorted runtime routines, 848and the output will vary from platform to platform. 849 850It is also possible to use `GDB` with these traceback addresses to debug 851the program. For example, we can break at a given code location, as reported 852in the stack traceback: 853 854 :: 855 856 $ gdb -nw stb 857 858Furthermore, this feature is not implemented inside Windows DLL. Only 859the non-symbolic traceback is reported in this case. 860 861 :: 862 863 (gdb) break *0x401373 864 Breakpoint 1 at 0x401373: file stb.adb, line 5. 865 866It is important to note that the stack traceback addresses 867do not change when debug information is included. This is particularly useful 868because it makes it possible to release software without debug information (to 869minimize object size), get a field report that includes a stack traceback 870whenever an internal bug occurs, and then be able to retrieve the sequence 871of calls with the same program compiled with debug information. 872 873 874.. rubric:: Tracebacks From Exception Occurrences 875 876Non-symbolic tracebacks are obtained by using the *-E* binder argument. 877The stack traceback is attached to the exception information string, and can 878be retrieved in an exception handler within the Ada program, by means of the 879Ada facilities defined in `Ada.Exceptions`. Here is a simple example: 880 881 .. code-block:: ada 882 883 with Ada.Text_IO; 884 with Ada.Exceptions; 885 886 procedure STB is 887 888 use Ada; 889 use Ada.Exceptions; 890 891 procedure P1 is 892 K : Positive := 1; 893 begin 894 K := K - 1; 895 exception 896 when E : others => 897 Text_IO.Put_Line (Exception_Information (E)); 898 end P1; 899 900 procedure P2 is 901 begin 902 P1; 903 end P2; 904 905 begin 906 P2; 907 end STB; 908 909This program will output: 910 911 :: 912 913 $ stb 914 915 Exception name: CONSTRAINT_ERROR 916 Message: stb.adb:12 917 Call stack traceback locations: 918 0x4015e4 0x401633 0x401644 0x401461 0x4011c4 0x4011f1 0x77e892a4 919 920 921.. rubric:: Tracebacks From Anywhere in a Program 922 923It is also possible to retrieve a stack traceback from anywhere in a 924program. For this you need to 925use the `GNAT.Traceback` API. This package includes a procedure called 926`Call_Chain` that computes a complete stack traceback, as well as useful 927display procedures described below. It is not necessary to use the 928*-E gnatbind* option in this case, because the stack traceback mechanism 929is invoked explicitly. 930 931In the following example we compute a traceback at a specific location in 932the program, and we display it using `GNAT.Debug_Utilities.Image` to 933convert addresses to strings: 934 935 936 .. code-block:: ada 937 938 with Ada.Text_IO; 939 with GNAT.Traceback; 940 with GNAT.Debug_Utilities; 941 942 procedure STB is 943 944 use Ada; 945 use GNAT; 946 use GNAT.Traceback; 947 948 procedure P1 is 949 TB : Tracebacks_Array (1 .. 10); 950 -- We are asking for a maximum of 10 stack frames. 951 Len : Natural; 952 -- Len will receive the actual number of stack frames returned. 953 begin 954 Call_Chain (TB, Len); 955 956 Text_IO.Put ("In STB.P1 : "); 957 958 for K in 1 .. Len loop 959 Text_IO.Put (Debug_Utilities.Image (TB (K))); 960 Text_IO.Put (' '); 961 end loop; 962 963 Text_IO.New_Line; 964 end P1; 965 966 procedure P2 is 967 begin 968 P1; 969 end P2; 970 971 begin 972 P2; 973 end STB; 974 975 :: 976 977 $ gnatmake -g stb 978 $ stb 979 980 In STB.P1 : 16#0040_F1E4# 16#0040_14F2# 16#0040_170B# 16#0040_171C# 981 16#0040_1461# 16#0040_11C4# 16#0040_11F1# 16#77E8_92A4# 982 983 984You can then get further information by invoking the `addr2line` 985tool as described earlier (note that the hexadecimal addresses 986need to be specified in C format, with a leading '0x'). 987 988.. index:: traceback, symbolic 989 990.. _Symbolic_Traceback: 991 992Symbolic Traceback 993^^^^^^^^^^^^^^^^^^ 994 995A symbolic traceback is a stack traceback in which procedure names are 996associated with each code location. 997 998Note that this feature is not supported on all platforms. See 999:samp:`GNAT.Traceback.Symbolic` spec in :file:`g-trasym.ads` for a complete 1000list of currently supported platforms. 1001 1002Note that the symbolic traceback requires that the program be compiled 1003with debug information. If it is not compiled with debug information 1004only the non-symbolic information will be valid. 1005 1006 1007.. rubric:: Tracebacks From Exception Occurrences 1008 1009Here is an example: 1010 1011 .. code-block:: ada 1012 1013 with Ada.Text_IO; 1014 with GNAT.Traceback.Symbolic; 1015 1016 procedure STB is 1017 1018 procedure P1 is 1019 begin 1020 raise Constraint_Error; 1021 end P1; 1022 1023 procedure P2 is 1024 begin 1025 P1; 1026 end P2; 1027 1028 procedure P3 is 1029 begin 1030 P2; 1031 end P3; 1032 1033 begin 1034 P3; 1035 exception 1036 when E : others => 1037 Ada.Text_IO.Put_Line (GNAT.Traceback.Symbolic.Symbolic_Traceback (E)); 1038 end STB; 1039 1040 :: 1041 1042 $ gnatmake -g .\stb -bargs -E 1043 $ stb 1044 1045 0040149F in stb.p1 at stb.adb:8 1046 004014B7 in stb.p2 at stb.adb:13 1047 004014CF in stb.p3 at stb.adb:18 1048 004015DD in ada.stb at stb.adb:22 1049 00401461 in main at b~stb.adb:168 1050 004011C4 in __mingw_CRTStartup at crt1.c:200 1051 004011F1 in mainCRTStartup at crt1.c:222 1052 77E892A4 in ?? at ??:0 1053 1054In the above example the ``.\`` syntax in the *gnatmake* command 1055is currently required by *addr2line* for files that are in 1056the current working directory. 1057Moreover, the exact sequence of linker options may vary from platform 1058to platform. 1059The above *-largs* section is for Windows platforms. By contrast, 1060under Unix there is no need for the *-largs* section. 1061Differences across platforms are due to details of linker implementation. 1062 1063 1064.. rubric:: Tracebacks From Anywhere in a Program 1065 1066It is possible to get a symbolic stack traceback 1067from anywhere in a program, just as for non-symbolic tracebacks. 1068The first step is to obtain a non-symbolic 1069traceback, and then call `Symbolic_Traceback` to compute the symbolic 1070information. Here is an example: 1071 1072 .. code-block:: ada 1073 1074 with Ada.Text_IO; 1075 with GNAT.Traceback; 1076 with GNAT.Traceback.Symbolic; 1077 1078 procedure STB is 1079 1080 use Ada; 1081 use GNAT.Traceback; 1082 use GNAT.Traceback.Symbolic; 1083 1084 procedure P1 is 1085 TB : Tracebacks_Array (1 .. 10); 1086 -- We are asking for a maximum of 10 stack frames. 1087 Len : Natural; 1088 -- Len will receive the actual number of stack frames returned. 1089 begin 1090 Call_Chain (TB, Len); 1091 Text_IO.Put_Line (Symbolic_Traceback (TB (1 .. Len))); 1092 end P1; 1093 1094 procedure P2 is 1095 begin 1096 P1; 1097 end P2; 1098 1099 begin 1100 P2; 1101 end STB; 1102 1103 1104.. rubric:: Automatic Symbolic Tracebacks 1105 1106Symbolic tracebacks may also be enabled by using the -Es switch to gnatbind (as 1107in `gprbuild -g ... -bargs -Es`). 1108This will cause the Exception_Information to contain a symbolic traceback, 1109which will also be printed if an unhandled exception terminates the 1110program. 1111 1112 1113.. index:: Code Coverage 1114.. index:: Profiling 1115 1116 1117.. _Code_Coverage_and_Profiling: 1118 1119Code Coverage and Profiling 1120=========================== 1121 1122This section describes how to use the `gcov` coverage testing tool and 1123the `gprof` profiler tool on Ada programs. 1124 1125.. index:: ! gcov 1126 1127.. _Code_Coverage_of_Ada_Programs_with_gcov: 1128 1129Code Coverage of Ada Programs with gcov 1130--------------------------------------- 1131 1132`gcov` is a test coverage program: it analyzes the execution of a given 1133program on selected tests, to help you determine the portions of the program 1134that are still untested. 1135 1136`gcov` is part of the GCC suite, and is described in detail in the GCC 1137User's Guide. You can refer to this documentation for a more complete 1138description. 1139 1140This chapter provides a quick startup guide, and 1141details some GNAT-specific features. 1142 1143.. _Quick_startup_guide: 1144 1145Quick startup guide 1146^^^^^^^^^^^^^^^^^^^ 1147 1148In order to perform coverage analysis of a program using `gcov`, several 1149steps are needed: 1150 1151#. Instrument the code during the compilation process, 1152#. Execute the instrumented program, and 1153#. Invoke the `gcov` tool to generate the coverage results. 1154 1155.. index:: -fprofile-arcs (gcc) 1156.. index:: -ftest-coverage (gcc 1157.. index:: -fprofile-arcs (gnatbind) 1158 1159The code instrumentation needed by gcov is created at the object level. 1160The source code is not modified in any way, because the instrumentation code is 1161inserted by gcc during the compilation process. To compile your code with code 1162coverage activated, you need to recompile your whole project using the 1163switches 1164`-fprofile-arcs` and `-ftest-coverage`, and link it using 1165`-fprofile-arcs`. 1166 1167 :: 1168 1169 $ gnatmake -P my_project.gpr -f -cargs -fprofile-arcs -ftest-coverage \\ 1170 -largs -fprofile-arcs 1171 1172This compilation process will create :file:`.gcno` files together with 1173the usual object files. 1174 1175Once the program is compiled with coverage instrumentation, you can 1176run it as many times as needed -- on portions of a test suite for 1177example. The first execution will produce :file:`.gcda` files at the 1178same location as the :file:`.gcno` files. Subsequent executions 1179will update those files, so that a cumulative result of the covered 1180portions of the program is generated. 1181 1182Finally, you need to call the `gcov` tool. The different options of 1183`gcov` are described in the GCC User's Guide, section 'Invoking gcov'. 1184 1185This will create annotated source files with a :file:`.gcov` extension: 1186:file:`my_main.adb` file will be analyzed in :file:`my_main.adb.gcov`. 1187 1188 1189.. _GNAT_specifics: 1190 1191GNAT specifics 1192^^^^^^^^^^^^^^ 1193 1194Because of Ada semantics, portions of the source code may be shared among 1195several object files. This is the case for example when generics are 1196involved, when inlining is active or when declarations generate initialisation 1197calls. In order to take 1198into account this shared code, you need to call `gcov` on all 1199source files of the tested program at once. 1200 1201The list of source files might exceed the system's maximum command line 1202length. In order to bypass this limitation, a new mechanism has been 1203implemented in `gcov`: you can now list all your project's files into a 1204text file, and provide this file to gcov as a parameter, preceded by a ``@`` 1205(e.g. :samp:`gcov @mysrclist.txt`). 1206 1207Note that on AIX compiling a static library with `-fprofile-arcs` is 1208not supported as there can be unresolved symbols during the final link. 1209 1210 1211.. index:: ! gprof 1212.. index:: Profiling 1213 1214.. _Profiling_an_Ada_Program_with_gprof: 1215 1216Profiling an Ada Program with gprof 1217----------------------------------- 1218 1219This section is not meant to be an exhaustive documentation of `gprof`. 1220Full documentation for it can be found in the :title:`GNU Profiler User's Guide` 1221documentation that is part of this GNAT distribution. 1222 1223Profiling a program helps determine the parts of a program that are executed 1224most often, and are therefore the most time-consuming. 1225 1226`gprof` is the standard GNU profiling tool; it has been enhanced to 1227better handle Ada programs and multitasking. 1228It is currently supported on the following platforms 1229 1230* linux x86/x86_64 1231* solaris sparc/sparc64/x86 1232* windows x86 1233 1234In order to profile a program using `gprof`, several steps are needed: 1235 1236#. Instrument the code, which requires a full recompilation of the project with the 1237 proper switches. 1238 1239#. Execute the program under the analysis conditions, i.e. with the desired 1240 input. 1241 1242#. Analyze the results using the `gprof` tool. 1243 1244The following sections detail the different steps, and indicate how 1245to interpret the results. 1246 1247 1248.. _Compilation_for_profiling: 1249 1250Compilation for profiling 1251^^^^^^^^^^^^^^^^^^^^^^^^^ 1252 1253.. index:: -pg (gcc), for profiling 1254.. index:: -pg (gnatlink), for profiling 1255 1256In order to profile a program the first step is to tell the compiler 1257to generate the necessary profiling information. The compiler switch to be used 1258is ``-pg``, which must be added to other compilation switches. This 1259switch needs to be specified both during compilation and link stages, and can 1260be specified once when using gnatmake: 1261 1262 :: 1263 1264 $ gnatmake -f -pg -P my_project 1265 1266Note that only the objects that were compiled with the ``-pg`` switch will 1267be profiled; if you need to profile your whole project, use the ``-f`` 1268gnatmake switch to force full recompilation. 1269 1270.. _Program_execution: 1271 1272 1273Program execution 1274^^^^^^^^^^^^^^^^^ 1275 1276Once the program has been compiled for profiling, you can run it as usual. 1277 1278The only constraint imposed by profiling is that the program must terminate 1279normally. An interrupted program (via a Ctrl-C, kill, etc.) will not be 1280properly analyzed. 1281 1282Once the program completes execution, a data file called :file:`gmon.out` is 1283generated in the directory where the program was launched from. If this file 1284already exists, it will be overwritten. 1285 1286 1287.. _Running_gprof: 1288 1289Running gprof 1290^^^^^^^^^^^^^ 1291 1292The `gprof` tool is called as follow: 1293 1294 :: 1295 1296 $ gprof my_prog gmon.out 1297 1298or simply: 1299 1300 :: 1301 1302 $ gprof my_prog 1303 1304The complete form of the gprof command line is the following: 1305 1306 :: 1307 1308 $ gprof [switches] [executable [data-file]] 1309 1310`gprof` supports numerous switches. The order of these 1311switch does not matter. The full list of options can be found in 1312the GNU Profiler User's Guide documentation that comes with this documentation. 1313 1314The following is the subset of those switches that is most relevant: 1315 1316.. index:: --demangle (gprof) 1317 1318:samp:`--demangle[={style}]`, :samp:`--no-demangle` 1319 These options control whether symbol names should be demangled when 1320 printing output. The default is to demangle C++ symbols. The 1321 ``--no-demangle`` option may be used to turn off demangling. Different 1322 compilers have different mangling styles. The optional demangling style 1323 argument can be used to choose an appropriate demangling style for your 1324 compiler, in particular Ada symbols generated by GNAT can be demangled using 1325 ``--demangle=gnat``. 1326 1327 1328.. index:: -e (gprof) 1329 1330:samp:`-e {function_name}` 1331 The :samp:`-e {function}` option tells `gprof` not to print 1332 information about the function `function_name` (and its 1333 children...) in the call graph. The function will still be listed 1334 as a child of any functions that call it, but its index number will be 1335 shown as ``[not printed]``. More than one ``-e`` option may be 1336 given; only one `function_name` may be indicated with each ``-e`` 1337 option. 1338 1339 1340.. index:: -E (gprof) 1341 1342:samp:`-E {function_name}` 1343 The :samp:`-E {function}` option works like the ``-e`` option, but 1344 execution time spent in the function (and children who were not called from 1345 anywhere else), will not be used to compute the percentages-of-time for 1346 the call graph. More than one ``-E`` option may be given; only one 1347 `function_name` may be indicated with each ``-E`` option. 1348 1349 1350.. index:: -f (gprof) 1351 1352:samp:`-f {function_name}` 1353 The :samp:`-f {function}` option causes `gprof` to limit the 1354 call graph to the function `function_name` and its children (and 1355 their children...). More than one ``-f`` option may be given; 1356 only one `function_name` may be indicated with each ``-f`` 1357 option. 1358 1359 1360.. index:: -F (gprof) 1361 1362:samp:`-F {function_name}` 1363 The :samp:`-F {function}` option works like the ``-f`` option, but 1364 only time spent in the function and its children (and their 1365 children...) will be used to determine total-time and 1366 percentages-of-time for the call graph. More than one ``-F`` option 1367 may be given; only one `function_name` may be indicated with each 1368 ``-F`` option. The ``-F`` option overrides the ``-E`` option. 1369 1370 1371.. _Interpretation_of_profiling_results: 1372 1373Interpretation of profiling results 1374^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1375 1376The results of the profiling analysis are represented by two arrays: the 1377'flat profile' and the 'call graph'. Full documentation of those outputs 1378can be found in the GNU Profiler User's Guide. 1379 1380The flat profile shows the time spent in each function of the program, and how 1381many time it has been called. This allows you to locate easily the most 1382time-consuming functions. 1383 1384The call graph shows, for each subprogram, the subprograms that call it, 1385and the subprograms that it calls. It also provides an estimate of the time 1386spent in each of those callers/called subprograms. 1387 1388 1389 1390.. _Improving_Performance: 1391 1392Improving Performance 1393===================== 1394 1395.. index:: Improving performance 1396 1397This section presents several topics related to program performance. 1398It first describes some of the tradeoffs that need to be considered 1399and some of the techniques for making your program run faster. 1400 1401.. only:: PRO or GPL 1402 1403 It then documents the unused subprogram/data elimination feature 1404 and the *gnatelim* tool, 1405 which can reduce the size of program executables. 1406 1407 1408.. only:: FSF 1409 1410 It then documents the unused subprogram/data elimination feature, 1411 which can reduce the size of program executables. 1412 1413 1414.. _Performance_Considerations: 1415 1416Performance Considerations 1417-------------------------- 1418 1419The GNAT system provides a number of options that allow a trade-off 1420between 1421 1422* performance of the generated code 1423 1424* speed of compilation 1425 1426* minimization of dependences and recompilation 1427 1428* the degree of run-time checking. 1429 1430The defaults (if no options are selected) aim at improving the speed 1431of compilation and minimizing dependences, at the expense of performance 1432of the generated code: 1433 1434* no optimization 1435 1436* no inlining of subprogram calls 1437 1438* all run-time checks enabled except overflow and elaboration checks 1439 1440These options are suitable for most program development purposes. This 1441section describes how you can modify these choices, and also provides 1442some guidelines on debugging optimized code. 1443 1444 1445.. _Controlling_Run-Time_Checks: 1446 1447Controlling Run-Time Checks 1448^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1449 1450By default, GNAT generates all run-time checks, except stack overflow 1451checks, and checks for access before elaboration on subprogram 1452calls. The latter are not required in default mode, because all 1453necessary checking is done at compile time. 1454 1455.. index:: -gnatp (gcc) 1456.. index:: -gnato (gcc) 1457 1458The gnat switch, *-gnatp* allows this default to be modified. See 1459:ref:`Run-Time_Checks`. 1460 1461Our experience is that the default is suitable for most development 1462purposes. 1463 1464Elaboration checks are off by default, and also not needed by default, since 1465GNAT uses a static elaboration analysis approach that avoids the need for 1466run-time checking. This manual contains a full chapter discussing the issue 1467of elaboration checks, and if the default is not satisfactory for your use, 1468you should read this chapter. 1469 1470For validity checks, the minimal checks required by the Ada Reference 1471Manual (for case statements and assignments to array elements) are on 1472by default. These can be suppressed by use of the *-gnatVn* switch. 1473Note that in Ada 83, there were no validity checks, so if the Ada 83 mode 1474is acceptable (or when comparing GNAT performance with an Ada 83 compiler), 1475it may be reasonable to routinely use *-gnatVn*. Validity checks 1476are also suppressed entirely if *-gnatp* is used. 1477 1478.. index:: Overflow checks 1479.. index:: Checks, overflow 1480 1481.. index:: Suppress 1482.. index:: Unsuppress 1483.. index:: pragma Suppress 1484.. index:: pragma Unsuppress 1485 1486Note that the setting of the switches controls the default setting of 1487the checks. They may be modified using either `pragma Suppress` (to 1488remove checks) or `pragma Unsuppress` (to add back suppressed 1489checks) in the program source. 1490 1491 1492.. _Use_of_Restrictions: 1493 1494Use of Restrictions 1495^^^^^^^^^^^^^^^^^^^ 1496 1497The use of pragma Restrictions allows you to control which features are 1498permitted in your program. Apart from the obvious point that if you avoid 1499relatively expensive features like finalization (enforceable by the use 1500of pragma Restrictions (No_Finalization), the use of this pragma does not 1501affect the generated code in most cases. 1502 1503One notable exception to this rule is that the possibility of task abort 1504results in some distributed overhead, particularly if finalization or 1505exception handlers are used. The reason is that certain sections of code 1506have to be marked as non-abortable. 1507 1508If you use neither the `abort` statement, nor asynchronous transfer 1509of control (`select ... then abort`), then this distributed overhead 1510is removed, which may have a general positive effect in improving 1511overall performance. Especially code involving frequent use of tasking 1512constructs and controlled types will show much improved performance. 1513The relevant restrictions pragmas are 1514 1515 .. code-block:: ada 1516 1517 pragma Restrictions (No_Abort_Statements); 1518 pragma Restrictions (Max_Asynchronous_Select_Nesting => 0); 1519 1520It is recommended that these restriction pragmas be used if possible. Note 1521that this also means that you can write code without worrying about the 1522possibility of an immediate abort at any point. 1523 1524 1525.. _Optimization_Levels: 1526 1527Optimization Levels 1528^^^^^^^^^^^^^^^^^^^ 1529 1530.. index:: -O (gcc) 1531 1532Without any optimization option, 1533the compiler's goal is to reduce the cost of 1534compilation and to make debugging produce the expected results. 1535Statements are independent: if you stop the program with a breakpoint between 1536statements, you can then assign a new value to any variable or change 1537the program counter to any other statement in the subprogram and get exactly 1538the results you would expect from the source code. 1539 1540Turning on optimization makes the compiler attempt to improve the 1541performance and/or code size at the expense of compilation time and 1542possibly the ability to debug the program. 1543 1544If you use multiple 1545-O options, with or without level numbers, 1546the last such option is the one that is effective. 1547 1548The default is optimization off. This results in the fastest compile 1549times, but GNAT makes absolutely no attempt to optimize, and the 1550generated programs are considerably larger and slower than when 1551optimization is enabled. You can use the 1552*-O* switch (the permitted forms are *-O0*, *-O1* 1553*-O2*, *-O3*, and *-Os*) 1554to *gcc* to control the optimization level: 1555 1556 1557* *-O0* 1558 No optimization (the default); 1559 generates unoptimized code but has 1560 the fastest compilation time. 1561 1562 Note that many other compilers do fairly extensive optimization 1563 even if 'no optimization' is specified. With gcc, it is 1564 very unusual to use -O0 for production if 1565 execution time is of any concern, since -O0 1566 really does mean no optimization at all. This difference between 1567 gcc and other compilers should be kept in mind when doing 1568 performance comparisons. 1569 1570* *-O1* 1571 Moderate optimization; 1572 optimizes reasonably well but does not 1573 degrade compilation time significantly. 1574 1575* *-O2* 1576 Full optimization; 1577 generates highly optimized code and has 1578 the slowest compilation time. 1579 1580* *-O3* 1581 Full optimization as in *-O2*; 1582 also uses more aggressive automatic inlining of subprograms within a unit 1583 (:ref:`Inlining_of_Subprograms`) and attempts to vectorize loops. 1584 1585 1586* *-Os* 1587 Optimize space usage (code and data) of resulting program. 1588 1589Higher optimization levels perform more global transformations on the 1590program and apply more expensive analysis algorithms in order to generate 1591faster and more compact code. The price in compilation time, and the 1592resulting improvement in execution time, 1593both depend on the particular application and the hardware environment. 1594You should experiment to find the best level for your application. 1595 1596Since the precise set of optimizations done at each level will vary from 1597release to release (and sometime from target to target), it is best to think 1598of the optimization settings in general terms. 1599See the *Options That Control Optimization* section in 1600:title:`Using the GNU Compiler Collection (GCC)` 1601for details about 1602the *-O* settings and a number of *-f* options that 1603individually enable or disable specific optimizations. 1604 1605Unlike some other compilation systems, *gcc* has 1606been tested extensively at all optimization levels. There are some bugs 1607which appear only with optimization turned on, but there have also been 1608bugs which show up only in *unoptimized* code. Selecting a lower 1609level of optimization does not improve the reliability of the code 1610generator, which in practice is highly reliable at all optimization 1611levels. 1612 1613Note regarding the use of *-O3*: The use of this optimization level 1614is generally discouraged with GNAT, since it often results in larger 1615executables which may run more slowly. See further discussion of this point 1616in :ref:`Inlining_of_Subprograms`. 1617 1618 1619.. _Debugging_Optimized_Code: 1620 1621Debugging Optimized Code 1622^^^^^^^^^^^^^^^^^^^^^^^^ 1623 1624.. index:: Debugging optimized code 1625.. index:: Optimization and debugging 1626 1627Although it is possible to do a reasonable amount of debugging at 1628nonzero optimization levels, 1629the higher the level the more likely that 1630source-level constructs will have been eliminated by optimization. 1631For example, if a loop is strength-reduced, the loop 1632control variable may be completely eliminated and thus cannot be 1633displayed in the debugger. 1634This can only happen at *-O2* or *-O3*. 1635Explicit temporary variables that you code might be eliminated at 1636level *-O1* or higher. 1637 1638.. index:: -g (gcc) 1639 1640The use of the *-g* switch, 1641which is needed for source-level debugging, 1642affects the size of the program executable on disk, 1643and indeed the debugging information can be quite large. 1644However, it has no effect on the generated code (and thus does not 1645degrade performance) 1646 1647Since the compiler generates debugging tables for a compilation unit before 1648it performs optimizations, the optimizing transformations may invalidate some 1649of the debugging data. You therefore need to anticipate certain 1650anomalous situations that may arise while debugging optimized code. 1651These are the most common cases: 1652 1653* *The 'hopping Program Counter':* Repeated `step` or `next` 1654 commands show 1655 the PC bouncing back and forth in the code. This may result from any of 1656 the following optimizations: 1657 1658 - *Common subexpression elimination:* using a single instance of code for a 1659 quantity that the source computes several times. As a result you 1660 may not be able to stop on what looks like a statement. 1661 1662 - *Invariant code motion:* moving an expression that does not change within a 1663 loop, to the beginning of the loop. 1664 1665 - *Instruction scheduling:* moving instructions so as to 1666 overlap loads and stores (typically) with other code, or in 1667 general to move computations of values closer to their uses. Often 1668 this causes you to pass an assignment statement without the assignment 1669 happening and then later bounce back to the statement when the 1670 value is actually needed. Placing a breakpoint on a line of code 1671 and then stepping over it may, therefore, not always cause all the 1672 expected side-effects. 1673 1674* *The 'big leap':* More commonly known as *cross-jumping*, in which 1675 two identical pieces of code are merged and the program counter suddenly 1676 jumps to a statement that is not supposed to be executed, simply because 1677 it (and the code following) translates to the same thing as the code 1678 that *was* supposed to be executed. This effect is typically seen in 1679 sequences that end in a jump, such as a `goto`, a `return`, or 1680 a `break` in a C `switch` statement. 1681 1682* *The 'roving variable':* The symptom is an unexpected value in a variable. 1683 There are various reasons for this effect: 1684 1685 - In a subprogram prologue, a parameter may not yet have been moved to its 1686 'home'. 1687 1688 - A variable may be dead, and its register re-used. This is 1689 probably the most common cause. 1690 1691 - As mentioned above, the assignment of a value to a variable may 1692 have been moved. 1693 1694 - A variable may be eliminated entirely by value propagation or 1695 other means. In this case, GCC may incorrectly generate debugging 1696 information for the variable 1697 1698 In general, when an unexpected value appears for a local variable or parameter 1699 you should first ascertain if that value was actually computed by 1700 your program, as opposed to being incorrectly reported by the debugger. 1701 Record fields or 1702 array elements in an object designated by an access value 1703 are generally less of a problem, once you have ascertained that the access 1704 value is sensible. 1705 Typically, this means checking variables in the preceding code and in the 1706 calling subprogram to verify that the value observed is explainable from other 1707 values (one must apply the procedure recursively to those 1708 other values); or re-running the code and stopping a little earlier 1709 (perhaps before the call) and stepping to better see how the variable obtained 1710 the value in question; or continuing to step *from* the point of the 1711 strange value to see if code motion had simply moved the variable's 1712 assignments later. 1713 1714In light of such anomalies, a recommended technique is to use *-O0* 1715early in the software development cycle, when extensive debugging capabilities 1716are most needed, and then move to *-O1* and later *-O2* as 1717the debugger becomes less critical. 1718Whether to use the *-g* switch in the release version is 1719a release management issue. 1720Note that if you use *-g* you can then use the *strip* program 1721on the resulting executable, 1722which removes both debugging information and global symbols. 1723 1724 1725.. _Inlining_of_Subprograms: 1726 1727Inlining of Subprograms 1728^^^^^^^^^^^^^^^^^^^^^^^ 1729 1730A call to a subprogram in the current unit is inlined if all the 1731following conditions are met: 1732 1733* The optimization level is at least *-O1*. 1734 1735* The called subprogram is suitable for inlining: It must be small enough 1736 and not contain something that *gcc* cannot support in inlined 1737 subprograms. 1738 1739 .. index:: pragma Inline 1740 .. index:: Inline 1741 1742* Any one of the following applies: `pragma Inline` is applied to the 1743 subprogram and the *-gnatn* switch is specified; the 1744 subprogram is local to the unit and called once from within it; the 1745 subprogram is small and optimization level *-O2* is specified; 1746 optimization level *-O3* is specified. 1747 1748Calls to subprograms in |withed| units are normally not inlined. 1749To achieve actual inlining (that is, replacement of the call by the code 1750in the body of the subprogram), the following conditions must all be true: 1751 1752* The optimization level is at least *-O1*. 1753 1754* The called subprogram is suitable for inlining: It must be small enough 1755 and not contain something that *gcc* cannot support in inlined 1756 subprograms. 1757 1758* The call appears in a body (not in a package spec). 1759 1760* There is a `pragma Inline` for the subprogram. 1761 1762* The *-gnatn* switch is used on the command line. 1763 1764Even if all these conditions are met, it may not be possible for 1765the compiler to inline the call, due to the length of the body, 1766or features in the body that make it impossible for the compiler 1767to do the inlining. 1768 1769Note that specifying the *-gnatn* switch causes additional 1770compilation dependencies. Consider the following: 1771 1772 .. code-block:: ada 1773 1774 package R is 1775 procedure Q; 1776 pragma Inline (Q); 1777 end R; 1778 package body R is 1779 ... 1780 end R; 1781 1782 with R; 1783 procedure Main is 1784 begin 1785 ... 1786 R.Q; 1787 end Main; 1788 1789With the default behavior (no *-gnatn* switch specified), the 1790compilation of the `Main` procedure depends only on its own source, 1791:file:`main.adb`, and the spec of the package in file :file:`r.ads`. This 1792means that editing the body of `R` does not require recompiling 1793`Main`. 1794 1795On the other hand, the call `R.Q` is not inlined under these 1796circumstances. If the *-gnatn* switch is present when `Main` 1797is compiled, the call will be inlined if the body of `Q` is small 1798enough, but now `Main` depends on the body of `R` in 1799:file:`r.adb` as well as on the spec. This means that if this body is edited, 1800the main program must be recompiled. Note that this extra dependency 1801occurs whether or not the call is in fact inlined by *gcc*. 1802 1803The use of front end inlining with *-gnatN* generates similar 1804additional dependencies. 1805 1806.. index:: -fno-inline (gcc) 1807 1808Note: The *-fno-inline* switch overrides all other conditions and ensures that 1809no inlining occurs, unless requested with pragma Inline_Always for gcc 1810back-ends. The extra dependences resulting from *-gnatn* will still be active, 1811even if this switch is used to suppress the resulting inlining actions. 1812 1813.. index:: -fno-inline-functions (gcc) 1814 1815Note: The *-fno-inline-functions* switch can be used to prevent 1816automatic inlining of subprograms if *-O3* is used. 1817 1818.. index:: -fno-inline-small-functions (gcc) 1819 1820Note: The *-fno-inline-small-functions* switch can be used to prevent 1821automatic inlining of small subprograms if *-O2* is used. 1822 1823.. index:: -fno-inline-functions-called-once (gcc) 1824 1825Note: The *-fno-inline-functions-called-once* switch 1826can be used to prevent inlining of subprograms local to the unit 1827and called once from within it if *-O1* is used. 1828 1829Note regarding the use of *-O3*: *-gnatn* is made up of two 1830sub-switches *-gnatn1* and *-gnatn2* that can be directly 1831specified in lieu of it, *-gnatn* being translated into one of them 1832based on the optimization level. With *-O2* or below, *-gnatn* 1833is equivalent to *-gnatn1* which activates pragma `Inline` with 1834moderate inlining across modules. With *-O3*, *-gnatn* is 1835equivalent to *-gnatn2* which activates pragma `Inline` with 1836full inlining across modules. If you have used pragma `Inline` in 1837appropriate cases, then it is usually much better to use *-O2* 1838and *-gnatn* and avoid the use of *-O3* which has the additional 1839effect of inlining subprograms you did not think should be inlined. We have 1840found that the use of *-O3* may slow down the compilation and increase 1841the code size by performing excessive inlining, leading to increased 1842instruction cache pressure from the increased code size and thus minor 1843performance improvements. So the bottom line here is that you should not 1844automatically assume that *-O3* is better than *-O2*, and 1845indeed you should use *-O3* only if tests show that it actually 1846improves performance for your program. 1847 1848.. _Floating_Point_Operations: 1849 1850Floating_Point_Operations 1851^^^^^^^^^^^^^^^^^^^^^^^^^ 1852 1853.. index:: Floating-Point Operations 1854 1855On almost all targets, GNAT maps Float and Long_Float to the 32-bit and 185664-bit standard IEEE floating-point representations, and operations will 1857use standard IEEE arithmetic as provided by the processor. On most, but 1858not all, architectures, the attribute Machine_Overflows is False for these 1859types, meaning that the semantics of overflow is implementation-defined. 1860In the case of GNAT, these semantics correspond to the normal IEEE 1861treatment of infinities and NaN (not a number) values. For example, 18621.0 / 0.0 yields plus infinitiy and 0.0 / 0.0 yields a NaN. By 1863avoiding explicit overflow checks, the performance is greatly improved 1864on many targets. However, if required, floating-point overflow can be 1865enabled by the use of the pragma Check_Float_Overflow. 1866 1867Another consideration that applies specifically to x86 32-bit 1868architectures is which form of floating-point arithmetic is used. 1869By default the operations use the old style x86 floating-point, 1870which implements an 80-bit extended precision form (on these 1871architectures the type Long_Long_Float corresponds to that form). 1872In addition, generation of efficient code in this mode means that 1873the extended precision form will be used for intermediate results. 1874This may be helpful in improving the final precision of a complex 1875expression. However it means that the results obtained on the x86 1876will be different from those on other architectures, and for some 1877algorithms, the extra intermediate precision can be detrimental. 1878 1879In addition to this old-style floating-point, all modern x86 chips 1880implement an alternative floating-point operation model referred 1881to as SSE2. In this model there is no extended form, and furthermore 1882execution performance is significantly enhanced. To force GNAT to use 1883this more modern form, use both of the switches: 1884 1885 -msse2 -mfpmath=sse 1886 1887A unit compiled with these switches will automatically use the more 1888efficient SSE2 instruction set for Float and Long_Float operations. 1889Note that the ABI has the same form for both floating-point models, 1890so it is permissible to mix units compiled with and without these 1891switches. 1892 1893 1894 1895 1896 1897.. _Vectorization_of_loops: 1898 1899Vectorization of loops 1900^^^^^^^^^^^^^^^^^^^^^^ 1901 1902.. index:: Optimization Switches 1903 1904You can take advantage of the auto-vectorizer present in the *gcc* 1905back end to vectorize loops with GNAT. The corresponding command line switch 1906is *-ftree-vectorize* but, as it is enabled by default at *-O3* 1907and other aggressive optimizations helpful for vectorization also are enabled 1908by default at this level, using *-O3* directly is recommended. 1909 1910You also need to make sure that the target architecture features a supported 1911SIMD instruction set. For example, for the x86 architecture, you should at 1912least specify *-msse2* to get significant vectorization (but you don't 1913need to specify it for x86-64 as it is part of the base 64-bit architecture). 1914Similarly, for the PowerPC architecture, you should specify *-maltivec*. 1915 1916The preferred loop form for vectorization is the `for` iteration scheme. 1917Loops with a `while` iteration scheme can also be vectorized if they are 1918very simple, but the vectorizer will quickly give up otherwise. With either 1919iteration scheme, the flow of control must be straight, in particular no 1920`exit` statement may appear in the loop body. The loop may however 1921contain a single nested loop, if it can be vectorized when considered alone: 1922 1923 .. code-block:: ada 1924 1925 A : array (1..4, 1..4) of Long_Float; 1926 S : array (1..4) of Long_Float; 1927 1928 procedure Sum is 1929 begin 1930 for I in A'Range(1) loop 1931 for J in A'Range(2) loop 1932 S (I) := S (I) + A (I, J); 1933 end loop; 1934 end loop; 1935 end Sum; 1936 1937The vectorizable operations depend on the targeted SIMD instruction set, but 1938the adding and some of the multiplying operators are generally supported, as 1939well as the logical operators for modular types. Note that compiling 1940with *-gnatp* might well reveal cases where some checks do thwart 1941vectorization. 1942 1943Type conversions may also prevent vectorization if they involve semantics that 1944are not directly supported by the code generator or the SIMD instruction set. 1945A typical example is direct conversion from floating-point to integer types. 1946The solution in this case is to use the following idiom: 1947 1948 .. code-block:: ada 1949 1950 Integer (S'Truncation (F)) 1951 1952if `S` is the subtype of floating-point object `F`. 1953 1954In most cases, the vectorizable loops are loops that iterate over arrays. 1955All kinds of array types are supported, i.e. constrained array types with 1956static bounds: 1957 1958 .. code-block:: ada 1959 1960 type Array_Type is array (1 .. 4) of Long_Float; 1961 1962constrained array types with dynamic bounds: 1963 1964 1965 .. code-block:: ada 1966 1967 type Array_Type is array (1 .. Q.N) of Long_Float; 1968 1969 type Array_Type is array (Q.K .. 4) of Long_Float; 1970 1971 type Array_Type is array (Q.K .. Q.N) of Long_Float; 1972 1973or unconstrained array types: 1974 1975 .. code-block:: ada 1976 1977 type Array_Type is array (Positive range <>) of Long_Float; 1978 1979The quality of the generated code decreases when the dynamic aspect of the 1980array type increases, the worst code being generated for unconstrained array 1981types. This is so because, the less information the compiler has about the 1982bounds of the array, the more fallback code it needs to generate in order to 1983fix things up at run time. 1984 1985It is possible to specify that a given loop should be subject to vectorization 1986preferably to other optimizations by means of pragma `Loop_Optimize`: 1987 1988 .. code-block:: ada 1989 1990 pragma Loop_Optimize (Vector); 1991 1992placed immediately within the loop will convey the appropriate hint to the 1993compiler for this loop. 1994 1995It is also possible to help the compiler generate better vectorized code 1996for a given loop by asserting that there are no loop-carried dependencies 1997in the loop. Consider for example the procedure: 1998 1999 .. code-block:: ada 2000 2001 type Arr is array (1 .. 4) of Long_Float; 2002 2003 procedure Add (X, Y : not null access Arr; R : not null access Arr) is 2004 begin 2005 for I in Arr'Range loop 2006 R(I) := X(I) + Y(I); 2007 end loop; 2008 end; 2009 2010By default, the compiler cannot unconditionally vectorize the loop because 2011assigning to a component of the array designated by R in one iteration could 2012change the value read from the components of the array designated by X or Y 2013in a later iteration. As a result, the compiler will generate two versions 2014of the loop in the object code, one vectorized and the other not vectorized, 2015as well as a test to select the appropriate version at run time. This can 2016be overcome by another hint: 2017 2018 .. code-block:: ada 2019 2020 pragma Loop_Optimize (Ivdep); 2021 2022placed immediately within the loop will tell the compiler that it can safely 2023omit the non-vectorized version of the loop as well as the run-time test. 2024 2025 2026.. _Other_Optimization_Switches: 2027 2028Other Optimization Switches 2029^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2030 2031.. index:: Optimization Switches 2032 2033Since `GNAT` uses the *gcc* back end, all the specialized 2034*gcc* optimization switches are potentially usable. These switches 2035have not been extensively tested with GNAT but can generally be expected 2036to work. Examples of switches in this category are *-funroll-loops* 2037and the various target-specific *-m* options (in particular, it has 2038been observed that *-march=xxx* can significantly improve performance 2039on appropriate machines). For full details of these switches, see 2040the `Submodel Options` section in the `Hardware Models and Configurations` 2041chapter of :title:`Using the GNU Compiler Collection (GCC)`. 2042 2043 2044.. _Optimization_and_Strict_Aliasing: 2045 2046Optimization and Strict Aliasing 2047^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2048 2049.. index:: Aliasing 2050.. index:: Strict Aliasing 2051.. index:: No_Strict_Aliasing 2052 2053The strong typing capabilities of Ada allow an optimizer to generate 2054efficient code in situations where other languages would be forced to 2055make worst case assumptions preventing such optimizations. Consider 2056the following example: 2057 2058 .. code-block:: ada 2059 2060 procedure R is 2061 type Int1 is new Integer; 2062 type Int2 is new Integer; 2063 type Int1A is access Int1; 2064 type Int2A is access Int2; 2065 Int1V : Int1A; 2066 Int2V : Int2A; 2067 ... 2068 2069 begin 2070 ... 2071 for J in Data'Range loop 2072 if Data (J) = Int1V.all then 2073 Int2V.all := Int2V.all + 1; 2074 end if; 2075 end loop; 2076 ... 2077 end R; 2078 2079In this example, since the variable `Int1V` can only access objects 2080of type `Int1`, and `Int2V` can only access objects of type 2081`Int2`, there is no possibility that the assignment to 2082`Int2V.all` affects the value of `Int1V.all`. This means that 2083the compiler optimizer can "know" that the value `Int1V.all` is constant 2084for all iterations of the loop and avoid the extra memory reference 2085required to dereference it each time through the loop. 2086 2087This kind of optimization, called strict aliasing analysis, is 2088triggered by specifying an optimization level of *-O2* or 2089higher or *-Os* and allows `GNAT` to generate more efficient code 2090when access values are involved. 2091 2092However, although this optimization is always correct in terms of 2093the formal semantics of the Ada Reference Manual, difficulties can 2094arise if features like `Unchecked_Conversion` are used to break 2095the typing system. Consider the following complete program example: 2096 2097 .. code-block:: ada 2098 2099 package p1 is 2100 type int1 is new integer; 2101 type int2 is new integer; 2102 type a1 is access int1; 2103 type a2 is access int2; 2104 end p1; 2105 2106 with p1; use p1; 2107 package p2 is 2108 function to_a2 (Input : a1) return a2; 2109 end p2; 2110 2111 with Unchecked_Conversion; 2112 package body p2 is 2113 function to_a2 (Input : a1) return a2 is 2114 function to_a2u is 2115 new Unchecked_Conversion (a1, a2); 2116 begin 2117 return to_a2u (Input); 2118 end to_a2; 2119 end p2; 2120 2121 with p2; use p2; 2122 with p1; use p1; 2123 with Text_IO; use Text_IO; 2124 procedure m is 2125 v1 : a1 := new int1; 2126 v2 : a2 := to_a2 (v1); 2127 begin 2128 v1.all := 1; 2129 v2.all := 0; 2130 put_line (int1'image (v1.all)); 2131 end; 2132 2133This program prints out 0 in *-O0* or *-O1* 2134mode, but it prints out 1 in *-O2* mode. That's 2135because in strict aliasing mode, the compiler can and 2136does assume that the assignment to `v2.all` could not 2137affect the value of `v1.all`, since different types 2138are involved. 2139 2140This behavior is not a case of non-conformance with the standard, since 2141the Ada RM specifies that an unchecked conversion where the resulting 2142bit pattern is not a correct value of the target type can result in an 2143abnormal value and attempting to reference an abnormal value makes the 2144execution of a program erroneous. That's the case here since the result 2145does not point to an object of type `int2`. This means that the 2146effect is entirely unpredictable. 2147 2148However, although that explanation may satisfy a language 2149lawyer, in practice an applications programmer expects an 2150unchecked conversion involving pointers to create true 2151aliases and the behavior of printing 1 seems plain wrong. 2152In this case, the strict aliasing optimization is unwelcome. 2153 2154Indeed the compiler recognizes this possibility, and the 2155unchecked conversion generates a warning: 2156 2157 :: 2158 2159 p2.adb:5:07: warning: possible aliasing problem with type "a2" 2160 p2.adb:5:07: warning: use -fno-strict-aliasing switch for references 2161 p2.adb:5:07: warning: or use "pragma No_Strict_Aliasing (a2);" 2162 2163Unfortunately the problem is recognized when compiling the body of 2164package `p2`, but the actual "bad" code is generated while 2165compiling the body of `m` and this latter compilation does not see 2166the suspicious `Unchecked_Conversion`. 2167 2168As implied by the warning message, there are approaches you can use to 2169avoid the unwanted strict aliasing optimization in a case like this. 2170 2171One possibility is to simply avoid the use of *-O2*, but 2172that is a bit drastic, since it throws away a number of useful 2173optimizations that do not involve strict aliasing assumptions. 2174 2175A less drastic approach is to compile the program using the 2176option *-fno-strict-aliasing*. Actually it is only the 2177unit containing the dereferencing of the suspicious pointer 2178that needs to be compiled. So in this case, if we compile 2179unit `m` with this switch, then we get the expected 2180value of zero printed. Analyzing which units might need 2181the switch can be painful, so a more reasonable approach 2182is to compile the entire program with options *-O2* 2183and *-fno-strict-aliasing*. If the performance is 2184satisfactory with this combination of options, then the 2185advantage is that the entire issue of possible "wrong" 2186optimization due to strict aliasing is avoided. 2187 2188To avoid the use of compiler switches, the configuration 2189pragma `No_Strict_Aliasing` with no parameters may be 2190used to specify that for all access types, the strict 2191aliasing optimization should be suppressed. 2192 2193However, these approaches are still overkill, in that they causes 2194all manipulations of all access values to be deoptimized. A more 2195refined approach is to concentrate attention on the specific 2196access type identified as problematic. 2197 2198First, if a careful analysis of uses of the pointer shows 2199that there are no possible problematic references, then 2200the warning can be suppressed by bracketing the 2201instantiation of `Unchecked_Conversion` to turn 2202the warning off: 2203 2204 .. code-block:: ada 2205 2206 pragma Warnings (Off); 2207 function to_a2u is 2208 new Unchecked_Conversion (a1, a2); 2209 pragma Warnings (On); 2210 2211Of course that approach is not appropriate for this particular 2212example, since indeed there is a problematic reference. In this 2213case we can take one of two other approaches. 2214 2215The first possibility is to move the instantiation of unchecked 2216conversion to the unit in which the type is declared. In 2217this example, we would move the instantiation of 2218`Unchecked_Conversion` from the body of package 2219`p2` to the spec of package `p1`. Now the 2220warning disappears. That's because any use of the 2221access type knows there is a suspicious unchecked 2222conversion, and the strict aliasing optimization 2223is automatically suppressed for the type. 2224 2225If it is not practical to move the unchecked conversion to the same unit 2226in which the destination access type is declared (perhaps because the 2227source type is not visible in that unit), you may use pragma 2228`No_Strict_Aliasing` for the type. This pragma must occur in the 2229same declarative sequence as the declaration of the access type: 2230 2231 .. code-block:: ada 2232 2233 type a2 is access int2; 2234 pragma No_Strict_Aliasing (a2); 2235 2236Here again, the compiler now knows that the strict aliasing optimization 2237should be suppressed for any reference to type `a2` and the 2238expected behavior is obtained. 2239 2240Finally, note that although the compiler can generate warnings for 2241simple cases of unchecked conversions, there are tricker and more 2242indirect ways of creating type incorrect aliases which the compiler 2243cannot detect. Examples are the use of address overlays and unchecked 2244conversions involving composite types containing access types as 2245components. In such cases, no warnings are generated, but there can 2246still be aliasing problems. One safe coding practice is to forbid the 2247use of address clauses for type overlaying, and to allow unchecked 2248conversion only for primitive types. This is not really a significant 2249restriction since any possible desired effect can be achieved by 2250unchecked conversion of access values. 2251 2252The aliasing analysis done in strict aliasing mode can certainly 2253have significant benefits. We have seen cases of large scale 2254application code where the time is increased by up to 5% by turning 2255this optimization off. If you have code that includes significant 2256usage of unchecked conversion, you might want to just stick with 2257*-O1* and avoid the entire issue. If you get adequate 2258performance at this level of optimization level, that's probably 2259the safest approach. If tests show that you really need higher 2260levels of optimization, then you can experiment with *-O2* 2261and *-O2 -fno-strict-aliasing* to see how much effect this 2262has on size and speed of the code. If you really need to use 2263*-O2* with strict aliasing in effect, then you should 2264review any uses of unchecked conversion of access types, 2265particularly if you are getting the warnings described above. 2266 2267 2268.. _Aliased_Variables_and_Optimization: 2269 2270Aliased Variables and Optimization 2271^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2272 2273.. index:: Aliasing 2274 2275There are scenarios in which programs may 2276use low level techniques to modify variables 2277that otherwise might be considered to be unassigned. For example, 2278a variable can be passed to a procedure by reference, which takes 2279the address of the parameter and uses the address to modify the 2280variable's value, even though it is passed as an IN parameter. 2281Consider the following example: 2282 2283 .. code-block:: ada 2284 2285 procedure P is 2286 Max_Length : constant Natural := 16; 2287 type Char_Ptr is access all Character; 2288 2289 procedure Get_String(Buffer: Char_Ptr; Size : Integer); 2290 pragma Import (C, Get_String, "get_string"); 2291 2292 Name : aliased String (1 .. Max_Length) := (others => ' '); 2293 Temp : Char_Ptr; 2294 2295 function Addr (S : String) return Char_Ptr is 2296 function To_Char_Ptr is 2297 new Ada.Unchecked_Conversion (System.Address, Char_Ptr); 2298 begin 2299 return To_Char_Ptr (S (S'First)'Address); 2300 end; 2301 2302 begin 2303 Temp := Addr (Name); 2304 Get_String (Temp, Max_Length); 2305 end; 2306 2307where Get_String is a C function that uses the address in Temp to 2308modify the variable `Name`. This code is dubious, and arguably 2309erroneous, and the compiler would be entitled to assume that 2310`Name` is never modified, and generate code accordingly. 2311 2312However, in practice, this would cause some existing code that 2313seems to work with no optimization to start failing at high 2314levels of optimzization. 2315 2316What the compiler does for such cases is to assume that marking 2317a variable as aliased indicates that some "funny business" may 2318be going on. The optimizer recognizes the aliased keyword and 2319inhibits optimizations that assume the value cannot be assigned. 2320This means that the above example will in fact "work" reliably, 2321that is, it will produce the expected results. 2322 2323 2324.. _Atomic_Variables_and_Optimization: 2325 2326Atomic Variables and Optimization 2327^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2328 2329.. index:: Atomic 2330 2331There are two considerations with regard to performance when 2332atomic variables are used. 2333 2334First, the RM only guarantees that access to atomic variables 2335be atomic, it has nothing to say about how this is achieved, 2336though there is a strong implication that this should not be 2337achieved by explicit locking code. Indeed GNAT will never 2338generate any locking code for atomic variable access (it will 2339simply reject any attempt to make a variable or type atomic 2340if the atomic access cannot be achieved without such locking code). 2341 2342That being said, it is important to understand that you cannot 2343assume that the entire variable will always be accessed. Consider 2344this example: 2345 2346 .. code-block:: ada 2347 2348 type R is record 2349 A,B,C,D : Character; 2350 end record; 2351 for R'Size use 32; 2352 for R'Alignment use 4; 2353 2354 RV : R; 2355 pragma Atomic (RV); 2356 X : Character; 2357 ... 2358 X := RV.B; 2359 2360You cannot assume that the reference to `RV.B` 2361will read the entire 32-bit 2362variable with a single load instruction. It is perfectly legitimate if 2363the hardware allows it to do a byte read of just the B field. This read 2364is still atomic, which is all the RM requires. GNAT can and does take 2365advantage of this, depending on the architecture and optimization level. 2366Any assumption to the contrary is non-portable and risky. Even if you 2367examine the assembly language and see a full 32-bit load, this might 2368change in a future version of the compiler. 2369 2370If your application requires that all accesses to `RV` in this 2371example be full 32-bit loads, you need to make a copy for the access 2372as in: 2373 2374 .. code-block:: ada 2375 2376 declare 2377 RV_Copy : constant R := RV; 2378 begin 2379 X := RV_Copy.B; 2380 end; 2381 2382Now the reference to RV must read the whole variable. 2383Actually one can imagine some compiler which figures 2384out that the whole copy is not required (because only 2385the B field is actually accessed), but GNAT 2386certainly won't do that, and we don't know of any 2387compiler that would not handle this right, and the 2388above code will in practice work portably across 2389all architectures (that permit the Atomic declaration). 2390 2391The second issue with atomic variables has to do with 2392the possible requirement of generating synchronization 2393code. For more details on this, consult the sections on 2394the pragmas Enable/Disable_Atomic_Synchronization in the 2395GNAT Reference Manual. If performance is critical, and 2396such synchronization code is not required, it may be 2397useful to disable it. 2398 2399 2400.. _Passive_Task_Optimization: 2401 2402Passive Task Optimization 2403^^^^^^^^^^^^^^^^^^^^^^^^^ 2404 2405.. index:: Passive Task 2406 2407A passive task is one which is sufficiently simple that 2408in theory a compiler could recognize it an implement it 2409efficiently without creating a new thread. The original design 2410of Ada 83 had in mind this kind of passive task optimization, but 2411only a few Ada 83 compilers attempted it. The problem was that 2412it was difficult to determine the exact conditions under which 2413the optimization was possible. The result is a very fragile 2414optimization where a very minor change in the program can 2415suddenly silently make a task non-optimizable. 2416 2417With the revisiting of this issue in Ada 95, there was general 2418agreement that this approach was fundamentally flawed, and the 2419notion of protected types was introduced. When using protected 2420types, the restrictions are well defined, and you KNOW that the 2421operations will be optimized, and furthermore this optimized 2422performance is fully portable. 2423 2424Although it would theoretically be possible for GNAT to attempt to 2425do this optimization, but it really doesn't make sense in the 2426context of Ada 95, and none of the Ada 95 compilers implement 2427this optimization as far as we know. In particular GNAT never 2428attempts to perform this optimization. 2429 2430In any new Ada 95 code that is written, you should always 2431use protected types in place of tasks that might be able to 2432be optimized in this manner. 2433Of course this does not help if you have legacy Ada 83 code 2434that depends on this optimization, but it is unusual to encounter 2435a case where the performance gains from this optimization 2436are significant. 2437 2438Your program should work correctly without this optimization. If 2439you have performance problems, then the most practical 2440approach is to figure out exactly where these performance problems 2441arise, and update those particular tasks to be protected types. Note 2442that typically clients of the tasks who call entries, will not have 2443to be modified, only the task definition itself. 2444 2445 2446.. _Text_IO_Suggestions: 2447 2448`Text_IO` Suggestions 2449--------------------- 2450 2451.. index:: Text_IO and performance 2452 2453The `Ada.Text_IO` package has fairly high overheads due in part to 2454the requirement of maintaining page and line counts. If performance 2455is critical, a recommendation is to use `Stream_IO` instead of 2456`Text_IO` for volume output, since this package has less overhead. 2457 2458If `Text_IO` must be used, note that by default output to the standard 2459output and standard error files is unbuffered (this provides better 2460behavior when output statements are used for debugging, or if the 2461progress of a program is observed by tracking the output, e.g. by 2462using the Unix *tail -f* command to watch redirected output. 2463 2464If you are generating large volumes of output with `Text_IO` and 2465performance is an important factor, use a designated file instead 2466of the standard output file, or change the standard output file to 2467be buffered using `Interfaces.C_Streams.setvbuf`. 2468 2469 2470.. _Reducing_Size_of_Executables_with_Unused_Subprogram/Data_Elimination: 2471 2472Reducing Size of Executables with Unused Subprogram/Data Elimination 2473-------------------------------------------------------------------- 2474 2475.. index:: Uunused subprogram/data elimination 2476 2477This section describes how you can eliminate unused subprograms and data from 2478your executable just by setting options at compilation time. 2479 2480.. _About_unused_subprogram/data_elimination: 2481 2482About unused subprogram/data elimination 2483^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2484 2485By default, an executable contains all code and data of its composing objects 2486(directly linked or coming from statically linked libraries), even data or code 2487never used by this executable. 2488 2489This feature will allow you to eliminate such unused code from your 2490executable, making it smaller (in disk and in memory). 2491 2492This functionality is available on all Linux platforms except for the IA-64 2493architecture and on all cross platforms using the ELF binary file format. 2494In both cases GNU binutils version 2.16 or later are required to enable it. 2495 2496.. _Compilation_options: 2497 2498Compilation options 2499^^^^^^^^^^^^^^^^^^^ 2500 2501The operation of eliminating the unused code and data from the final executable 2502is directly performed by the linker. 2503 2504.. index:: -ffunction-sections (gcc) 2505.. index:: -fdata-sections (gcc) 2506 2507In order to do this, it has to work with objects compiled with the 2508following options: 2509*-ffunction-sections* *-fdata-sections*. 2510 2511These options are usable with C and Ada files. 2512They will place respectively each 2513function or data in a separate section in the resulting object file. 2514 2515Once the objects and static libraries are created with these options, the 2516linker can perform the dead code elimination. You can do this by setting 2517the *-Wl,--gc-sections* option to gcc command or in the 2518*-largs* section of *gnatmake*. This will perform a 2519garbage collection of code and data never referenced. 2520 2521If the linker performs a partial link (*-r* linker option), then you 2522will need to provide the entry point using the *-e* / *--entry* 2523linker option. 2524 2525Note that objects compiled without the *-ffunction-sections* and 2526*-fdata-sections* options can still be linked with the executable. 2527However, no dead code elimination will be performed on those objects (they will 2528be linked as is). 2529 2530The GNAT static library is now compiled with -ffunction-sections and 2531-fdata-sections on some platforms. This allows you to eliminate the unused code 2532and data of the GNAT library from your executable. 2533 2534 2535.. _Example_of_unused_subprogram/data_elimination: 2536 2537Example of unused subprogram/data elimination 2538^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2539 2540Here is a simple example: 2541 2542 .. code-block:: ada 2543 2544 with Aux; 2545 2546 procedure Test is 2547 begin 2548 Aux.Used (10); 2549 end Test; 2550 2551 package Aux is 2552 Used_Data : Integer; 2553 Unused_Data : Integer; 2554 2555 procedure Used (Data : Integer); 2556 procedure Unused (Data : Integer); 2557 end Aux; 2558 2559 package body Aux is 2560 procedure Used (Data : Integer) is 2561 begin 2562 Used_Data := Data; 2563 end Used; 2564 2565 procedure Unused (Data : Integer) is 2566 begin 2567 Unused_Data := Data; 2568 end Unused; 2569 end Aux; 2570 2571`Unused` and `Unused_Data` are never referenced in this code 2572excerpt, and hence they may be safely removed from the final executable. 2573 2574 :: 2575 2576 $ gnatmake test 2577 2578 $ nm test | grep used 2579 020015f0 T aux__unused 2580 02005d88 B aux__unused_data 2581 020015cc T aux__used 2582 02005d84 B aux__used_data 2583 2584 $ gnatmake test -cargs -fdata-sections -ffunction-sections \\ 2585 -largs -Wl,--gc-sections 2586 2587 $ nm test | grep used 2588 02005350 T aux__used 2589 0201ffe0 B aux__used_data 2590 2591It can be observed that the procedure `Unused` and the object 2592`Unused_Data` are removed by the linker when using the 2593appropriate options. 2594 2595.. only:: PRO or GPL 2596 2597 .. _Reducing_Size_of_Ada_Executables_with_gnatelim: 2598 2599 Reducing Size of Ada Executables with `gnatelim` 2600 ------------------------------------------------ 2601 2602 .. index:: gnatelim 2603 2604 This section describes *gnatelim*, a tool which detects unused 2605 subprograms and helps the compiler to create a smaller executable for your 2606 program. 2607 2608 .. _About_gnatelim: 2609 2610 About `gnatelim` 2611 ^^^^^^^^^^^^^^^^ 2612 2613 When a program shares a set of Ada 2614 packages with other programs, it may happen that this program uses 2615 only a fraction of the subprograms defined in these packages. The code 2616 created for these unused subprograms increases the size of the executable. 2617 2618 `gnatelim` tracks unused subprograms in an Ada program and 2619 outputs a list of GNAT-specific pragmas `Eliminate` marking all the 2620 subprograms that are declared but never called. By placing the list of 2621 `Eliminate` pragmas in the GNAT configuration file :file:`gnat.adc` and 2622 recompiling your program, you may decrease the size of its executable, 2623 because the compiler will not generate the code for 'eliminated' subprograms. 2624 See `Pragma_Eliminate` in the :title:`GNAT_Reference_Manual` for more 2625 information about this pragma. 2626 2627 `gnatelim` needs as its input data the name of the main subprogram. 2628 2629 If a set of source files is specified as `gnatelim` arguments, it 2630 treats these files as a complete set of sources making up a program to 2631 analyse, and analyses only these sources. 2632 2633 After a full successful build of the main subprogram `gnatelim` can be 2634 called without specifying sources to analyse, in this case it computes 2635 the source closure of the main unit from the :file:`ALI` files. 2636 2637 If the set of sources to be processed by `gnatelim` contains sources with 2638 preprocessing directives 2639 then the needed options should be provided to run preprocessor as a part of 2640 the *gnatelim* call, and the generated set of pragmas `Eliminate` 2641 will correspond to preprocessed sources. 2642 2643 The following command will create the set of :file:`ALI` files needed for 2644 `gnatelim`: 2645 2646 :: 2647 2648 $ gnatmake -c Main_Prog 2649 2650 Note that `gnatelim` does not need object files. 2651 2652 2653 .. _Running_gnatelim: 2654 2655 Running `gnatelim` 2656 ^^^^^^^^^^^^^^^^^^ 2657 2658 `gnatelim` has the following command-line interface: 2659 2660 2661 :: 2662 2663 $ gnatelim [`switches`] -main=`main_unit_name` {`filename`} [-cargs `gcc_switches`] 2664 2665 `main_unit_name` should be a name of a source file that contains the main 2666 subprogram of a program (partition). 2667 2668 Each `filename` is the name (including the extension) of a source 2669 file to process. 'Wildcards' are allowed, and 2670 the file name may contain path information. 2671 2672 `gcc_switches` is a list of switches for 2673 *gcc*. They will be passed on to all compiler invocations made by 2674 *gnatelim* to generate the ASIS trees. Here you can provide 2675 *-I* switches to form the source search path, 2676 use the *-gnatec* switch to set the configuration file, 2677 use the *-gnat05* switch if sources should be compiled in 2678 Ada 2005 mode etc. 2679 2680 `gnatelim` has the following switches: 2681 2682 2683 .. index:: --version (gnatelim) 2684 2685 :samp:`--version` 2686 Display Copyright and version, then exit disregarding all other options. 2687 2688 2689 .. index:: --help (gnatelim) 2690 2691 :samp:`--help` 2692 Display usage, then exit disregarding all other options. 2693 2694 2695 .. index:: -P (gnatelim) 2696 2697 :samp:`-P {file}` 2698 Indicates the name of the project file that describes the set of sources 2699 to be processed. 2700 2701 2702 .. index:: -X (gnatelim) 2703 2704 :samp:`-X{name}={value}` 2705 Indicates that external variable `name` in the argument project 2706 has the value `value`. Has no effect if no project is specified as 2707 tool argument. 2708 2709 2710 .. index:: --RTS (gnatelim) 2711 2712 :samp:`--RTS={rts-path}` 2713 Specifies the default location of the runtime library. Same meaning as the 2714 equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`). 2715 2716 2717 .. index:: -files (gnatelim) 2718 2719 :samp:`-files={filename}` 2720 Take the argument source files from the specified file. This file should be an 2721 ordinary text file containing file names separated by spaces or 2722 line breaks. You can use this switch more than once in the same call to 2723 *gnatelim*. You also can combine this switch with 2724 an explicit list of files. 2725 2726 2727 .. index:: -log (gnatelim) 2728 2729 :samp:`-log` 2730 Duplicate all the output sent to :file:`stderr` into a log file. The log file 2731 is named :file:`gnatelim.log` and is located in the current directory. 2732 2733 .. index:: --no-elim-dispatch (gnatelim) 2734 2735 :samp:`--no-elim-dispatch` 2736 Do not generate pragmas for dispatching operations. 2737 2738 2739 .. index:: --ignore (gnatelim) 2740 2741 :samp:`--ignore={filename}` 2742 Do not generate pragmas for subprograms declared in the sources 2743 listed in a specified file 2744 2745 .. index:: -o (gnatelim) 2746 2747 2748 :samp:`-o={report_file}` 2749 Put *gnatelim* output into a specified file. If this file already exists, 2750 it is overridden. If this switch is not used, *gnatelim* outputs its results 2751 into :file:`stderr` 2752 2753 2754 .. index:: -j (gnatelim) 2755 2756 :samp:`-j{n}` 2757 Use `n` processes to carry out the tree creations (internal representations 2758 of the argument sources). On a multiprocessor machine this speeds up processing 2759 of big sets of argument sources. If `n` is 0, then the maximum number of 2760 parallel tree creations is the number of core processors on the platform. 2761 2762 2763 .. index:: -q (gnatelim) 2764 2765 :samp:`-q` 2766 Quiet mode: by default `gnatelim` outputs to the standard error 2767 stream the number of program units left to be processed. This option turns 2768 this trace off. 2769 2770 .. index:: -t (gnatelim) 2771 2772 2773 :samp:`-t` 2774 Print out execution time. 2775 2776 2777 .. index:: -v (gnatelim) 2778 2779 :samp:`-v` 2780 Verbose mode: `gnatelim` version information is printed as Ada 2781 comments to the standard output stream. Also, in addition to the number of 2782 program units left `gnatelim` will output the name of the current unit 2783 being processed. 2784 2785 2786 .. index:: -wq (gnatelim) 2787 2788 :samp:`-wq` 2789 Quiet warning mode - some warnings are suppressed. In particular warnings that 2790 indicate that the analysed set of sources is incomplete to make up a 2791 partition and that some subprogram bodies are missing are not generated. 2792 2793 Note: to invoke *gnatelim* with a project file, use the `gnat` 2794 driver (see :ref:`The_GNAT_Driver_and_Project_Files`). 2795 2796 2797 .. _Processing_Precompiled_Libraries: 2798 2799 Processing Precompiled Libraries 2800 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2801 2802 If some program uses a precompiled Ada library, it can be processed by 2803 `gnatelim` in a usual way. `gnatelim` will newer generate an 2804 Eliminate pragma for a subprogram if the body of this subprogram has not 2805 been analysed, this is a typical case for subprograms from precompiled 2806 libraries. Switch *-wq* may be used to suppress 2807 warnings about missing source files and non-analyzed subprogram bodies 2808 that can be generated when processing precompiled Ada libraries. 2809 2810 2811 .. _Correcting_the_List_of_Eliminate_Pragmas: 2812 2813 Correcting the List of Eliminate Pragmas 2814 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2815 2816 In some rare cases `gnatelim` may try to eliminate 2817 subprograms that are actually called in the program. In this case, the 2818 compiler will generate an error message of the form: 2819 2820 :: 2821 2822 main.adb:4:08: cannot reference subprogram "P" eliminated at elim.out:5 2823 2824 You will need to manually remove the wrong `Eliminate` pragmas from 2825 the configuration file indicated in the error message. You should recompile 2826 your program from scratch after that, because you need a consistent 2827 configuration file(s) during the entire compilation. 2828 2829 2830 .. _Making_Your_Executables_Smaller: 2831 2832 Making Your Executables Smaller 2833 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2834 2835 In order to get a smaller executable for your program you now have to 2836 recompile the program completely with the configuration file containing 2837 pragmas Eliminate generated by gnatelim. If these pragmas are placed in 2838 :file:`gnat.adc` file located in your current directory, just do: 2839 2840 :: 2841 2842 $ gnatmake -f main_prog 2843 2844 (Use the *-f* option for *gnatmake* to 2845 recompile everything 2846 with the set of pragmas `Eliminate` that you have obtained with 2847 *gnatelim*). 2848 2849 Be aware that the set of `Eliminate` pragmas is specific to each 2850 program. It is not recommended to merge sets of `Eliminate` 2851 pragmas created for different programs in one configuration file. 2852 2853 2854 .. _Summary_of_the_gnatelim_Usage_Cycle: 2855 2856 Summary of the `gnatelim` Usage Cycle 2857 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2858 2859 Here is a quick summary of the steps to be taken in order to reduce 2860 the size of your executables with `gnatelim`. You may use 2861 other GNAT options to control the optimization level, 2862 to produce the debugging information, to set search path, etc. 2863 2864 * Create a complete set of :file:`ALI` files (if the program has not been 2865 built already) 2866 2867 :: 2868 2869 $ gnatmake -c main_prog 2870 2871 * Generate a list of `Eliminate` pragmas in default configuration file 2872 :file:`gnat.adc` in the current directory 2873 2874 :: 2875 2876 $ gnatelim main_prog >[>] gnat.adc 2877 2878 * Recompile the application 2879 2880 :: 2881 2882 $ gnatmake -f main_prog 2883 2884 2885 2886.. index:: Overflow checks 2887.. index:: Checks (overflow) 2888 2889.. _Overflow_Check_Handling_in_GNAT: 2890 2891Overflow Check Handling in GNAT 2892=============================== 2893 2894This section explains how to control the handling of overflow checks. 2895 2896.. _Background: 2897 2898Background 2899---------- 2900 2901Overflow checks are checks that the compiler may make to ensure 2902that intermediate results are not out of range. For example: 2903 2904 .. code-block:: ada 2905 2906 A : Integer; 2907 ... 2908 A := A + 1; 2909 2910If `A` has the value `Integer'Last`, then the addition may cause 2911overflow since the result is out of range of the type `Integer`. 2912In this case `Constraint_Error` will be raised if checks are 2913enabled. 2914 2915A trickier situation arises in examples like the following: 2916 2917 .. code-block:: ada 2918 2919 A, C : Integer; 2920 ... 2921 A := (A + 1) + C; 2922 2923where `A` is `Integer'Last` and `C` is `-1`. 2924Now the final result of the expression on the right hand side is 2925`Integer'Last` which is in range, but the question arises whether the 2926intermediate addition of `(A + 1)` raises an overflow error. 2927 2928The (perhaps surprising) answer is that the Ada language 2929definition does not answer this question. Instead it leaves 2930it up to the implementation to do one of two things if overflow 2931checks are enabled. 2932 2933* raise an exception (`Constraint_Error`), or 2934 2935* yield the correct mathematical result which is then used in 2936 subsequent operations. 2937 2938If the compiler chooses the first approach, then the assignment of this 2939example will indeed raise `Constraint_Error` if overflow checking is 2940enabled, or result in erroneous execution if overflow checks are suppressed. 2941 2942But if the compiler 2943chooses the second approach, then it can perform both additions yielding 2944the correct mathematical result, which is in range, so no exception 2945will be raised, and the right result is obtained, regardless of whether 2946overflow checks are suppressed. 2947 2948Note that in the first example an 2949exception will be raised in either case, since if the compiler 2950gives the correct mathematical result for the addition, it will 2951be out of range of the target type of the assignment, and thus 2952fails the range check. 2953 2954This lack of specified behavior in the handling of overflow for 2955intermediate results is a source of non-portability, and can thus 2956be problematic when programs are ported. Most typically this arises 2957in a situation where the original compiler did not raise an exception, 2958and then the application is moved to a compiler where the check is 2959performed on the intermediate result and an unexpected exception is 2960raised. 2961 2962Furthermore, when using Ada 2012's preconditions and other 2963assertion forms, another issue arises. Consider: 2964 2965 .. code-block:: ada 2966 2967 procedure P (A, B : Integer) with 2968 Pre => A + B <= Integer'Last; 2969 2970One often wants to regard arithmetic in a context like this from 2971a mathematical point of view. So for example, if the two actual parameters 2972for a call to `P` are both `Integer'Last`, then 2973the precondition should be regarded as False. If we are executing 2974in a mode with run-time checks enabled for preconditions, then we would 2975like this precondition to fail, rather than raising an exception 2976because of the intermediate overflow. 2977 2978However, the language definition leaves the specification of 2979whether the above condition fails (raising `Assert_Error`) or 2980causes an intermediate overflow (raising `Constraint_Error`) 2981up to the implementation. 2982 2983The situation is worse in a case such as the following: 2984 2985 .. code-block:: ada 2986 2987 procedure Q (A, B, C : Integer) with 2988 Pre => A + B + C <= Integer'Last; 2989 2990Consider the call 2991 2992 .. code-block:: ada 2993 2994 Q (A => Integer'Last, B => 1, C => -1); 2995 2996From a mathematical point of view the precondition 2997is True, but at run time we may (but are not guaranteed to) get an 2998exception raised because of the intermediate overflow (and we really 2999would prefer this precondition to be considered True at run time). 3000 3001 3002.. _Management_of_Overflows_in_GNAT: 3003 3004Management of Overflows in GNAT 3005------------------------------- 3006 3007To deal with the portability issue, and with the problem of 3008mathematical versus run-time interpretation of the expressions in 3009assertions, GNAT provides comprehensive control over the handling 3010of intermediate overflow. GNAT can operate in three modes, and 3011furthemore, permits separate selection of operating modes for 3012the expressions within assertions (here the term 'assertions' 3013is used in the technical sense, which includes preconditions and so forth) 3014and for expressions appearing outside assertions. 3015 3016The three modes are: 3017 3018* *Use base type for intermediate operations* (`STRICT`) 3019 3020 In this mode, all intermediate results for predefined arithmetic 3021 operators are computed using the base type, and the result must 3022 be in range of the base type. If this is not the 3023 case then either an exception is raised (if overflow checks are 3024 enabled) or the execution is erroneous (if overflow checks are suppressed). 3025 This is the normal default mode. 3026 3027* *Most intermediate overflows avoided* (`MINIMIZED`) 3028 3029 In this mode, the compiler attempts to avoid intermediate overflows by 3030 using a larger integer type, typically `Long_Long_Integer`, 3031 as the type in which arithmetic is 3032 performed for predefined arithmetic operators. This may be slightly more 3033 expensive at 3034 run time (compared to suppressing intermediate overflow checks), though 3035 the cost is negligible on modern 64-bit machines. For the examples given 3036 earlier, no intermediate overflows would have resulted in exceptions, 3037 since the intermediate results are all in the range of 3038 `Long_Long_Integer` (typically 64-bits on nearly all implementations 3039 of GNAT). In addition, if checks are enabled, this reduces the number of 3040 checks that must be made, so this choice may actually result in an 3041 improvement in space and time behavior. 3042 3043 However, there are cases where `Long_Long_Integer` is not large 3044 enough, consider the following example: 3045 3046 .. code-block:: ada 3047 3048 procedure R (A, B, C, D : Integer) with 3049 Pre => (A**2 * B**2) / (C**2 * D**2) <= 10; 3050 3051 where `A` = `B` = `C` = `D` = `Integer'Last`. 3052 Now the intermediate results are 3053 out of the range of `Long_Long_Integer` even though the final result 3054 is in range and the precondition is True (from a mathematical point 3055 of view). In such a case, operating in this mode, an overflow occurs 3056 for the intermediate computation (which is why this mode 3057 says *most* intermediate overflows are avoided). In this case, 3058 an exception is raised if overflow checks are enabled, and the 3059 execution is erroneous if overflow checks are suppressed. 3060 3061* *All intermediate overflows avoided* (`ELIMINATED`) 3062 3063 In this mode, the compiler avoids all intermediate overflows 3064 by using arbitrary precision arithmetic as required. In this 3065 mode, the above example with `A**2 * B**2` would 3066 not cause intermediate overflow, because the intermediate result 3067 would be evaluated using sufficient precision, and the result 3068 of evaluating the precondition would be True. 3069 3070 This mode has the advantage of avoiding any intermediate 3071 overflows, but at the expense of significant run-time overhead, 3072 including the use of a library (included automatically in this 3073 mode) for multiple-precision arithmetic. 3074 3075 This mode provides cleaner semantics for assertions, since now 3076 the run-time behavior emulates true arithmetic behavior for the 3077 predefined arithmetic operators, meaning that there is never a 3078 conflict between the mathematical view of the assertion, and its 3079 run-time behavior. 3080 3081 Note that in this mode, the behavior is unaffected by whether or 3082 not overflow checks are suppressed, since overflow does not occur. 3083 It is possible for gigantic intermediate expressions to raise 3084 `Storage_Error` as a result of attempting to compute the 3085 results of such expressions (e.g. `Integer'Last ** Integer'Last`) 3086 but overflow is impossible. 3087 3088 3089Note that these modes apply only to the evaluation of predefined 3090arithmetic, membership, and comparison operators for signed integer 3091aritmetic. 3092 3093For fixed-point arithmetic, checks can be suppressed. But if checks 3094are enabled 3095then fixed-point values are always checked for overflow against the 3096base type for intermediate expressions (that is such checks always 3097operate in the equivalent of `STRICT` mode). 3098 3099For floating-point, on nearly all architectures, `Machine_Overflows` 3100is False, and IEEE infinities are generated, so overflow exceptions 3101are never raised. If you want to avoid infinities, and check that 3102final results of expressions are in range, then you can declare a 3103constrained floating-point type, and range checks will be carried 3104out in the normal manner (with infinite values always failing all 3105range checks). 3106 3107 3108.. _Specifying_the_Desired_Mode: 3109 3110Specifying the Desired Mode 3111--------------------------- 3112 3113.. index:: pragma Overflow_Mode 3114 3115The desired mode of for handling intermediate overflow can be specified using 3116either the `Overflow_Mode` pragma or an equivalent compiler switch. 3117The pragma has the form 3118 3119 .. code-block:: ada 3120 3121 pragma Overflow_Mode ([General =>] MODE [, [Assertions =>] MODE]); 3122 3123where `MODE` is one of 3124 3125* `STRICT`: intermediate overflows checked (using base type) 3126* `MINIMIZED`: minimize intermediate overflows 3127* `ELIMINATED`: eliminate intermediate overflows 3128 3129The case is ignored, so `MINIMIZED`, `Minimized` and 3130`minimized` all have the same effect. 3131 3132If only the `General` parameter is present, then the given `MODE` 3133applies 3134to expressions both within and outside assertions. If both arguments 3135are present, then `General` applies to expressions outside assertions, 3136and `Assertions` applies to expressions within assertions. For example: 3137 3138 .. code-block:: ada 3139 3140 pragma Overflow_Mode 3141 (General => Minimized, Assertions => Eliminated); 3142 3143specifies that general expressions outside assertions be evaluated 3144in 'minimize intermediate overflows' mode, and expressions within 3145assertions be evaluated in 'eliminate intermediate overflows' mode. 3146This is often a reasonable choice, avoiding excessive overhead 3147outside assertions, but assuring a high degree of portability 3148when importing code from another compiler, while incurring 3149the extra overhead for assertion expressions to ensure that 3150the behavior at run time matches the expected mathematical 3151behavior. 3152 3153The `Overflow_Mode` pragma has the same scoping and placement 3154rules as pragma `Suppress`, so it can occur either as a 3155configuration pragma, specifying a default for the whole 3156program, or in a declarative scope, where it applies to the 3157remaining declarations and statements in that scope. 3158 3159Note that pragma `Overflow_Mode` does not affect whether 3160overflow checks are enabled or suppressed. It only controls the 3161method used to compute intermediate values. To control whether 3162overflow checking is enabled or suppressed, use pragma `Suppress` 3163or `Unsuppress` in the usual manner 3164 3165 3166.. index:: -gnato? (gcc) 3167.. index:: -gnato?? (gcc) 3168 3169Additionally, a compiler switch *-gnato?* or *-gnato??* 3170can be used to control the checking mode default (which can be subsequently 3171overridden using pragmas). 3172 3173Here ``?`` is one of the digits ``1`` through ``3``: 3174 3175 ====== ===================================================== 3176 ``1`` use base type for intermediate operations (`STRICT`) 3177 ``2`` minimize intermediate overflows (`MINIMIZED`) 3178 ``3`` eliminate intermediate overflows (`ELIMINATED`) 3179 ====== ===================================================== 3180 3181As with the pragma, if only one digit appears then it applies to all 3182cases; if two digits are given, then the first applies outside 3183assertions, and the second within assertions. Thus the equivalent 3184of the example pragma above would be 3185*-gnato23*. 3186 3187If no digits follow the *-gnato*, then it is equivalent to 3188*-gnato11*, 3189causing all intermediate operations to be computed using the base 3190type (`STRICT` mode). 3191 3192 3193.. _Default_Settings: 3194 3195Default Settings 3196---------------- 3197 3198The default mode for overflow checks is 3199 3200 :: 3201 3202 General => Strict 3203 3204which causes all computations both inside and outside assertions to use 3205the base type. 3206 3207This retains compatibility with previous versions of 3208GNAT which suppressed overflow checks by default and always 3209used the base type for computation of intermediate results. 3210 3211.. Sphinx allows no emphasis within :index: role. As a workaround we 3212 point the index to "switch" and use emphasis for "-gnato". 3213 3214The :index:`switch <-gnato (gcc)>` *-gnato* (with no digits following) 3215is equivalent to 3216 3217 :: 3218 3219 General => Strict 3220 3221which causes overflow checking of all intermediate overflows 3222both inside and outside assertions against the base type. 3223 3224The pragma `Suppress (Overflow_Check)` disables overflow 3225checking, but it has no effect on the method used for computing 3226intermediate results. 3227 3228The pragma `Unsuppress (Overflow_Check)` enables overflow 3229checking, but it has no effect on the method used for computing 3230intermediate results. 3231 3232 3233.. _Implementation_Notes: 3234 3235Implementation Notes 3236-------------------- 3237 3238In practice on typical 64-bit machines, the `MINIMIZED` mode is 3239reasonably efficient, and can be generally used. It also helps 3240to ensure compatibility with code imported from some other 3241compiler to GNAT. 3242 3243Setting all intermediate overflows checking (`CHECKED` mode) 3244makes sense if you want to 3245make sure that your code is compatible with any other possible 3246Ada implementation. This may be useful in ensuring portability 3247for code that is to be exported to some other compiler than GNAT. 3248 3249The Ada standard allows the reassociation of expressions at 3250the same precedence level if no parentheses are present. For 3251example, `A+B+C` parses as though it were `(A+B)+C`, but 3252the compiler can reintepret this as `A+(B+C)`, possibly 3253introducing or eliminating an overflow exception. The GNAT 3254compiler never takes advantage of this freedom, and the 3255expression `A+B+C` will be evaluated as `(A+B)+C`. 3256If you need the other order, you can write the parentheses 3257explicitly `A+(B+C)` and GNAT will respect this order. 3258 3259The use of `ELIMINATED` mode will cause the compiler to 3260automatically include an appropriate arbitrary precision 3261integer arithmetic package. The compiler will make calls 3262to this package, though only in cases where it cannot be 3263sure that `Long_Long_Integer` is sufficient to guard against 3264intermediate overflows. This package does not use dynamic 3265alllocation, but it does use the secondary stack, so an 3266appropriate secondary stack package must be present (this 3267is always true for standard full Ada, but may require 3268specific steps for restricted run times such as ZFP). 3269 3270Although `ELIMINATED` mode causes expressions to use arbitrary 3271precision arithmetic, avoiding overflow, the final result 3272must be in an appropriate range. This is true even if the 3273final result is of type `[Long_[Long_]]Integer'Base`, which 3274still has the same bounds as its associated constrained 3275type at run-time. 3276 3277Currently, the `ELIMINATED` mode is only available on target 3278platforms for which `Long_Long_Integer` is 64-bits (nearly all GNAT 3279platforms). 3280 3281 3282 3283.. _Performing_Dimensionality_Analysis_in_GNAT: 3284 3285Performing Dimensionality Analysis in GNAT 3286========================================== 3287 3288.. index:: Dimensionality analysis 3289 3290The GNAT compiler supports dimensionality checking. The user can 3291specify physical units for objects, and the compiler will verify that uses 3292of these objects are compatible with their dimensions, in a fashion that is 3293familiar to engineering practice. The dimensions of algebraic expressions 3294(including powers with static exponents) are computed from their constituents. 3295 3296.. index:: Dimension_System aspect 3297.. index:: Dimension aspect 3298 3299This feature depends on Ada 2012 aspect specifications, and is available from 3300version 7.0.1 of GNAT onwards. 3301The GNAT-specific aspect `Dimension_System` 3302allows you to define a system of units; the aspect `Dimension` 3303then allows the user to declare dimensioned quantities within a given system. 3304(These aspects are described in the *Implementation Defined Aspects* 3305chapter of the *GNAT Reference Manual*). 3306 3307The major advantage of this model is that it does not require the declaration of 3308multiple operators for all possible combinations of types: it is only necessary 3309to use the proper subtypes in object declarations. 3310 3311.. index:: System.Dim.Mks package (GNAT library) 3312.. index:: MKS_Type type 3313 3314The simplest way to impose dimensionality checking on a computation is to make 3315use of the package `System.Dim.Mks`, 3316which is part of the GNAT library. This 3317package defines a floating-point type `MKS_Type`, 3318for which a sequence of 3319dimension names are specified, together with their conventional abbreviations. 3320The following should be read together with the full specification of the 3321package, in file :file:`s-dimmks.ads`. 3322 3323 .. index:: s-dimmks.ads file 3324 3325 .. code-block:: ada 3326 3327 type Mks_Type is new Long_Long_Float 3328 with 3329 Dimension_System => ( 3330 (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'), 3331 (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'), 3332 (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'), 3333 (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'), 3334 (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => "Theta"), 3335 (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'), 3336 (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J')); 3337 3338The package then defines a series of subtypes that correspond to these 3339conventional units. For example: 3340 3341 .. code-block:: ada 3342 3343 subtype Length is Mks_Type 3344 with 3345 Dimension => (Symbol => 'm', Meter => 1, others => 0); 3346 3347and similarly for `Mass`, `Time`, `Electric_Current`, 3348`Thermodynamic_Temperature`, `Amount_Of_Substance`, and 3349`Luminous_Intensity` (the standard set of units of the SI system). 3350 3351The package also defines conventional names for values of each unit, for 3352example: 3353 3354 .. code-block":: ada 3355 3356 m : constant Length := 1.0; 3357 kg : constant Mass := 1.0; 3358 s : constant Time := 1.0; 3359 A : constant Electric_Current := 1.0; 3360 3361as well as useful multiples of these units: 3362 3363 .. code-block:: ada 3364 3365 cm : constant Length := 1.0E-02; 3366 g : constant Mass := 1.0E-03; 3367 min : constant Time := 60.0; 3368 day : constant Time := 60.0 * 24.0 * min; 3369 ... 3370 3371Using this package, you can then define a derived unit by 3372providing the aspect that 3373specifies its dimensions within the MKS system, as well as the string to 3374be used for output of a value of that unit: 3375 3376 .. code-block:: ada 3377 3378 subtype Acceleration is Mks_Type 3379 with Dimension => ("m/sec^2", 3380 Meter => 1, 3381 Second => -2, 3382 others => 0); 3383 3384Here is a complete example of use: 3385 3386 .. code-block:: ada 3387 3388 with System.Dim.MKS; use System.Dim.Mks; 3389 with System.Dim.Mks_IO; use System.Dim.Mks_IO; 3390 with Text_IO; use Text_IO; 3391 procedure Free_Fall is 3392 subtype Acceleration is Mks_Type 3393 with Dimension => ("m/sec^2", 1, 0, -2, others => 0); 3394 G : constant acceleration := 9.81 * m / (s ** 2); 3395 T : Time := 10.0*s; 3396 Distance : Length; 3397 3398 begin 3399 Put ("Gravitational constant: "); 3400 Put (G, Aft => 2, Exp => 0); Put_Line (""); 3401 Distance := 0.5 * G * T ** 2; 3402 Put ("distance travelled in 10 seconds of free fall "); 3403 Put (Distance, Aft => 2, Exp => 0); 3404 Put_Line (""); 3405 end Free_Fall; 3406 3407Execution of this program yields: 3408 3409 :: 3410 3411 Gravitational constant: 9.81 m/sec^2 3412 distance travelled in 10 seconds of free fall 490.50 m 3413 3414However, incorrect assignments such as: 3415 3416 .. code-block:: ada 3417 3418 Distance := 5.0; 3419 Distance := 5.0 * kg: 3420 3421are rejected with the following diagnoses: 3422 3423 :: 3424 3425 Distance := 5.0; 3426 >>> dimensions mismatch in assignment 3427 >>> left-hand side has dimension [L] 3428 >>> right-hand side is dimensionless 3429 3430 Distance := 5.0 * kg: 3431 >>> dimensions mismatch in assignment 3432 >>> left-hand side has dimension [L] 3433 >>> right-hand side has dimension [M] 3434 3435The dimensions of an expression are properly displayed, even if there is 3436no explicit subtype for it. If we add to the program: 3437 3438 .. code-block:: ada 3439 3440 Put ("Final velocity: "); 3441 Put (G * T, Aft =>2, Exp =>0); 3442 Put_Line (""); 3443 3444then the output includes: 3445 3446 :: 3447 3448 Final velocity: 98.10 m.s**(-1) 3449 3450 3451 3452.. _Stack_Related_Facilities: 3453 3454Stack Related Facilities 3455======================== 3456 3457This section describes some useful tools associated with stack 3458checking and analysis. In 3459particular, it deals with dynamic and static stack usage measurements. 3460 3461.. _Stack_Overflow_Checking: 3462 3463Stack Overflow Checking 3464----------------------- 3465 3466.. index:: Stack Overflow Checking 3467 3468.. index:: -fstack-check (gcc) 3469 3470For most operating systems, *gcc* does not perform stack overflow 3471checking by default. This means that if the main environment task or 3472some other task exceeds the available stack space, then unpredictable 3473behavior will occur. Most native systems offer some level of protection by 3474adding a guard page at the end of each task stack. This mechanism is usually 3475not enough for dealing properly with stack overflow situations because 3476a large local variable could "jump" above the guard page. 3477Furthermore, when the 3478guard page is hit, there may not be any space left on the stack for executing 3479the exception propagation code. Enabling stack checking avoids 3480such situations. 3481 3482To activate stack checking, compile all units with the gcc option 3483`-fstack-check`. For example: 3484 3485 :: 3486 3487 $ gcc -c -fstack-check package1.adb 3488 3489Units compiled with this option will generate extra instructions to check 3490that any use of the stack (for procedure calls or for declaring local 3491variables in declare blocks) does not exceed the available stack space. 3492If the space is exceeded, then a `Storage_Error` exception is raised. 3493 3494For declared tasks, the stack size is controlled by the size 3495given in an applicable `Storage_Size` pragma or by the value specified 3496at bind time with ``-d`` (:ref:`Switches_for_gnatbind`) or is set to 3497the default size as defined in the GNAT runtime otherwise. 3498 3499.. index:: GNAT_STACK_LIMIT 3500 3501For the environment task, the stack size depends on 3502system defaults and is unknown to the compiler. Stack checking 3503may still work correctly if a fixed 3504size stack is allocated, but this cannot be guaranteed. 3505To ensure that a clean exception is signalled for stack 3506overflow, set the environment variable 3507:envvar:`GNAT_STACK_LIMIT` to indicate the maximum 3508stack area that can be used, as in: 3509 3510 :: 3511 3512 $ SET GNAT_STACK_LIMIT 1600 3513 3514The limit is given in kilobytes, so the above declaration would 3515set the stack limit of the environment task to 1.6 megabytes. 3516Note that the only purpose of this usage is to limit the amount 3517of stack used by the environment task. If it is necessary to 3518increase the amount of stack for the environment task, then this 3519is an operating systems issue, and must be addressed with the 3520appropriate operating systems commands. 3521 3522 3523.. _Static_Stack_Usage_Analysis: 3524 3525Static Stack Usage Analysis 3526--------------------------- 3527 3528.. index:: Static Stack Usage Analysis 3529 3530.. index:: -fstack-usage 3531 3532A unit compiled with ``-fstack-usage`` will generate an extra file 3533that specifies 3534the maximum amount of stack used, on a per-function basis. 3535The file has the same 3536basename as the target object file with a :file:`.su` extension. 3537Each line of this file is made up of three fields: 3538 3539* The name of the function. 3540* A number of bytes. 3541* One or more qualifiers: `static`, `dynamic`, `bounded`. 3542 3543The second field corresponds to the size of the known part of the function 3544frame. 3545 3546The qualifier `static` means that the function frame size 3547is purely static. 3548It usually means that all local variables have a static size. 3549In this case, the second field is a reliable measure of the function stack 3550utilization. 3551 3552The qualifier `dynamic` means that the function frame size is not static. 3553It happens mainly when some local variables have a dynamic size. When this 3554qualifier appears alone, the second field is not a reliable measure 3555of the function stack analysis. When it is qualified with `bounded`, it 3556means that the second field is a reliable maximum of the function stack 3557utilization. 3558 3559A unit compiled with ``-Wstack-usage`` will issue a warning for each 3560subprogram whose stack usage might be larger than the specified amount of 3561bytes. The wording is in keeping with the qualifier documented above. 3562 3563 3564.. _Dynamic_Stack_Usage_Analysis: 3565 3566Dynamic Stack Usage Analysis 3567---------------------------- 3568 3569It is possible to measure the maximum amount of stack used by a task, by 3570adding a switch to *gnatbind*, as: 3571 3572 :: 3573 3574 $ gnatbind -u0 file 3575 3576With this option, at each task termination, its stack usage is output on 3577:file:`stderr`. 3578It is not always convenient to output the stack usage when the program 3579is still running. Hence, it is possible to delay this output until program 3580termination. for a given number of tasks specified as the argument of the 3581``-u`` option. For instance: 3582 3583 :: 3584 3585 $ gnatbind -u100 file 3586 3587will buffer the stack usage information of the first 100 tasks to terminate and 3588output this info at program termination. Results are displayed in four 3589columns: 3590 3591 :: 3592 3593 Index | Task Name | Stack Size | Stack Usage 3594 3595where: 3596 3597* *Index* is a number associated with each task. 3598 3599* *Task Name* is the name of the task analyzed. 3600 3601* *Stack Size* is the maximum size for the stack. 3602 3603* *Stack Usage* is the measure done by the stack analyzer. 3604 In order to prevent overflow, the stack 3605 is not entirely analyzed, and it's not possible to know exactly how 3606 much has actually been used. 3607 3608The environment task stack, e.g., the stack that contains the main unit, is 3609only processed when the environment variable GNAT_STACK_LIMIT is set. 3610 3611The package `GNAT.Task_Stack_Usage` provides facilities to get 3612stack usage reports at run-time. See its body for the details. 3613 3614 3615 3616.. _Memory_Management_Issues: 3617 3618Memory Management Issues 3619======================== 3620 3621This section describes some useful memory pools provided in the GNAT library 3622and in particular the GNAT Debug Pool facility, which can be used to detect 3623incorrect uses of access values (including 'dangling references'). 3624 3625.. only:: PRO or GPL 3626 3627 It also describes the *gnatmem* tool, which can be used to track down 3628 "memory leaks". 3629 3630.. _Some_Useful_Memory_Pools: 3631 3632Some Useful Memory Pools 3633------------------------ 3634 3635.. index:: Memory Pool 3636.. index:: storage, pool 3637 3638The `System.Pool_Global` package offers the Unbounded_No_Reclaim_Pool 3639storage pool. Allocations use the standard system call `malloc` while 3640deallocations use the standard system call `free`. No reclamation is 3641performed when the pool goes out of scope. For performance reasons, the 3642standard default Ada allocators/deallocators do not use any explicit storage 3643pools but if they did, they could use this storage pool without any change in 3644behavior. That is why this storage pool is used when the user 3645manages to make the default implicit allocator explicit as in this example: 3646 3647 .. code-block:: ada 3648 3649 type T1 is access Something; 3650 -- no Storage pool is defined for T2 3651 3652 type T2 is access Something_Else; 3653 for T2'Storage_Pool use T1'Storage_Pool; 3654 -- the above is equivalent to 3655 for T2'Storage_Pool use System.Pool_Global.Global_Pool_Object; 3656 3657The `System.Pool_Local` package offers the Unbounded_Reclaim_Pool storage 3658pool. The allocation strategy is similar to `Pool_Local`'s 3659except that the all 3660storage allocated with this pool is reclaimed when the pool object goes out of 3661scope. This pool provides a explicit mechanism similar to the implicit one 3662provided by several Ada 83 compilers for allocations performed through a local 3663access type and whose purpose was to reclaim memory when exiting the 3664scope of a given local access. As an example, the following program does not 3665leak memory even though it does not perform explicit deallocation: 3666 3667 .. code-block:: ada 3668 3669 with System.Pool_Local; 3670 procedure Pooloc1 is 3671 procedure Internal is 3672 type A is access Integer; 3673 X : System.Pool_Local.Unbounded_Reclaim_Pool; 3674 for A'Storage_Pool use X; 3675 v : A; 3676 begin 3677 for I in 1 .. 50 loop 3678 v := new Integer; 3679 end loop; 3680 end Internal; 3681 begin 3682 for I in 1 .. 100 loop 3683 Internal; 3684 end loop; 3685 end Pooloc1; 3686 3687The `System.Pool_Size` package implements the Stack_Bounded_Pool used when 3688`Storage_Size` is specified for an access type. 3689The whole storage for the pool is 3690allocated at once, usually on the stack at the point where the access type is 3691elaborated. It is automatically reclaimed when exiting the scope where the 3692access type is defined. This package is not intended to be used directly by the 3693user and it is implicitly used for each such declaration: 3694 3695 .. code-block:: ada 3696 3697 type T1 is access Something; 3698 for T1'Storage_Size use 10_000; 3699 3700 3701.. _The_GNAT_Debug_Pool_Facility: 3702 3703The GNAT Debug Pool Facility 3704---------------------------- 3705 3706.. index:: Debug Pool 3707.. index:: storage, pool, memory corruption 3708 3709The use of unchecked deallocation and unchecked conversion can easily 3710lead to incorrect memory references. The problems generated by such 3711references are usually difficult to tackle because the symptoms can be 3712very remote from the origin of the problem. In such cases, it is 3713very helpful to detect the problem as early as possible. This is the 3714purpose of the Storage Pool provided by `GNAT.Debug_Pools`. 3715 3716In order to use the GNAT specific debugging pool, the user must 3717associate a debug pool object with each of the access types that may be 3718related to suspected memory problems. See Ada Reference Manual 13.11. 3719 3720 .. code-block:: ada 3721 3722 type Ptr is access Some_Type; 3723 Pool : GNAT.Debug_Pools.Debug_Pool; 3724 for Ptr'Storage_Pool use Pool; 3725 3726`GNAT.Debug_Pools` is derived from a GNAT-specific kind of 3727pool: the `Checked_Pool`. Such pools, like standard Ada storage pools, 3728allow the user to redefine allocation and deallocation strategies. They 3729also provide a checkpoint for each dereference, through the use of 3730the primitive operation `Dereference` which is implicitly called at 3731each dereference of an access value. 3732 3733Once an access type has been associated with a debug pool, operations on 3734values of the type may raise four distinct exceptions, 3735which correspond to four potential kinds of memory corruption: 3736 3737* `GNAT.Debug_Pools.Accessing_Not_Allocated_Storage` 3738* `GNAT.Debug_Pools.Accessing_Deallocated_Storage` 3739* `GNAT.Debug_Pools.Freeing_Not_Allocated_Storage` 3740* `GNAT.Debug_Pools.Freeing_Deallocated_Storage` 3741 3742For types associated with a Debug_Pool, dynamic allocation is performed using 3743the standard GNAT allocation routine. References to all allocated chunks of 3744memory are kept in an internal dictionary. Several deallocation strategies are 3745provided, whereupon the user can choose to release the memory to the system, 3746keep it allocated for further invalid access checks, or fill it with an easily 3747recognizable pattern for debug sessions. The memory pattern is the old IBM 3748hexadecimal convention: `16#DEADBEEF#`. 3749 3750See the documentation in the file g-debpoo.ads for more information on the 3751various strategies. 3752 3753Upon each dereference, a check is made that the access value denotes a 3754properly allocated memory location. Here is a complete example of use of 3755`Debug_Pools`, that includes typical instances of memory corruption: 3756 3757 .. code-block:: ada 3758 3759 with Gnat.Io; use Gnat.Io; 3760 with Unchecked_Deallocation; 3761 with Unchecked_Conversion; 3762 with GNAT.Debug_Pools; 3763 with System.Storage_Elements; 3764 with Ada.Exceptions; use Ada.Exceptions; 3765 procedure Debug_Pool_Test is 3766 3767 type T is access Integer; 3768 type U is access all T; 3769 3770 P : GNAT.Debug_Pools.Debug_Pool; 3771 for T'Storage_Pool use P; 3772 3773 procedure Free is new Unchecked_Deallocation (Integer, T); 3774 function UC is new Unchecked_Conversion (U, T); 3775 A, B : aliased T; 3776 3777 procedure Info is new GNAT.Debug_Pools.Print_Info(Put_Line); 3778 3779 begin 3780 Info (P); 3781 A := new Integer; 3782 B := new Integer; 3783 B := A; 3784 Info (P); 3785 Free (A); 3786 begin 3787 Put_Line (Integer'Image(B.all)); 3788 exception 3789 when E : others => Put_Line ("raised: " & Exception_Name (E)); 3790 end; 3791 begin 3792 Free (B); 3793 exception 3794 when E : others => Put_Line ("raised: " & Exception_Name (E)); 3795 end; 3796 B := UC(A'Access); 3797 begin 3798 Put_Line (Integer'Image(B.all)); 3799 exception 3800 when E : others => Put_Line ("raised: " & Exception_Name (E)); 3801 end; 3802 begin 3803 Free (B); 3804 exception 3805 when E : others => Put_Line ("raised: " & Exception_Name (E)); 3806 end; 3807 Info (P); 3808 end Debug_Pool_Test; 3809 3810The debug pool mechanism provides the following precise diagnostics on the 3811execution of this erroneous program: 3812 3813 :: 3814 3815 Debug Pool info: 3816 Total allocated bytes : 0 3817 Total deallocated bytes : 0 3818 Current Water Mark: 0 3819 High Water Mark: 0 3820 3821 Debug Pool info: 3822 Total allocated bytes : 8 3823 Total deallocated bytes : 0 3824 Current Water Mark: 8 3825 High Water Mark: 8 3826 3827 raised: GNAT.DEBUG_POOLS.ACCESSING_DEALLOCATED_STORAGE 3828 raised: GNAT.DEBUG_POOLS.FREEING_DEALLOCATED_STORAGE 3829 raised: GNAT.DEBUG_POOLS.ACCESSING_NOT_ALLOCATED_STORAGE 3830 raised: GNAT.DEBUG_POOLS.FREEING_NOT_ALLOCATED_STORAGE 3831 Debug Pool info: 3832 Total allocated bytes : 8 3833 Total deallocated bytes : 4 3834 Current Water Mark: 4 3835 High Water Mark: 8 3836 3837.. only:: PRO or GPL 3838 3839 .. _The_gnatmem_Tool: 3840 3841 The *gnatmem* Tool 3842 ------------------ 3843 3844 .. index:: ! gnatmem 3845 3846 The `gnatmem` utility monitors dynamic allocation and 3847 deallocation activity in a program, and displays information about 3848 incorrect deallocations and possible sources of memory leaks. 3849 It is designed to work in association with a static runtime library 3850 only and in this context provides three types of information: 3851 3852 * General information concerning memory management, such as the total 3853 number of allocations and deallocations, the amount of allocated 3854 memory and the high water mark, i.e., the largest amount of allocated 3855 memory in the course of program execution. 3856 3857 * Backtraces for all incorrect deallocations, that is to say deallocations 3858 which do not correspond to a valid allocation. 3859 3860 * Information on each allocation that is potentially the origin of a memory 3861 leak. 3862 3863 .. _Running_gnatmem: 3864 3865 Running `gnatmem` 3866 ^^^^^^^^^^^^^^^^^ 3867 3868 `gnatmem` makes use of the output created by the special version of 3869 allocation and deallocation routines that record call information. This allows 3870 it to obtain accurate dynamic memory usage history at a minimal cost to the 3871 execution speed. Note however, that `gnatmem` is not supported on all 3872 platforms (currently, it is supported on AIX, HP-UX, GNU/Linux, Solaris and 3873 Windows). 3874 3875 The `gnatmem` command has the form 3876 3877 :: 3878 3879 $ gnatmem [`switches`] `user_program` 3880 3881 The program must have been linked with the instrumented version of the 3882 allocation and deallocation routines. This is done by linking with the 3883 :file:`libgmem.a` library. For correct symbolic backtrace information, 3884 the user program should be compiled with debugging options 3885 (see :ref:`Switches_for_gcc`). For example to build :file:`my_program`: 3886 3887 :: 3888 3889 $ gnatmake -g my_program -largs -lgmem 3890 3891 As library :file:`libgmem.a` contains an alternate body for package 3892 `System.Memory`, :file:`s-memory.adb` should not be compiled and linked 3893 when an executable is linked with library :file:`libgmem.a`. It is then not 3894 recommended to use *gnatmake* with switch *-a*. 3895 3896 When :file:`my_program` is executed, the file :file:`gmem.out` is produced. 3897 This file contains information about all allocations and deallocations 3898 performed by the program. It is produced by the instrumented allocations and 3899 deallocations routines and will be used by `gnatmem`. 3900 3901 In order to produce symbolic backtrace information for allocations and 3902 deallocations performed by the GNAT run-time library, you need to use a 3903 version of that library that has been compiled with the *-g* switch 3904 (see :ref:`Rebuilding_the_GNAT_Run-Time_Library`). 3905 3906 *gnatmem* must be supplied with the :file:`gmem.out` file and the executable to 3907 examine. If the location of :file:`gmem.out` file was not explicitly supplied by 3908 *-i* switch, gnatmem will assume that this file can be found in the 3909 current directory. For example, after you have executed :file:`my_program`, 3910 :file:`gmem.out` can be analyzed by `gnatmem` using the command: 3911 3912 :: 3913 3914 $ gnatmem my_program 3915 3916 This will produce the output with the following format: 3917 3918 :: 3919 3920 $ gnatmem my_program 3921 3922 Global information 3923 ------------------ 3924 Total number of allocations : 45 3925 Total number of deallocations : 6 3926 Final Water Mark (non freed mem) : 11.29 Kilobytes 3927 High Water Mark : 11.40 Kilobytes 3928 3929 . 3930 . 3931 . 3932 Allocation Root # 2 3933 ------------------- 3934 Number of non freed allocations : 11 3935 Final Water Mark (non freed mem) : 1.16 Kilobytes 3936 High Water Mark : 1.27 Kilobytes 3937 Backtrace : 3938 my_program.adb:23 my_program.alloc 3939 . 3940 . 3941 . 3942 3943 The first block of output gives general information. In this case, the 3944 Ada construct **new** was executed 45 times, and only 6 calls to an 3945 Unchecked_Deallocation routine occurred. 3946 3947 Subsequent paragraphs display information on all allocation roots. 3948 An allocation root is a specific point in the execution of the program 3949 that generates some dynamic allocation, such as a **new** 3950 construct. This root is represented by an execution backtrace (or subprogram 3951 call stack). By default the backtrace depth for allocations roots is 1, so 3952 that a root corresponds exactly to a source location. The backtrace can 3953 be made deeper, to make the root more specific. 3954 3955 .. _Switches_for_gnatmem: 3956 3957 Switches for `gnatmem` 3958 ^^^^^^^^^^^^^^^^^^^^^^ 3959 3960 `gnatmem` recognizes the following switches: 3961 3962 .. index:: -q (gnatmem) 3963 3964 :samp:`-q` 3965 Quiet. Gives the minimum output needed to identify the origin of the 3966 memory leaks. Omits statistical information. 3967 3968 3969 .. index:: N switch (gnatmem) 3970 3971 :samp:`{N}` 3972 `N` is an integer literal (usually between 1 and 10) which controls the 3973 depth of the backtraces defining allocation root. The default value for 3974 N is 1. The deeper the backtrace, the more precise the localization of 3975 the root. Note that the total number of roots can depend on this 3976 parameter. This parameter must be specified *before* the name of the 3977 executable to be analyzed, to avoid ambiguity. 3978 3979 3980 .. index:: -b (gnatmem) 3981 3982 :samp:`-b {N}` 3983 This switch has the same effect as just a depth parameter `N`. 3984 3985 3986 .. index:: -i (gnatmem) 3987 3988 :samp:`-i {file}` 3989 Do the `gnatmem` processing starting from :file:`file`, rather than 3990 :file:`gmem.out` in the current directory. 3991 3992 3993 .. index:: -m (gnatmem) 3994 3995 :samp:`-m {n}` 3996 This switch causes `gnatmem` to mask the allocation roots that have less 3997 than n leaks. The default value is 1. Specifying the value of 0 will allow 3998 examination of even the roots that did not result in leaks. 3999 4000 4001 .. index:: -s (gnatmem) 4002 4003 :samp:`-s {order}` 4004 This switch causes `gnatmem` to sort the allocation roots according to the 4005 specified order of sort criteria, each identified by a single letter. The 4006 currently supported criteria are `n`, `h`, and `w` standing respectively for 4007 number of unfreed allocations, high watermark, and final watermark 4008 corresponding to a specific root. The default order is `nwh`. 4009 4010 4011 .. index:: -t (gnatmem) 4012 4013 :samp:`-t` 4014 This switch causes memory allocated size to be always output in bytes. 4015 Default `gnatmem` behavior is to show memory sizes less then 1 kilobyte 4016 in bytes, from 1 kilobyte till 1 megabyte in kilobytes and the rest in 4017 megabytes. 4018 4019 4020 .. _Example_of_gnatmem_Usage: 4021 4022 Example of `gnatmem` Usage 4023 ^^^^^^^^^^^^^^^^^^^^^^^^^^ 4024 4025 The following example shows the use of `gnatmem` 4026 on a simple memory-leaking program. 4027 Suppose that we have the following Ada program: 4028 4029 .. code-block:: ada 4030 4031 with Unchecked_Deallocation; 4032 procedure Test_Gm is 4033 4034 type T is array (1..1000) of Integer; 4035 type Ptr is access T; 4036 procedure Free is new Unchecked_Deallocation (T, Ptr); 4037 A : Ptr; 4038 4039 procedure My_Alloc is 4040 begin 4041 A := new T; 4042 end My_Alloc; 4043 4044 procedure My_DeAlloc is 4045 B : Ptr := A; 4046 begin 4047 Free (B); 4048 end My_DeAlloc; 4049 4050 begin 4051 My_Alloc; 4052 for I in 1 .. 5 loop 4053 for J in I .. 5 loop 4054 My_Alloc; 4055 end loop; 4056 My_Dealloc; 4057 end loop; 4058 end; 4059 4060 The program needs to be compiled with the debugging option and linked with 4061 the `gmem` library: 4062 4063 :: 4064 4065 $ gnatmake -g test_gm -largs -lgmem 4066 4067 Then we execute the program as usual: 4068 4069 :: 4070 4071 $ test_gm 4072 4073 Then `gnatmem` is invoked simply with 4074 4075 :: 4076 4077 $ gnatmem test_gm 4078 4079 which produces the following output (result may vary on different platforms): 4080 4081 :: 4082 4083 Global information 4084 ------------------ 4085 Total number of allocations : 18 4086 Total number of deallocations : 5 4087 Final Water Mark (non freed mem) : 53.00 Kilobytes 4088 High Water Mark : 56.90 Kilobytes 4089 4090 Allocation Root # 1 4091 ------------------- 4092 Number of non freed allocations : 11 4093 Final Water Mark (non freed mem) : 42.97 Kilobytes 4094 High Water Mark : 46.88 Kilobytes 4095 Backtrace : 4096 test_gm.adb:11 test_gm.my_alloc 4097 4098 Allocation Root # 2 4099 ------------------- 4100 Number of non freed allocations : 1 4101 Final Water Mark (non freed mem) : 10.02 Kilobytes 4102 High Water Mark : 10.02 Kilobytes 4103 Backtrace : 4104 s-secsta.adb:81 system.secondary_stack.ss_init 4105 4106 Allocation Root # 3 4107 ------------------- 4108 Number of non freed allocations : 1 4109 Final Water Mark (non freed mem) : 12 Bytes 4110 High Water Mark : 12 Bytes 4111 Backtrace : 4112 s-secsta.adb:181 system.secondary_stack.ss_init 4113 4114 4115 Note that the GNAT runtime contains itself a certain number of 4116 allocations that have no corresponding deallocation, 4117 as shown here for root #2 and root #3. 4118 This is a normal behavior when the number of non-freed allocations 4119 is one, it allocates dynamic data structures that the run time needs for 4120 the complete lifetime of the program. Note also that there is only one 4121 allocation root in the user program with a single line back trace: 4122 test_gm.adb:11 test_gm.my_alloc, whereas a careful analysis of the 4123 program shows that 'My_Alloc' is called at 2 different points in the 4124 source (line 21 and line 24). If those two allocation roots need to be 4125 distinguished, the backtrace depth parameter can be used: 4126 4127 :: 4128 4129 $ gnatmem 3 test_gm 4130 4131 which will give the following output: 4132 4133 4134 :: 4135 4136 Global information 4137 ------------------ 4138 Total number of allocations : 18 4139 Total number of deallocations : 5 4140 Final Water Mark (non freed mem) : 53.00 Kilobytes 4141 High Water Mark : 56.90 Kilobytes 4142 4143 Allocation Root # 1 4144 ------------------- 4145 Number of non freed allocations : 10 4146 Final Water Mark (non freed mem) : 39.06 Kilobytes 4147 High Water Mark : 42.97 Kilobytes 4148 Backtrace : 4149 test_gm.adb:11 test_gm.my_alloc 4150 test_gm.adb:24 test_gm 4151 b_test_gm.c:52 main 4152 4153 Allocation Root # 2 4154 ------------------- 4155 Number of non freed allocations : 1 4156 Final Water Mark (non freed mem) : 10.02 Kilobytes 4157 High Water Mark : 10.02 Kilobytes 4158 Backtrace : 4159 s-secsta.adb:81 system.secondary_stack.ss_init 4160 s-secsta.adb:283 <system__secondary_stack___elabb> 4161 b_test_gm.c:33 adainit 4162 4163 Allocation Root # 3 4164 ------------------- 4165 Number of non freed allocations : 1 4166 Final Water Mark (non freed mem) : 3.91 Kilobytes 4167 High Water Mark : 3.91 Kilobytes 4168 Backtrace : 4169 test_gm.adb:11 test_gm.my_alloc 4170 test_gm.adb:21 test_gm 4171 b_test_gm.c:52 main 4172 4173 Allocation Root # 4 4174 ------------------- 4175 Number of non freed allocations : 1 4176 Final Water Mark (non freed mem) : 12 Bytes 4177 High Water Mark : 12 Bytes 4178 Backtrace : 4179 s-secsta.adb:181 system.secondary_stack.ss_init 4180 s-secsta.adb:283 <system__secondary_stack___elabb> 4181 b_test_gm.c:33 adainit 4182 4183 The allocation root #1 of the first example has been split in 2 roots #1 4184 and #3, thanks to the more precise associated backtrace. 4185