Debian Codegraph @

gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst

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