3 .. |with| replace:: *with*
4 .. |withs| replace:: *with*\ s
5 .. |withed| replace:: *with*\ ed
6 .. |withing| replace:: *with*\ ing
8 .. -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
11 .. _GNAT_and_Program_Execution:
13 **************************
14 GNAT and Program Execution
15 **************************
17 This chapter covers several topics:
19 * `Running and Debugging Ada Programs`_
21 * `Improving Performance`_
22 * `Overflow Check Handling in GNAT`_
23 * `Performing Dimensionality Analysis in GNAT`_
24 * `Stack Related Facilities`_
25 * `Memory Management Issues`_
27 .. _Running_and_Debugging_Ada_Programs:
29 Running and Debugging Ada Programs
30 ==================================
34 This section discusses how to debug Ada programs.
36 An incorrect Ada program may be handled in three ways by the GNAT compiler:
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
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.
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.
55 .. _The_GNAT_Debugger_GDB:
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.
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``.
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.
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.
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.
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.
117 This section describes how to initiate the debugger.
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.
124 The command to run ``GDB`` is
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``.
137 .. _Introduction_to_GDB_Commands:
139 Introduction to GDB Commands
140 ----------------------------
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
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.
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
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.
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.
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.
195 Continues execution following a breakpoint, until the next breakpoint or the
196 termination of the program.
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.
206 Executes a single line. If this line is a subprogram call, executes and
207 returns from the call.
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.
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.
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.
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),
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.
243 Kills the child process in which the program is running under GDB.
244 This may be useful for several purposes:
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.
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
253 * It allows you to debug a core dump rather than a running process.
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).
264 .. _Using_Ada_Expressions:
266 Using Ada Expressions
267 ---------------------
269 .. index:: Ada expressions (in gdb)
271 ``GDB`` supports a fairly large subset of Ada expression syntax, with some
272 extensions. The philosophy behind the design of this subset is
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``).
279 * That type safety and strict adherence to Ada language restrictions
280 are not particularly relevant in a debugging context.
282 * That brevity is important to the ``GDB`` user.
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.
290 For details on the supported Ada syntax, see :title:`Debugging with GDB`.
293 .. _Calling_User-Defined_Subprograms:
295 Calling User-Defined Subprograms
296 --------------------------------
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:
304 call subprogram-name (parameters)
306 The keyword ``call`` can be omitted in the normal case where the
307 ``subprogram-name`` does not coincide with any of the predefined
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).
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.
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.
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.
350 .. _Using_the_Next_Command_in_a_Function:
352 Using the *next* Command in a Function
353 --------------------------------------
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.
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
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.
374 .. _Stopping_When_Ada_Exceptions_Are_Raised:
376 Stopping When Ada Exceptions Are Raised
377 ---------------------------------------
379 .. index:: Exceptions (in gdb)
381 You can set catchpoints that stop the program execution when your program
382 raises selected exceptions.
385 * :samp:`catch exception`
386 Set a catchpoint that stops execution whenever (any task in the) program
387 raises any exception.
390 * :samp:`catch exception {name}`
391 Set a catchpoint that stops execution whenever (any task in the) program
392 raises the exception *name*.
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.
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*.
406 .. index:: Tasks (in gdb)
413 ``GDB`` allows the following task-related commands:
417 This command shows a list of current Ada tasks, as in the following example:
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
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.
434 .. index:: Breakpoints and tasks
436 * ``break`` *linespec* ``task`` *taskid*, ``break`` *linespec* ``task`` *taskid* ``if`` ...
438 These commands are like the ``break ... thread ...``.
439 *linespec* specifies source lines.
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.
447 If you do not specify :samp:`task {taskid}` when you set a
448 breakpoint, the breakpoint applies to *all* tasks of your
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``).
455 .. index:: Task switching (in gdb)
457 * :samp:`task {taskno}`
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
465 For more detailed information on the tasking support,
466 see :title:`Debugging with GDB`.
469 .. index:: Debugging Generic Units
472 .. _Debugging_Generic_Units:
474 Debugging Generic Units
475 -----------------------
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.
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
490 procedure kp (v1 : in out integer);
494 procedure kp (v1 : in out integer) is
512 Then to break on a call to procedure kp in the k2 instance, simply
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
524 .. index:: Remote Debugging with gdbserver
526 .. _Remote_Debugging_with_gdbserver:
528 Remote Debugging with gdbserver
529 -------------------------------
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).
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.
546 $ gdbserver localhost:4444 program
547 Process program created; pid = 5685
548 Listening on port 4444
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
558 (gdb) target remote targethost:4444
559 Remote debugging using targethost:4444
560 0x00007f29936d0af0 in ?? () from /lib64/ld-linux-x86-64.so.
562 Breakpoint 1 at 0x401f0c: file foo.adb, line 3.
566 Breakpoint 1, foo () at foo.adb:4
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.
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.
578 .. index:: Abnormal Termination or Failure to Terminate
580 .. _GNAT_Abnormal_Termination_or_Failure_to_Terminate:
582 GNAT Abnormal Termination or Failure to Terminate
583 -------------------------------------------------
585 When presented with programs that contain serious errors in syntax
587 GNAT may on rare occasions experience problems in operation, such
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.
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.
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.
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.
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.
614 .. index:: -gnatdc switch
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.
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
633 .. _Naming_Conventions_for_GNAT_Source_Files:
635 Naming Conventions for GNAT Source Files
636 ----------------------------------------
638 In order to examine the workings of the GNAT system, the following
639 brief description of its organization may be helpful:
641 * Files with prefix :file:`sc` contain the lexical scanner.
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`.
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.
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
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.
664 * The files :file:`atree.ads` and :file:`atree.adb` detail the low-level
665 data structures used by the front-end.
667 * The files :file:`sinfo.ads` and :file:`sinfo.adb` detail the structure of
668 the abstract syntax tree as produced by the parser.
670 * The files :file:`einfo.ads` and :file:`einfo.adb` detail the attributes of
671 all entities, computed during semantic analysis.
673 * Library management issues are dealt with in files with prefix
676 .. index:: Annex A (in Ada Reference Manual)
678 * Ada files with the prefix :file:`a-` are children of ``Ada``, as
681 .. index:: Annex B (in Ada reference Manual)
683 * Files with prefix :file:`i-` are children of ``Interfaces``, as
686 .. index:: System (package in Ada Reference Manual)
688 * Files with prefix :file:`s-` are children of ``System``. This includes
689 both language-defined children and GNAT run-time routines.
691 .. index:: GNAT (package)
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.
698 .. _Getting_Internal_Debugging_Information:
700 Getting Internal Debugging Information
701 --------------------------------------
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.
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
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.
722 .. index:: stack traceback
723 .. index:: stack unwinding
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.
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.
742 Note that there is no runtime performance penalty when stack traceback
743 is enabled, and no exception is raised during program execution.
745 .. index:: traceback, non-symbolic
747 .. _Non-Symbolic_Traceback:
749 Non-Symbolic Traceback
750 ^^^^^^^^^^^^^^^^^^^^^^
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.
756 .. rubric:: Tracebacks From an Unhandled Exception
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.
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`.
766 Here is a simple example with ``gnatmake``:
774 raise Constraint_Error;
788 $ gnatmake stb -g -bargs -E -largs -no-pie
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
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:
805 $ addr2line -e stb 0x401373 0x40138b 0x40139c 0x401335 0x4011c4
816 The ``addr2line`` tool has several other useful options:
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 ========================= ====================================================
827 $ addr2line -e stb -a -f -p --demangle=gnat 0x401373 0x40138b
828 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4
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:?
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.
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::
851 (gdb) break *0x401373
852 Breakpoint 1 at 0x401373: file stb.adb, line 5.
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.
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.
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::
875 $ gnatmake stb -g -bargs -E
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
884 $ gnatsymbolize --load stb 0x400000 0x401373 0x40138b 0x40139c 0x401335 \
885 0x4011c4 0x4011f1 0x77e892a4
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 ???
896 .. rubric:: Tracebacks From Exception Occurrences
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:
919 Text_IO.Put_Line (Exception_Information (E));
933 $ gnatmake stb -g -bargs -E -largs -no-pie
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
942 .. rubric:: Tracebacks From Anywhere in a Program
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.
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:
960 with GNAT.Debug_Utilities;
971 LA : constant Address := Executable_Load_Address;
974 TB : Tracebacks_Array (1 .. 10);
975 -- We are asking for a maximum of 10 stack frames.
977 -- Len will receive the actual number of stack frames returned.
979 Call_Chain (TB, Len);
981 Put ("In STB.P1 : ");
983 for K in 1 .. Len loop
984 Put (Debug_Utilities.Image_C (TB (K)));
997 if LA /= Null_Address then
998 Put_Line ("Load address: " & Debug_Utilities.Image_C (LA));
1009 Load address: 0x400000
1010 In STB.P1 : 0x40F1E4 0x4014F2 0x40170B 0x40171C 0x401461 0x4011C4 \
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').
1018 .. index:: traceback, symbolic
1020 .. _Symbolic_Traceback:
1025 A symbolic traceback is a stack traceback in which procedure names are
1026 associated with each code location.
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.
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.
1037 .. rubric:: Tracebacks From Exception Occurrences
1044 with GNAT.Traceback.Symbolic;
1050 raise Constraint_Error;
1067 Ada.Text_IO.Put_Line (GNAT.Traceback.Symbolic.Symbolic_Traceback (E));
1072 $ gnatmake -g stb -bargs -E
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
1084 .. rubric:: Tracebacks From Anywhere in a Program
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:
1095 with GNAT.Traceback;
1096 with GNAT.Traceback.Symbolic;
1102 use GNAT.Traceback.Symbolic;
1105 TB : Tracebacks_Array (1 .. 10);
1106 -- We are asking for a maximum of 10 stack frames.
1108 -- Len will receive the actual number of stack frames returned.
1110 Call_Chain (TB, Len);
1111 Text_IO.Put_Line (Symbolic_Traceback (TB (1 .. Len)));
1124 .. rubric:: Automatic Symbolic Tracebacks
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
1133 .. _Pretty-Printers_For_The_GNAT_Runtime:
1135 Pretty-Printers for the GNAT runtime
1136 ------------------------------------
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.
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``:
1148 with Ada.Containers.Ordered_Maps;
1151 package Int_To_Nat is
1152 new Ada.Containers.Ordered_Maps (Integer, Natural);
1154 Map : Int_To_Nat.Map;
1160 Map.Clear; -- BREAK HERE
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
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:
1193 python import gnatdbg; gnatdbg.setup()
1195 Once this is done, GDB's ``print`` command will automatically use
1196 these pretty-printers when appropriate. Using the previous example:
1201 $1 = pp.int_to_nat.map of length 3 = {
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).
1212 To display a value without involving pretty-printers, ``print`` can be
1213 invoked with its ``/r`` option:
1221 Finer control of pretty-printers is also possible: see `GDB's online
1223 <http://docs.adacore.com/gdb-docs/html/gdb.html#Pretty_002dPrinter-Commands>`_
1224 for more information.
1227 .. index:: Profiling
1235 This section describes how to use the ``gprof`` profiler tool on Ada programs.
1238 .. index:: Profiling
1240 .. _Profiling_an_Ada_Program_with_gprof:
1242 Profiling an Ada Program with gprof
1243 -----------------------------------
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.
1249 Profiling a program helps determine the parts of a program that are executed
1250 most often, and are therefore the most time-consuming.
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
1257 * Windows x86/x86_64 (without PIE support)
1259 In order to profile a program using ``gprof``, several steps are needed:
1261 #. Instrument the code, which requires a full recompilation of the project with the
1264 #. Execute the program under the analysis conditions, i.e. with the desired
1267 #. Analyze the results using the ``gprof`` tool.
1269 The following sections detail the different steps, and indicate how
1270 to interpret the results.
1273 .. _Compilation_for_profiling:
1275 Compilation for profiling
1276 ^^^^^^^^^^^^^^^^^^^^^^^^^
1278 .. index:: -pg (gcc), for profiling
1279 .. index:: -pg (gnatlink), for profiling
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:
1289 $ gnatmake -f -pg -P my_project
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.
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.
1299 .. _Program_execution:
1305 Once the program has been compiled for profiling, you can run it as usual.
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
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.
1321 The ``gprof`` tool is called as follow:
1325 $ gprof my_prog gmon.out
1333 The complete form of the gprof command line is the following:
1337 $ gprof [switches] [executable [data-file]]
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.
1343 The following is the subset of those switches that is most relevant:
1345 .. index:: --demangle (gprof)
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``.
1357 .. index:: -e (gprof)
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``
1369 .. index:: -E (gprof)
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.
1379 .. index:: -f (gprof)
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``
1389 .. index:: -F (gprof)
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.
1400 .. _Interpretation_of_profiling_results:
1402 Interpretation of profiling results
1403 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
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.
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.
1419 .. _Improving_Performance:
1421 Improving Performance
1422 =====================
1424 .. index:: Improving performance
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.
1430 It then documents the unused subprogram/data elimination feature,
1431 which can reduce the size of program executables.
1433 .. _Performance_Considerations:
1435 Performance Considerations
1436 --------------------------
1438 The GNAT system provides a number of options that allow a trade-off
1441 * performance of the generated code
1443 * speed of compilation
1445 * minimization of dependences and recompilation
1447 * the degree of run-time checking.
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:
1455 * no inlining of subprogram calls
1457 * all run-time checks enabled except overflow and elaboration checks
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.
1464 .. _Controlling_Run-Time_Checks:
1466 Controlling Run-Time Checks
1467 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
1474 .. index:: -gnatp (gcc)
1475 .. index:: -gnato (gcc)
1477 The gnat switch, :switch:`-gnatp` allows this default to be modified. See
1478 :ref:`Run-Time_Checks`.
1480 Our experience is that the default is suitable for most development
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.
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.
1497 .. index:: Overflow checks
1498 .. index:: Checks, overflow
1501 .. index:: Unsuppress
1502 .. index:: pragma Suppress
1503 .. index:: pragma Unsuppress
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.
1511 .. _Use_of_Restrictions:
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.
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.
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
1536 pragma Restrictions (No_Abort_Statements);
1537 pragma Restrictions (Max_Asynchronous_Select_Nesting => 0);
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.
1544 .. _Optimization_Levels:
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.
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.
1564 -O options, with or without level numbers,
1565 the last such option is the one that is effective.
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:
1577 No optimization (the default);
1578 generates unoptimized code but has
1579 the fastest compilation time.
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.
1589 Moderate optimization;
1590 optimizes reasonably well but does not
1591 degrade compilation time significantly.
1595 generates highly optimized code and has
1596 the slowest compilation time.
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.
1605 Optimize space usage (code and data) of resulting program.
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.
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)`
1620 the :switch:`-O` settings and a number of :switch:`-f` options that
1621 individually enable or disable specific optimizations.
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
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`.
1637 .. _Debugging_Optimized_Code:
1639 Debugging Optimized Code
1640 ^^^^^^^^^^^^^^^^^^^^^^^^
1642 .. index:: Debugging optimized code
1643 .. index:: Optimization and debugging
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.
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)
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:
1671 * *The 'hopping Program Counter':* Repeated ``step`` or ``next``
1673 the PC bouncing back and forth in the code. This may result from any of
1674 the following optimizations:
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.
1680 - *Invariant code motion:* moving an expression that does not change within a
1681 loop, to the beginning of the loop.
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.
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.
1700 * *The 'roving variable':* The symptom is an unexpected value in a variable.
1701 There are various reasons for this effect:
1703 - In a subprogram prologue, a parameter may not yet have been moved to its
1706 - A variable may be dead, and its register re-used. This is
1707 probably the most common cause.
1709 - As mentioned above, the assignment of a value to a variable may
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
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.
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
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
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.
1743 .. _Inlining_of_Subprograms:
1745 Inlining of Subprograms
1746 ^^^^^^^^^^^^^^^^^^^^^^^
1748 A call to a subprogram in the current unit is inlined if all the
1749 following conditions are met:
1751 * The optimization level is at least :switch:`-O1`.
1753 * The called subprogram is suitable for inlining: It must be small enough
1754 and not contain something that ``gcc`` cannot support in inlined
1757 .. index:: pragma Inline
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.
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:
1769 * The optimization level is at least :switch:`-O1`.
1771 * The called subprogram is suitable for inlining: It must be small enough
1772 and not contain something that ``gcc`` cannot support in inlined
1775 * There is a ``pragma Inline`` for the subprogram.
1777 * The :switch:`-gnatn` switch is used on the command line.
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
1784 Note that specifying the :switch:`-gnatn` switch causes additional
1785 compilation dependencies. Consider the following:
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
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``.
1818 The use of front end inlining with :switch:`-gnatN` generates similar
1819 additional dependencies.
1821 .. index:: -fno-inline (gcc)
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.
1828 .. index:: -fno-inline-functions (gcc)
1830 Note: The :switch:`-fno-inline-functions` switch can be used to prevent
1831 automatic inlining of subprograms if :switch:`-O3` is used.
1833 .. index:: -fno-inline-small-functions (gcc)
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.
1838 .. index:: -fno-inline-functions-called-once (gcc)
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.
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.
1863 .. _Floating_Point_Operations:
1865 Floating Point Operations
1866 ^^^^^^^^^^^^^^^^^^^^^^^^^
1868 .. index:: Floating-Point Operations
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.
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.
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:
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
1912 .. _Vectorization_of_loops:
1914 Vectorization of loops
1915 ^^^^^^^^^^^^^^^^^^^^^^
1917 .. index:: Optimization Switches
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.
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`.
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:
1940 A : array (1..4, 1..4) of Long_Float;
1941 S : array (1..4) of Long_Float;
1945 for I in A'Range(1) loop
1946 for J in A'Range(2) loop
1947 S (I) := S (I) + A (I, J);
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
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:
1965 Integer (S'Truncation (F))
1967 if ``S`` is the subtype of floating-point object ``F``.
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
1975 type Array_Type is array (1 .. 4) of Long_Float;
1977 constrained array types with dynamic bounds:
1982 type Array_Type is array (1 .. Q.N) of Long_Float;
1984 type Array_Type is array (Q.K .. 4) of Long_Float;
1986 type Array_Type is array (Q.K .. Q.N) of Long_Float;
1988 or unconstrained array types:
1992 type Array_Type is array (Positive range <>) of Long_Float;
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.
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``:
2005 pragma Loop_Optimize (Vector);
2007 placed immediately within the loop will convey the appropriate hint to the
2008 compiler for this loop.
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:
2016 type Arr is array (1 .. 4) of Long_Float;
2018 procedure Add (X, Y : not null access Arr; R : not null access Arr) is
2020 for I in Arr'Range loop
2021 R(I) := X(I) + Y(I);
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:
2035 pragma Loop_Optimize (Ivdep);
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.
2041 .. _Other_Optimization_Switches:
2043 Other Optimization Switches
2044 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
2046 .. index:: Optimization Switches
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)`.
2059 .. _Optimization_and_Strict_Aliasing:
2061 Optimization and Strict Aliasing
2062 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2065 .. index:: Strict Aliasing
2066 .. index:: No_Strict_Aliasing
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:
2076 type Int1 is new Integer;
2077 type Int2 is new Integer;
2078 type Int1A is access Int1;
2079 type Int2A is access Int2;
2086 for J in Data'Range loop
2087 if Data (J) = Int1V.all then
2088 Int2V.all := Int2V.all + 1;
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.
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.
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:
2115 type int1 is new integer;
2116 type int2 is new integer;
2117 type a1 is access int1;
2118 type a2 is access int2;
2123 function to_a2 (Input : a1) return a2;
2126 with Ada.Unchecked_Conversion;
2128 function to_a2 (Input : a1) return a2 is
2130 new Ada.Unchecked_Conversion (a1, a2);
2132 return to_a2u (Input);
2138 with Text_IO; use Text_IO;
2140 v1 : a1 := new int1;
2141 v2 : a2 := to_a2 (v1);
2145 put_line (int1'image (v1.all));
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
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.
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.
2169 Indeed the compiler recognizes this possibility, and the
2170 unchecked conversion generates a warning:
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);"
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``.
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.
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.
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.
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.
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.
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
2221 pragma Warnings (Off);
2223 new Ada.Unchecked_Conversion (a1, a2);
2224 pragma Warnings (On);
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.
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.
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:
2248 type a2 is access int2;
2249 pragma No_Strict_Aliasing (a2);
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.
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.
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.
2283 .. _Aliased_Variables_and_Optimization:
2285 Aliased Variables and Optimization
2286 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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:
2301 Max_Length : constant Natural := 16;
2302 type Char_Ptr is access all Character;
2304 procedure Get_String(Buffer: Char_Ptr; Size : Integer);
2305 pragma Import (C, Get_String, "get_string");
2307 Name : aliased String (1 .. Max_Length) := (others => ' ');
2310 function Addr (S : String) return Char_Ptr is
2311 function To_Char_Ptr is
2312 new Ada.Unchecked_Conversion (System.Address, Char_Ptr);
2314 return To_Char_Ptr (S (S'First)'Address);
2318 Temp := Addr (Name);
2319 Get_String (Temp, Max_Length);
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.
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.
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.
2339 .. _Atomic_Variables_and_Optimization:
2341 Atomic Variables and Optimization
2342 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2346 There are two considerations with regard to performance when
2347 atomic variables are used.
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).
2357 That being said, it is important to understand that you cannot
2358 assume that the entire variable will always be accessed. Consider
2364 A,B,C,D : Character;
2367 for R'Alignment use 4;
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.
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
2392 RV_Copy : constant R := RV;
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).
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.
2415 .. _Passive_Task_Optimization:
2417 Passive Task Optimization
2418 ^^^^^^^^^^^^^^^^^^^^^^^^^
2420 .. index:: Passive Task
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.
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.
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.
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
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.
2461 .. _Text_IO_Suggestions:
2463 ``Text_IO`` Suggestions
2464 -----------------------
2466 .. index:: Text_IO and performance
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.
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).
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``.
2485 .. _Reducing_Size_of_Executables_with_Unused_Subprogram/Data_Elimination:
2487 Reducing Size of Executables with Unused Subprogram/Data Elimination
2488 --------------------------------------------------------------------
2490 .. index:: Uunused subprogram/data elimination
2492 This section describes how you can eliminate unused subprograms and data from
2493 your executable just by setting options at compilation time.
2495 .. _About_unused_subprogram/data_elimination:
2497 About unused subprogram/data elimination
2498 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
2504 This feature will allow you to eliminate such unused code from your
2505 executable, making it smaller (in disk and in memory).
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.
2511 .. _Compilation_options:
2516 The operation of eliminating the unused code and data from the final executable
2517 is directly performed by the linker.
2519 .. index:: -ffunction-sections (gcc)
2520 .. index:: -fdata-sections (gcc)
2522 In order to do this, it has to work with objects compiled with the
2524 :switch:`-ffunction-sections` :switch:`-fdata-sections`.
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.
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.
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`
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
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.
2550 .. _Example_of_unused_subprogram/data_elimination:
2552 Example of unused subprogram/data elimination
2553 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2555 Here is a simple example:
2567 Used_Data : Integer;
2568 Unused_Data : Integer;
2570 procedure Used (Data : Integer);
2571 procedure Unused (Data : Integer);
2575 procedure Used (Data : Integer) is
2580 procedure Unused (Data : Integer) is
2582 Unused_Data := Data;
2586 ``Unused`` and ``Unused_Data`` are never referenced in this code
2587 excerpt, and hence they may be safely removed from the final executable.
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
2599 $ gnatmake test -cargs -fdata-sections -ffunction-sections \\
2600 -largs -Wl,--gc-sections
2602 $ nm test | grep used
2603 02005350 T aux__used
2604 0201ffe0 B aux__used_data
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.
2611 .. index:: Overflow checks
2612 .. index:: Checks (overflow)
2614 .. _Overflow_Check_Handling_in_GNAT:
2616 Overflow Check Handling in GNAT
2617 ===============================
2619 This section explains how to control the handling of overflow checks.
2626 Overflow checks are checks that the compiler may make to ensure
2627 that intermediate results are not out of range. For example:
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
2640 A trickier situation arises in examples like the following:
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.
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
2658 * raise an exception (``Constraint_Error``), or
2660 * yield the correct mathematical result which is then used in
2661 subsequent operations.
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.
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.
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.
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
2687 Furthermore, when using Ada 2012's preconditions and other
2688 assertion forms, another issue arises. Consider:
2692 procedure P (A, B : Integer) with
2693 Pre => A + B <= Integer'Last;
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.
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.
2708 The situation is worse in a case such as the following:
2712 procedure Q (A, B, C : Integer) with
2713 Pre => A + B + C <= Integer'Last;
2719 Q (A => Integer'Last, B => 1, C => -1);
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).
2727 .. _Management_of_Overflows_in_GNAT:
2729 Management of Overflows in GNAT
2730 -------------------------------
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.
2741 The three modes are:
2743 * *Use base type for intermediate operations* (``STRICT``)
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.
2752 * *Most intermediate overflows avoided* (``MINIMIZED``)
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
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.
2768 However, there are cases where ``Long_Long_Integer`` is not large
2769 enough, consider the following example:
2773 procedure R (A, B, C, D : Integer) with
2774 Pre => (A**2 * B**2) / (C**2 * D**2) <= 10;
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.
2786 * *All intermediate overflows avoided* (``ELIMINATED``)
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.
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.
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
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.
2814 Note that these modes apply only to the evaluation of predefined
2815 arithmetic, membership, and comparison operators for signed integer
2818 For fixed-point arithmetic, checks can be suppressed. But if checks
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).
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
2833 .. _Specifying_the_Desired_Mode:
2835 Specifying the Desired Mode
2836 ---------------------------
2838 .. index:: pragma Overflow_Mode
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
2846 pragma Overflow_Mode ([General =>] MODE [, [Assertions =>] MODE]);
2848 where ``MODE`` is one of
2850 * ``STRICT``: intermediate overflows checked (using base type)
2851 * ``MINIMIZED``: minimize intermediate overflows
2852 * ``ELIMINATED``: eliminate intermediate overflows
2854 The case is ignored, so ``MINIMIZED``, ``Minimized`` and
2855 ``minimized`` all have the same effect.
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:
2864 pragma Overflow_Mode
2865 (General => Minimized, Assertions => Eliminated);
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
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.
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.
2890 .. index:: -gnato? (gcc)
2891 .. index:: -gnato?? (gcc)
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).
2897 Here ``?`` is one of the digits ``1`` through ``3``:
2899 ====== ======================================================
2900 ``1`` use base type for intermediate operations (``STRICT``)
2901 ``2`` minimize intermediate overflows (``MINIMIZED``)
2902 ``3`` eliminate intermediate overflows (``ELIMINATED``)
2903 ====== ======================================================
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
2911 If no digits follow the :switch:`-gnato`, then it is equivalent to
2913 causing all intermediate operations to be computed using the base
2914 type (``STRICT`` mode).
2917 .. _Default_Settings:
2922 The default mode for overflow checks is
2928 which causes all computations both inside and outside assertions to use
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.
2935 .. Sphinx allows no emphasis within :index: role. As a workaround we
2936 point the index to "switch" and use emphasis for "-gnato".
2938 The :index:`switch <-gnato (gcc)>` :switch:`-gnato` (with no digits following)
2945 which causes overflow checking of all intermediate overflows
2946 both inside and outside assertions against the base type.
2948 The pragma ``Suppress (Overflow_Check)`` disables overflow
2949 checking, but it has no effect on the method used for computing
2950 intermediate results.
2952 The pragma ``Unsuppress (Overflow_Check)`` enables overflow
2953 checking, but it has no effect on the method used for computing
2954 intermediate results.
2957 .. _Implementation_Notes:
2959 Implementation Notes
2960 --------------------
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
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.
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.
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).
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
3001 Currently, the ``ELIMINATED`` mode is only available on target
3002 platforms for which ``Long_Long_Integer`` is 64-bits (nearly all GNAT
3007 .. _Performing_Dimensionality_Analysis_in_GNAT:
3009 Performing Dimensionality Analysis in GNAT
3010 ==========================================
3012 .. index:: Dimensionality analysis
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.
3020 .. index:: Dimension_System aspect
3021 .. index:: Dimension aspect
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*).
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.
3035 .. index:: System.Dim.Mks package (GNAT library)
3036 .. index:: MKS_Type type
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`.
3046 .. index:: s-digemk.ads file
3050 type Mks_Type is new Float_Type
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'));
3061 The package then defines a series of subtypes that correspond to these
3062 conventional units. For example:
3066 subtype Length is Mks_Type
3068 Dimension => (Symbol => 'm', Meter => 1, others => 0);
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).
3074 The package also defines conventional names for values of each unit, for
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;
3084 as well as useful multiples of these units:
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;
3094 There are three instantiations of ``System.Dim.Generic_Mks`` defined in the
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`.
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:
3107 subtype Acceleration is Mks_Type
3108 with Dimension => ("m/sec^2",
3113 Here is a complete example of use:
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);
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);
3136 Execution of this program yields:
3140 Gravitational constant: 9.81 m/sec^2
3141 distance travelled in 10 seconds of free fall 490.50 m
3143 However, incorrect assignments such as:
3148 Distance := 5.0 * kg;
3150 are rejected with the following diagnoses:
3155 >>> dimensions mismatch in assignment
3156 >>> left-hand side has dimension [L]
3157 >>> right-hand side is dimensionless
3159 Distance := 5.0 * kg:
3160 >>> dimensions mismatch in assignment
3161 >>> left-hand side has dimension [L]
3162 >>> right-hand side has dimension [M]
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:
3169 Put ("Final velocity: ");
3170 Put (G * T, Aft =>2, Exp =>0);
3173 then the output includes:
3177 Final velocity: 98.10 m.s**(-1)
3180 .. index:: Dimensionable type
3181 .. index:: Dimensioned subtype
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``
3188 .. index:: Dimension Vector (for a dimensioned subtype)
3189 .. index:: Dimension aspect
3190 .. index:: Dimension_System aspect
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:
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``.
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.
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:
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.
3225 * :samp:`DV({op expr})`, where *op* is a unary operator, is :samp:`DV({expr})`
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.
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)``.
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.
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
3245 The dimensionality checks for relationals use the same rules as
3246 for "+" and "-", except when comparing to a literal; thus
3258 and is thus illegal, but
3264 is accepted with a warning. Analogously a conditional expression requires the
3265 same dimension vector for each branch (with no exception for literals).
3267 The dimension vector of a type conversion :samp:`T({expr})` is defined
3268 as follows, based on the nature of ``T``:
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.
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.
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.
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
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.
3301 The dimension vector for a type qualification :samp:`T'({expr})` is the same
3302 as for the type conversion :samp:`T({expr})`.
3304 An assignment statement
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).
3315 .. _Stack_Related_Facilities:
3317 Stack Related Facilities
3318 ========================
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.
3324 .. _Stack_Overflow_Checking:
3326 Stack Overflow Checking
3327 -----------------------
3329 .. index:: Stack Overflow Checking
3331 .. index:: -fstack-check (gcc)
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
3345 To activate stack checking, compile all units with the ``gcc`` option
3346 :switch:`-fstack-check`. For example:
3350 $ gcc -c -fstack-check package1.adb
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.
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.
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.
3367 .. _Static_Stack_Usage_Analysis:
3369 Static Stack Usage Analysis
3370 ---------------------------
3372 .. index:: Static Stack Usage Analysis
3374 .. index:: -fstack-usage
3376 A unit compiled with ``-fstack-usage`` will generate an extra file
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:
3383 * The name of the function.
3384 * A number of bytes.
3385 * One or more qualifiers: ``static``, ``dynamic``, ``bounded``.
3387 The second field corresponds to the size of the known part of the function
3390 The qualifier ``static`` means that the function frame size
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
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
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.
3408 .. _Dynamic_Stack_Usage_Analysis:
3410 Dynamic Stack Usage Analysis
3411 ----------------------------
3413 It is possible to measure the maximum amount of stack used by a task, by
3414 adding a switch to ``gnatbind``, as:
3420 With this option, at each task termination, its stack usage is output on
3422 Note that this switch is not compatible with tools like
3423 Valgrind and DrMemory; they will report errors.
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:
3432 $ gnatbind -u100 file
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
3440 Index | Task Name | Stack Size | Stack Usage
3444 * *Index* is a number associated with each task.
3446 * *Task Name* is the name of the task analyzed.
3448 * *Stack Size* is the maximum size for the stack.
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.
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:
3462 $ set GNAT_STACK_LIMIT 1600
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.
3467 The package ``GNAT.Task_Stack_Usage`` provides facilities to get
3468 stack-usage reports at run time. See its body for the details.
3472 .. _Memory_Management_Issues:
3474 Memory Management Issues
3475 ========================
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').
3481 .. only:: PRO or GPL
3483 It also describes the ``gnatmem`` tool, which can be used to track down
3486 .. _Some_Useful_Memory_Pools:
3488 Some Useful Memory Pools
3489 ------------------------
3491 .. index:: Memory Pool
3492 .. index:: storage, pool
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:
3505 type T1 is access Something;
3506 -- no Storage pool is defined for T2
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;
3513 The ``System.Pool_Local`` package offers the ``Unbounded_Reclaim_Pool`` storage
3514 pool. The allocation strategy is similar to ``Pool_Local``
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:
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;
3533 for I in 1 .. 50 loop
3538 for I in 1 .. 100 loop
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:
3553 type T1 is access Something;
3554 for T1'Storage_Size use 10_000;
3557 .. _The_GNAT_Debug_Pool_Facility:
3559 The GNAT Debug Pool Facility
3560 ----------------------------
3562 .. index:: Debug Pool
3563 .. index:: storage, pool, memory corruption
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``.
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.
3578 type Ptr is access Some_Type;
3579 Pool : GNAT.Debug_Pools.Debug_Pool;
3580 for Ptr'Storage_Pool use Pool;
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.
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:
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``
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#``.
3606 See the documentation in the file g-debpoo.ads for more information on the
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:
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
3623 type T is access Integer;
3624 type U is access all T;
3626 P : GNAT.Debug_Pools.Debug_Pool;
3627 for T'Storage_Pool use P;
3629 procedure Free is new Ada.Unchecked_Deallocation (Integer, T);
3630 function UC is new Ada.Unchecked_Conversion (U, T);
3633 procedure Info is new GNAT.Debug_Pools.Print_Info(Put_Line);
3643 Put_Line (Integer'Image(B.all));
3645 when E : others => Put_Line ("raised: " & Exception_Name (E));
3650 when E : others => Put_Line ("raised: " & Exception_Name (E));
3654 Put_Line (Integer'Image(B.all));
3656 when E : others => Put_Line ("raised: " & Exception_Name (E));
3661 when E : others => Put_Line ("raised: " & Exception_Name (E));
3664 end Debug_Pool_Test;
3666 The debug pool mechanism provides the following precise diagnostics on the
3667 execution of this erroneous program:
3672 Total allocated bytes : 0
3673 Total deallocated bytes : 0
3674 Current Water Mark: 0
3678 Total allocated bytes : 8
3679 Total deallocated bytes : 0
3680 Current Water Mark: 8
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
3688 Total allocated bytes : 8
3689 Total deallocated bytes : 4
3690 Current Water Mark: 4
3693 .. only:: PRO or GPL
3695 .. _The_gnatmem_Tool:
3697 The ``gnatmem`` Tool
3698 --------------------
3700 .. index:: ! gnatmem
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:
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.
3714 * Backtraces for all incorrect deallocations, that is to say deallocations
3715 which do not correspond to a valid allocation.
3717 * Information on each allocation that is potentially the origin of a memory
3720 .. _Running_gnatmem:
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.
3731 The ``gnatmem`` command has the form
3735 $ gnatmem [ switches ] [ DEPTH ] user_program
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
3747 $ gnatmake my_program -g -largs -lgmem -no-pie
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`.
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``.
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`).
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:
3772 $ gnatmem my_program
3774 This will produce the output with the following format:
3778 $ gnatmem my_program
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
3792 Number of non freed allocations : 11
3793 Final Water Mark (non freed mem) : 1.16 Kilobytes
3794 High Water Mark : 1.27 Kilobytes
3796 my_program.adb:23 my_program.alloc
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.
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.
3813 .. _Switches_for_gnatmem:
3815 Switches for ``gnatmem``
3816 ^^^^^^^^^^^^^^^^^^^^^^^^
3818 ``gnatmem`` recognizes the following switches:
3820 .. index:: -q (gnatmem)
3823 Quiet. Gives the minimum output needed to identify the origin of the
3824 memory leaks. Omits statistical information.
3827 .. index:: DEPTH switch (gnatmem)
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.
3839 .. index:: -b (gnatmem)
3842 This switch has the same effect as just a depth parameter ``N``.
3845 .. index:: -i (gnatmem)
3848 Do the ``gnatmem`` processing starting from :file:`file`, rather than
3849 :file:`gmem.out` in the current directory.
3852 .. index:: -m (gnatmem)
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.
3860 .. index:: -s (gnatmem)
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``.
3870 .. index:: -t (gnatmem)
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
3879 .. _Example_of_gnatmem_Usage:
3881 Example of ``gnatmem`` Usage
3882 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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:
3890 with Ada.Unchecked_Deallocation;
3891 procedure Test_Gm is
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);
3898 procedure My_Alloc is
3903 procedure My_DeAlloc is
3911 for I in 1 .. 5 loop
3912 for J in I .. 5 loop
3919 The program needs to be compiled with the debugging option and linked with
3920 the ``gmem`` library:
3924 $ gnatmake -g test_gm -largs -lgmem
3926 Then we execute the program as usual:
3932 Then ``gnatmem`` is invoked simply with
3938 which produces the following output (result may vary on different platforms):
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
3951 Number of non freed allocations : 11
3952 Final Water Mark (non freed mem) : 42.97 Kilobytes
3953 High Water Mark : 46.88 Kilobytes
3955 test_gm.adb:11 test_gm.my_alloc
3959 Number of non freed allocations : 1
3960 Final Water Mark (non freed mem) : 10.02 Kilobytes
3961 High Water Mark : 10.02 Kilobytes
3963 s-secsta.adb:81 system.secondary_stack.ss_init
3967 Number of non freed allocations : 1
3968 Final Water Mark (non freed mem) : 12 Bytes
3969 High Water Mark : 12 Bytes
3971 s-secsta.adb:181 system.secondary_stack.ss_init
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:
3990 which will give the following output:
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
4004 Number of non freed allocations : 10
4005 Final Water Mark (non freed mem) : 39.06 Kilobytes
4006 High Water Mark : 42.97 Kilobytes
4008 test_gm.adb:11 test_gm.my_alloc
4009 test_gm.adb:24 test_gm
4014 Number of non freed allocations : 1
4015 Final Water Mark (non freed mem) : 10.02 Kilobytes
4016 High Water Mark : 10.02 Kilobytes
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
4024 Number of non freed allocations : 1
4025 Final Water Mark (non freed mem) : 3.91 Kilobytes
4026 High Water Mark : 3.91 Kilobytes
4028 test_gm.adb:11 test_gm.my_alloc
4029 test_gm.adb:21 test_gm
4034 Number of non freed allocations : 1
4035 Final Water Mark (non freed mem) : 12 Bytes
4036 High Water Mark : 12 Bytes
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
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.