Debian Codegraph @

gcc/ada/doc/gnat_ugn/elaboration_order_handling_in_gnat.rst

raw
1 .. role:: switch(samp)
2
3 .. |with| replace:: *with*
4 .. |withs| replace:: *with*\ s
5 .. |withed| replace:: *with*\ ed
6 .. |withing| replace:: *with*\ ing
7
8 .. -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
9
10
11 .. _Elaboration_Order_Handling_in_GNAT:
12
13 **********************************
14 Elaboration Order Handling in GNAT
15 **********************************
16
17 .. index:: Order of elaboration
18 .. index:: Elaboration control
19
20 This appendix describes the handling of elaboration code in Ada and GNAT, and
21 discusses how the order of elaboration of program units can be controlled in
22 GNAT, either automatically or with explicit programming features.
23
24 .. _Elaboration_Code:
25
26 Elaboration Code
27 ================
28
29 Ada defines the term *execution* as the process by which a construct achieves
30 its run-time effect. This process is also referred to as **elaboration** for
31 declarations and *evaluation* for expressions.
32
33 The execution model in Ada allows for certain sections of an Ada program to be
34 executed prior to execution of the program itself, primarily with the intent of
35 initializing data. These sections are referred to as **elaboration code**.
36 Elaboration code is executed as follows:
37
38 * All partitions of an Ada program are executed in parallel with one another,
39 possibly in a separate address space, and possibly on a separate computer.
40
41 * The execution of a partition involves running the environment task for that
42 partition.
43
44 * The environment task executes all elaboration code (if available) for all
45 units within that partition. This code is said to be executed at
46 **elaboration time**.
47
48 * The environment task executes the Ada program (if available) for that
49 partition.
50
51 In addition to the Ada terminology, this appendix defines the following terms:
52
53 * *Invocation*
54
55 The act of calling a subprogram, instantiating a generic, or activating a
56 task.
57
58 * *Scenario*
59
60 A construct that is elaborated or invoked by elaboration code is referred to
61 as an *elaboration scenario* or simply a **scenario**. GNAT recognizes the
62 following scenarios:
63
64 - ``'Access`` of entries, operators, and subprograms
65
66 - Activation of tasks
67
68 - Calls to entries, operators, and subprograms
69
70 - Instantiations of generic templates
71
72 * *Target*
73
74 A construct elaborated by a scenario is referred to as *elaboration target*
75 or simply **target**. GNAT recognizes the following targets:
76
77 - For ``'Access`` of entries, operators, and subprograms, the target is the
78 entry, operator, or subprogram being aliased.
79
80 - For activation of tasks, the target is the task body
81
82 - For calls to entries, operators, and subprograms, the target is the entry,
83 operator, or subprogram being invoked.
84
85 - For instantiations of generic templates, the target is the generic template
86 being instantiated.
87
88 Elaboration code may appear in two distinct contexts:
89
90 * *Library level*
91
92 A scenario appears at the library level when it is encapsulated by a package
93 [body] compilation unit, ignoring any other package [body] declarations in
94 between.
95
96 .. code-block:: ada
97
98 with Server;
99 package Client is
100 procedure Proc;
101
102 package Nested is
103 Val : ... := Server.Func;
104 end Nested;
105 end Client;
106
107 In the example above, the call to ``Server.Func`` is an elaboration scenario
108 because it appears at the library level of package ``Client``. Note that the
109 declaration of package ``Nested`` is ignored according to the definition
110 given above. As a result, the call to ``Server.Func`` will be invoked when
111 the spec of unit ``Client`` is elaborated.
112
113 * *Package body statements*
114
115 A scenario appears within the statement sequence of a package body when it is
116 bounded by the region starting from the ``begin`` keyword of the package body
117 and ending at the ``end`` keyword of the package body.
118
119 .. code-block:: ada
120
121 package body Client is
122 procedure Proc is
123 begin
124 ...
125 end Proc;
126 begin
127 Proc;
128 end Client;
129
130 In the example above, the call to ``Proc`` is an elaboration scenario because
131 it appears within the statement sequence of package body ``Client``. As a
132 result, the call to ``Proc`` will be invoked when the body of ``Client`` is
133 elaborated.
134
135 .. _Elaboration_Order:
136
137 Elaboration Order
138 =================
139
140 The sequence by which the elaboration code of all units within a partition is
141 executed is referred to as **elaboration order**.
142
143 Within a single unit, elaboration code is executed in sequential order.
144
145 .. code-block:: ada
146
147 package body Client is
148 Result : ... := Server.Func;
149
150 procedure Proc is
151 package Inst is new Server.Gen;
152 begin
153 Inst.Eval (Result);
154 end Proc;
155 begin
156 Proc;
157 end Client;
158
159 In the example above, the elaboration order within package body ``Client`` is
160 as follows:
161
162 1. The object declaration of ``Result`` is elaborated.
163
164 * Function ``Server.Func`` is invoked.
165
166 2. The subprogram body of ``Proc`` is elaborated.
167
168 3. Procedure ``Proc`` is invoked.
169
170 * Generic unit ``Server.Gen`` is instantiated as ``Inst``.
171
172 * Instance ``Inst`` is elaborated.
173
174 * Procedure ``Inst.Eval`` is invoked.
175
176 The elaboration order of all units within a partition depends on the following
177 factors:
178
179 * |withed| units
180
181 * parent units
182
183 * purity of units
184
185 * preelaborability of units
186
187 * presence of elaboration-control pragmas
188
189 * invocations performed in elaboration code
190
191 A program may have several elaboration orders depending on its structure.
192
193 .. code-block:: ada
194
195 package Server is
196 function Func (Index : Integer) return Integer;
197 end Server;
198
199 .. code-block:: ada
200
201 package body Server is
202 Results : array (1 .. 5) of Integer := (1, 2, 3, 4, 5);
203
204 function Func (Index : Integer) return Integer is
205 begin
206 return Results (Index);
207 end Func;
208 end Server;
209
210 .. code-block:: ada
211
212 with Server;
213 package Client is
214 Val : constant Integer := Server.Func (3);
215 end Client;
216
217 .. code-block:: ada
218
219 with Client;
220 procedure Main is begin null; end Main;
221
222 The following elaboration order exhibits a fundamental problem referred to as
223 *access-before-elaboration* or simply **ABE**.
224
225 ::
226
227 spec of Server
228 spec of Client
229 body of Server
230 body of Main
231
232 The elaboration of ``Server``'s spec materializes function ``Func``, making it
233 callable. The elaboration of ``Client``'s spec elaborates the declaration of
234 ``Val``. This invokes function ``Server.Func``, however the body of
235 ``Server.Func`` has not been elaborated yet because ``Server``'s body comes
236 after ``Client``'s spec in the elaboration order. As a result, the value of
237 constant ``Val`` is now undefined.
238
239 Without any guarantees from the language, an undetected ABE problem may hinder
240 proper initialization of data, which in turn may lead to undefined behavior at
241 run time. To prevent such ABE problems, Ada employs dynamic checks in the same
242 vein as index or null exclusion checks. A failed ABE check raises exception
243 ``Program_Error``.
244
245 The following elaboration order avoids the ABE problem and the program can be
246 successfully elaborated.
247
248 ::
249
250 spec of Server
251 body of Server
252 spec of Client
253 body of Main
254
255 Ada states that a total elaboration order must exist, but it does not define
256 what this order is. A compiler is thus tasked with choosing a suitable
257 elaboration order which satisfies the dependencies imposed by |with| clauses,
258 unit categorization, elaboration-control pragmas, and invocations performed in
259 elaboration code. Ideally an order that avoids ABE problems should be chosen,
260 however a compiler may not always find such an order due to complications with
261 respect to control and data flow.
262
263 .. _Checking_the_Elaboration_Order:
264
265 Checking the Elaboration Order
266 ==============================
267
268 To avoid placing the entire elaboration-order burden on the programmer, Ada
269 provides three lines of defense:
270
271 * *Static semantics*
272
273 Static semantic rules restrict the possible choice of elaboration order. For
274 instance, if unit Client |withs| unit Server, then the spec of Server is
275 always elaborated prior to Client. The same principle applies to child units
276 - the spec of a parent unit is always elaborated prior to the child unit.
277
278 * *Dynamic semantics*
279
280 Dynamic checks are performed at run time, to ensure that a target is
281 elaborated prior to a scenario that invokes it, thus avoiding ABE problems.
282 A failed run-time check raises exception ``Program_Error``. The following
283 restrictions apply:
284
285 - *Restrictions on calls*
286
287 An entry, operator, or subprogram can be called from elaboration code only
288 when the corresponding body has been elaborated.
289
290 - *Restrictions on instantiations*
291
292 A generic unit can be instantiated by elaboration code only when the
293 corresponding body has been elaborated.
294
295 - *Restrictions on task activation*
296
297 A task can be activated by elaboration code only when the body of the
298 associated task type has been elaborated.
299
300 The restrictions above can be summarized by the following rule:
301
302 *If a target has a body, then this body must be elaborated prior to the
303 scenario that invokes the target.*
304
305 * *Elaboration control*
306
307 Pragmas are provided for the programmer to specify the desired elaboration
308 order.
309
310 .. _Controlling_the_Elaboration_Order_in_Ada:
311
312 Controlling the Elaboration Order in Ada
313 ========================================
314
315 Ada provides several idioms and pragmas to aid the programmer with specifying
316 the desired elaboration order and avoiding ABE problems altogether.
317
318 * *Packages without a body*
319
320 A library package which does not require a completing body does not suffer
321 from ABE problems.
322
323 .. code-block:: ada
324
325 package Pack is
326 generic
327 type Element is private;
328 package Containers is
329 type Element_Array is array (1 .. 10) of Element;
330 end Containers;
331 end Pack;
332
333 In the example above, package ``Pack`` does not require a body because it
334 does not contain any constructs which require completion in a body. As a
335 result, generic ``Pack.Containers`` can be instantiated without encountering
336 any ABE problems.
337
338 .. index:: pragma Pure
339
340 * *pragma Pure*
341
342 Pragma ``Pure`` places sufficient restrictions on a unit to guarantee that no
343 scenario within the unit can result in an ABE problem.
344
345 .. index:: pragma Preelaborate
346
347 * *pragma Preelaborate*
348
349 Pragma ``Preelaborate`` is slightly less restrictive than pragma ``Pure``,
350 but still strong enough to prevent ABE problems within a unit.
351
352 .. index:: pragma Elaborate_Body
353
354 * *pragma Elaborate_Body*
355
356 Pragma ``Elaborate_Body`` requires that the body of a unit is elaborated
357 immediately after its spec. This restriction guarantees that no client
358 scenario can invoke a server target before the target body has been
359 elaborated because the spec and body are effectively "glued" together.
360
361 .. code-block:: ada
362
363 package Server is
364 pragma Elaborate_Body;
365
366 function Func return Integer;
367 end Server;
368
369 .. code-block:: ada
370
371 package body Server is
372 function Func return Integer is
373 begin
374 ...
375 end Func;
376 end Server;
377
378 .. code-block:: ada
379
380 with Server;
381 package Client is
382 Val : constant Integer := Server.Func;
383 end Client;
384
385 In the example above, pragma ``Elaborate_Body`` guarantees the following
386 elaboration order:
387
388 ::
389
390 spec of Server
391 body of Server
392 spec of Client
393
394 because the spec of ``Server`` must be elaborated prior to ``Client`` by
395 virtue of the |with| clause, and in addition the body of ``Server`` must be
396 elaborated immediately after the spec of ``Server``.
397
398 Removing pragma ``Elaborate_Body`` could result in the following incorrect
399 elaboration order:
400
401 ::
402
403 spec of Server
404 spec of Client
405 body of Server
406
407 where ``Client`` invokes ``Server.Func``, but the body of ``Server.Func`` has
408 not been elaborated yet.
409
410 The pragmas outlined above allow a server unit to guarantee safe elaboration
411 use by client units. Thus it is a good rule to mark units as ``Pure`` or
412 ``Preelaborate``, and if this is not possible, mark them as ``Elaborate_Body``.
413
414 There are however situations where ``Pure``, ``Preelaborate``, and
415 ``Elaborate_Body`` are not applicable. Ada provides another set of pragmas for
416 use by client units to help ensure the elaboration safety of server units they
417 depend on.
418
419 .. index:: pragma Elaborate (Unit)
420
421 * *pragma Elaborate (Unit)*
422
423 Pragma ``Elaborate`` can be placed in the context clauses of a unit, after a
424 |with| clause. It guarantees that both the spec and body of its argument will
425 be elaborated prior to the unit with the pragma. Note that other unrelated
426 units may be elaborated in between the spec and the body.
427
428 .. code-block:: ada
429
430 package Server is
431 function Func return Integer;
432 end Server;
433
434 .. code-block:: ada
435
436 package body Server is
437 function Func return Integer is
438 begin
439 ...
440 end Func;
441 end Server;
442
443 .. code-block:: ada
444
445 with Server;
446 pragma Elaborate (Server);
447 package Client is
448 Val : constant Integer := Server.Func;
449 end Client;
450
451 In the example above, pragma ``Elaborate`` guarantees the following
452 elaboration order:
453
454 ::
455
456 spec of Server
457 body of Server
458 spec of Client
459
460 Removing pragma ``Elaborate`` could result in the following incorrect
461 elaboration order:
462
463 ::
464
465 spec of Server
466 spec of Client
467 body of Server
468
469 where ``Client`` invokes ``Server.Func``, but the body of ``Server.Func``
470 has not been elaborated yet.
471
472 .. index:: pragma Elaborate_All (Unit)
473
474 * *pragma Elaborate_All (Unit)*
475
476 Pragma ``Elaborate_All`` is placed in the context clauses of a unit, after
477 a |with| clause. It guarantees that both the spec and body of its argument
478 will be elaborated prior to the unit with the pragma, as well as all units
479 |withed| by the spec and body of the argument, recursively. Note that other
480 unrelated units may be elaborated in between the spec and the body.
481
482 .. code-block:: ada
483
484 package Math is
485 function Factorial (Val : Natural) return Natural;
486 end Math;
487
488 .. code-block:: ada
489
490 package body Math is
491 function Factorial (Val : Natural) return Natural is
492 begin
493 ...;
494 end Factorial;
495 end Math;
496
497 .. code-block:: ada
498
499 package Computer is
500 type Operation_Kind is (None, Op_Factorial);
501
502 function Compute
503 (Val : Natural;
504 Op : Operation_Kind) return Natural;
505 end Computer;
506
507 .. code-block:: ada
508
509 with Math;
510 package body Computer is
511 function Compute
512 (Val : Natural;
513 Op : Operation_Kind) return Natural
514 is
515 if Op = Op_Factorial then
516 return Math.Factorial (Val);
517 end if;
518
519 return 0;
520 end Compute;
521 end Computer;
522
523 .. code-block:: ada
524
525 with Computer;
526 pragma Elaborate_All (Computer);
527 package Client is
528 Val : constant Natural :=
529 Computer.Compute (123, Computer.Op_Factorial);
530 end Client;
531
532 In the example above, pragma ``Elaborate_All`` can result in the following
533 elaboration order:
534
535 ::
536
537 spec of Math
538 body of Math
539 spec of Computer
540 body of Computer
541 spec of Client
542
543 Note that there are several allowable suborders for the specs and bodies of
544 ``Math`` and ``Computer``, but the point is that these specs and bodies will
545 be elaborated prior to ``Client``.
546
547 Removing pragma ``Elaborate_All`` could result in the following incorrect
548 elaboration order:
549
550 ::
551
552 spec of Math
553 spec of Computer
554 body of Computer
555 spec of Client
556 body of Math
557
558 where ``Client`` invokes ``Computer.Compute``, which in turn invokes
559 ``Math.Factorial``, but the body of ``Math.Factorial`` has not been
560 elaborated yet.
561
562 All pragmas shown above can be summarized by the following rule:
563
564 *If a client unit elaborates a server target directly or indirectly, then if
565 the server unit requires a body and does not have pragma Pure, Preelaborate,
566 or Elaborate_Body, then the client unit should have pragma Elaborate or
567 Elaborate_All for the server unit.*
568
569 If the rule outlined above is not followed, then a program may fall in one of
570 the following states:
571
572 * *No elaboration order exists*
573
574 In this case a compiler must diagnose the situation, and refuse to build an
575 executable program.
576
577 * *One or more incorrect elaboration orders exist*
578
579 In this case a compiler can build an executable program, but
580 ``Program_Error`` will be raised when the program is run.
581
582 * *Several elaboration orders exist, some correct, some incorrect*
583
584 In this case the programmer has not controlled the elaboration order. As a
585 result, a compiler may or may not pick one of the correct orders, and the
586 program may or may not raise ``Program_Error`` when it is run. This is the
587 worst possible state because the program may fail on another compiler, or
588 even another version of the same compiler.
589
590 * *One or more correct orders exist*
591
592 In this case a compiler can build an executable program, and the program is
593 run successfully. This state may be guaranteed by following the outlined
594 rules, or may be the result of good program architecture.
595
596 Note that one additional advantage of using ``Elaborate`` and ``Elaborate_All``
597 is that the program continues to stay in the last state (one or more correct
598 orders exist) even if maintenance changes the bodies of targets.
599
600 .. _Controlling_the_Elaboration_Order_in_GNAT:
601
602 Controlling the Elaboration Order in GNAT
603 =========================================
604
605 In addition to Ada semantics and rules synthesized from them, GNAT offers
606 three elaboration models to aid the programmer with specifying the correct
607 elaboration order and to diagnose elaboration problems.
608
609 .. index:: Dynamic elaboration model
610
611 * *Dynamic elaboration model*
612
613 This is the most permissive of the three elaboration models and emulates the
614 behavior specified by the Ada Reference Manual. When the dynamic model is in
615 effect, GNAT makes the following assumptions:
616
617 - All code within all units in a partition is considered to be elaboration
618 code.
619
620 - Some of the invocations in elaboration code may not take place at run time
621 due to conditional execution.
622
623 GNAT performs extensive diagnostics on a unit-by-unit basis for all scenarios
624 that invoke internal targets. In addition, GNAT generates run-time checks for
625 all external targets and for all scenarios that may exhibit ABE problems.
626
627 The elaboration order is obtained by honoring all |with| clauses, purity and
628 preelaborability of units, and elaboration-control pragmas. The dynamic model
629 attempts to take all invocations in elaboration code into account. If an
630 invocation leads to a circularity, GNAT ignores the invocation based on the
631 assumptions stated above. An order obtained using the dynamic model may fail
632 an ABE check at run time when GNAT ignored an invocation.
633
634 The dynamic model is enabled with compiler switch :switch:`-gnatE`.
635
636 .. index:: Static elaboration model
637
638 * *Static elaboration model*
639
640 This is the middle ground of the three models. When the static model is in
641 effect, GNAT makes the following assumptions:
642
643 - Only code at the library level and in package body statements within all
644 units in a partition is considered to be elaboration code.
645
646 - All invocations in elaboration will take place at run time, regardless of
647 conditional execution.
648
649 GNAT performs extensive diagnostics on a unit-by-unit basis for all scenarios
650 that invoke internal targets. In addition, GNAT generates run-time checks for
651 all external targets and for all scenarios that may exhibit ABE problems.
652
653 The elaboration order is obtained by honoring all |with| clauses, purity and
654 preelaborability of units, presence of elaboration-control pragmas, and all
655 invocations in elaboration code. An order obtained using the static model is
656 guaranteed to be ABE problem-free, excluding dispatching calls and
657 access-to-subprogram types.
658
659 The static model is the default model in GNAT.
660
661 .. index:: SPARK elaboration model
662
663 * *SPARK elaboration model*
664
665 This is the most conservative of the three models and enforces the SPARK
666 rules of elaboration as defined in the SPARK Reference Manual, section 7.7.
667 The SPARK model is in effect only when a scenario and a target reside in a
668 region subject to ``SPARK_Mode On``, otherwise the dynamic or static model
669 is in effect.
670
671 The SPARK model is enabled with compiler switch :switch:`-gnatd.v`.
672
673 .. index:: Legacy elaboration models
674
675 * *Legacy elaboration models*
676
677 In addition to the three elaboration models outlined above, GNAT provides the
678 following legacy models:
679
680 - `Legacy elaboration-checking model` available in pre-18.x versions of GNAT.
681 This model is enabled with compiler switch :switch:`-gnatH`.
682
683 - `Legacy elaboration-order model` available in pre-20.x versions of GNAT.
684 This model is enabled with binder switch :switch:`-H`.
685
686 .. index:: Relaxed elaboration mode
687
688 The dynamic, legacy, and static models can be relaxed using compiler switch
689 :switch:`-gnatJ`, making them more permissive. Note that in this mode, GNAT
690 may not diagnose certain elaboration issues or install run-time checks.
691
692 .. _Mixing_Elaboration_Models:
693
694 Mixing Elaboration Models
695 =========================
696
697 It is possible to mix units compiled with a different elaboration model,
698 however the following rules must be observed:
699
700 * A client unit compiled with the dynamic model can only |with| a server unit
701 that meets at least one of the following criteria:
702
703 - The server unit is compiled with the dynamic model.
704
705 - The server unit is a GNAT implementation unit from the ``Ada``, ``GNAT``,
706 ``Interfaces``, or ``System`` hierarchies.
707
708 - The server unit has pragma ``Pure`` or ``Preelaborate``.
709
710 - The client unit has an explicit ``Elaborate_All`` pragma for the server
711 unit.
712
713 These rules ensure that elaboration checks are not omitted. If the rules are
714 violated, the binder emits a warning:
715
716 ::
717
718 warning: "x.ads" has dynamic elaboration checks and with's
719 warning: "y.ads" which has static elaboration checks
720
721 The warnings can be suppressed by binder switch :switch:`-ws`.
722
723 .. _ABE_Diagnostics:
724
725 ABE Diagnostics
726 ===============
727
728 GNAT performs extensive diagnostics on a unit-by-unit basis for all scenarios
729 that invoke internal targets, regardless of whether the dynamic, SPARK, or
730 static model is in effect.
731
732 Note that GNAT emits warnings rather than hard errors whenever it encounters an
733 elaboration problem. This is because the elaboration model in effect may be too
734 conservative, or a particular scenario may not be invoked due conditional
735 execution. The warnings can be suppressed selectively with ``pragma Warnings
736 (Off)`` or globally with compiler switch :switch:`-gnatwL`.
737
738 A *guaranteed ABE* arises when the body of a target is not elaborated early
739 enough, and causes *all* scenarios that directly invoke the target to fail.
740
741 .. code-block:: ada
742
743 package body Guaranteed_ABE is
744 function ABE return Integer;
745
746 Val : constant Integer := ABE;
747
748 function ABE return Integer is
749 begin
750 ...
751 end ABE;
752 end Guaranteed_ABE;
753
754 In the example above, the elaboration of ``Guaranteed_ABE``'s body elaborates
755 the declaration of ``Val``. This invokes function ``ABE``, however the body of
756 ``ABE`` has not been elaborated yet. GNAT emits the following diagnostic:
757
758 ::
759
760 4. Val : constant Integer := ABE;
761 |
762 >>> warning: cannot call "ABE" before body seen
763 >>> warning: Program_Error will be raised at run time
764
765 A *conditional ABE* arises when the body of a target is not elaborated early
766 enough, and causes *some* scenarios that directly invoke the target to fail.
767
768 .. code-block:: ada
769
770 1. package body Conditional_ABE is
771 2. procedure Force_Body is null;
772 3.
773 4. generic
774 5. with function Func return Integer;
775 6. package Gen is
776 7. Val : constant Integer := Func;
777 8. end Gen;
778 9.
779 10. function ABE return Integer;
780 11.
781 12. function Cause_ABE return Boolean is
782 13. package Inst is new Gen (ABE);
783 14. begin
784 15. ...
785 16. end Cause_ABE;
786 17.
787 18. Val : constant Boolean := Cause_ABE;
788 19.
789 20. function ABE return Integer is
790 21. begin
791 22. ...
792 23. end ABE;
793 24.
794 25. Safe : constant Boolean := Cause_ABE;
795 26. end Conditional_ABE;
796
797 In the example above, the elaboration of package body ``Conditional_ABE``
798 elaborates the declaration of ``Val``. This invokes function ``Cause_ABE``,
799 which instantiates generic unit ``Gen`` as ``Inst``. The elaboration of
800 ``Inst`` invokes function ``ABE``, however the body of ``ABE`` has not been
801 elaborated yet. GNAT emits the following diagnostic:
802
803 ::
804
805 13. package Inst is new Gen (ABE);
806 |
807 >>> warning: in instantiation at line 7
808 >>> warning: cannot call "ABE" before body seen
809 >>> warning: Program_Error may be raised at run time
810 >>> warning: body of unit "Conditional_ABE" elaborated
811 >>> warning: function "Cause_ABE" called at line 18
812 >>> warning: function "ABE" called at line 7, instance at line 13
813
814 Note that the same ABE problem does not occur with the elaboration of
815 declaration ``Safe`` because the body of function ``ABE`` has already been
816 elaborated at that point.
817
818 .. _SPARK_Diagnostics:
819
820 SPARK Diagnostics
821 =================
822
823 GNAT enforces the SPARK rules of elaboration as defined in the SPARK Reference
824 Manual section 7.7 when compiler switch :switch:`-gnatd.v` is in effect. Note
825 that GNAT emits hard errors whenever it encounters a violation of the SPARK
826 rules.
827
828 ::
829
830 1. with Server;
831 2. package body SPARK_Diagnostics with SPARK_Mode is
832 3. Val : constant Integer := Server.Func;
833 |
834 >>> call to "Func" during elaboration in SPARK
835 >>> unit "SPARK_Diagnostics" requires pragma "Elaborate_All" for "Server"
836 >>> body of unit "SPARK_Model" elaborated
837 >>> function "Func" called at line 3
838
839 4. end SPARK_Diagnostics;
840
841 .. _Elaboration_Circularities:
842
843 Elaboration Circularities
844 =========================
845
846 An **elaboration circularity** occurs whenever the elaboration of a set of
847 units enters a deadlocked state, where each unit is waiting for another unit
848 to be elaborated. This situation may be the result of improper use of |with|
849 clauses, elaboration-control pragmas, or invocations in elaboration code.
850
851 The following example exhibits an elaboration circularity.
852
853 .. code-block:: ada
854
855 with B; pragma Elaborate (B);
856 package A is
857 end A;
858
859 .. code-block:: ada
860
861 package B is
862 procedure Force_Body;
863 end B;
864
865 .. code-block:: ada
866
867 with C;
868 package body B is
869 procedure Force_Body is null;
870
871 Elab : constant Integer := C.Func;
872 end B;
873
874 .. code-block:: ada
875
876 package C is
877 function Func return Integer;
878 end C;
879
880 .. code-block:: ada
881
882 with A;
883 package body C is
884 function Func return Integer is
885 begin
886 ...
887 end Func;
888 end C;
889
890 The binder emits the following diagnostic:
891
892 ::
893
894 error: Elaboration circularity detected
895 info:
896 info: Reason:
897 info:
898 info: unit "a (spec)" depends on its own elaboration
899 info:
900 info: Circularity:
901 info:
902 info: unit "a (spec)" has with clause and pragma Elaborate for unit "b (spec)"
903 info: unit "b (body)" is in the closure of pragma Elaborate
904 info: unit "b (body)" invokes a construct of unit "c (body)" at elaboration time
905 info: unit "c (body)" has with clause for unit "a (spec)"
906 info:
907 info: Suggestions:
908 info:
909 info: remove pragma Elaborate for unit "b (body)" in unit "a (spec)"
910 info: use the dynamic elaboration model (compiler switch -gnatE)
911
912 The diagnostic consist of the following sections:
913
914 * Reason
915
916 This section provides a short explanation describing why the set of units
917 could not be ordered.
918
919 * Circularity
920
921 This section enumerates the units comprising the deadlocked set, along with
922 their interdependencies.
923
924 * Suggestions
925
926 This section enumerates various tactics for eliminating the circularity.
927
928 .. _Resolving_Elaboration_Circularities:
929
930 Resolving Elaboration Circularities
931 ===================================
932
933 The most desirable option from the point of view of long-term maintenance is to
934 rearrange the program so that the elaboration problems are avoided. One useful
935 technique is to place the elaboration code into separate child packages.
936 Another is to move some of the initialization code to explicitly invoked
937 subprograms, where the program controls the order of initialization explicitly.
938 Although this is the most desirable option, it may be impractical and involve
939 too much modification, especially in the case of complex legacy code.
940
941 When faced with an elaboration circularity, the programmer should also consider
942 the tactics given in the suggestions section of the circularity diagnostic.
943 Depending on the units involved in the circularity, their |with| clauses,
944 purity, preelaborability, presence of elaboration-control pragmas and
945 invocations at elaboration time, the binder may suggest one or more of the
946 following tactics to eliminate the circularity:
947
948 * Pragma Elaborate elimination
949
950 ::
951
952 remove pragma Elaborate for unit "..." in unit "..."
953
954 This tactic is suggested when the binder has determined that pragma
955 ``Elaborate``:
956
957 - Prevents a set of units from being elaborated.
958
959 - The removal of the pragma will not eliminate the semantic effects of the
960 pragma. In other words, the argument of the pragma will still be elaborated
961 prior to the unit containing the pragma.
962
963 - The removal of the pragma will enable the successful ordering of the units.
964
965 The programmer should remove the pragma as advised, and rebuild the program.
966
967 * Pragma Elaborate_All elimination
968
969 ::
970
971 remove pragma Elaborate_All for unit "..." in unit "..."
972
973 This tactic is suggested when the binder has determined that pragma
974 ``Elaborate_All``:
975
976 - Prevents a set of units from being elaborated.
977
978 - The removal of the pragma will not eliminate the semantic effects of the
979 pragma. In other words, the argument of the pragma along with its |with|
980 closure will still be elaborated prior to the unit containing the pragma.
981
982 - The removal of the pragma will enable the successful ordering of the units.
983
984 The programmer should remove the pragma as advised, and rebuild the program.
985
986 * Pragma Elaborate_All downgrade
987
988 ::
989
990 change pragma Elaborate_All for unit "..." to Elaborate in unit "..."
991
992 This tactic is always suggested with the pragma ``Elaborate_All`` elimination
993 tactic. It offers a different alternative of guaranteeing that the argument
994 of the pragma will still be elaborated prior to the unit containing the
995 pragma.
996
997 The programmer should update the pragma as advised, and rebuild the program.
998
999 * Pragma Elaborate_Body elimination
1000
1001 ::
1002
1003 remove pragma Elaborate_Body in unit "..."
1004
1005 This tactic is suggested when the binder has determined that pragma
1006 ``Elaborate_Body``:
1007
1008 - Prevents a set of units from being elaborated.
1009
1010 - The removal of the pragma will enable the successful ordering of the units.
1011
1012 Note that the binder cannot determine whether the pragma is required for
1013 other purposes, such as guaranteeing the initialization of a variable
1014 declared in the spec by elaboration code in the body.
1015
1016 The programmer should remove the pragma as advised, and rebuild the program.
1017
1018 * Use of pragma Restrictions
1019
1020 ::
1021
1022 use pragma Restrictions (No_Entry_Calls_In_Elaboration_Code)
1023
1024 This tactic is suggested when the binder has determined that a task
1025 activation at elaboration time:
1026
1027 - Prevents a set of units from being elaborated.
1028
1029 Note that the binder cannot determine with certainty whether the task will
1030 block at elaboration time.
1031
1032 The programmer should create a configuration file, place the pragma within,
1033 update the general compilation arguments, and rebuild the program.
1034
1035 * Use of dynamic elaboration model
1036
1037 ::
1038
1039 use the dynamic elaboration model (compiler switch -gnatE)
1040
1041 This tactic is suggested when the binder has determined that an invocation at
1042 elaboration time:
1043
1044 - Prevents a set of units from being elaborated.
1045
1046 - The use of the dynamic model will enable the successful ordering of the
1047 units.
1048
1049 The programmer has two options:
1050
1051 - Determine the units involved in the invocation using the detailed
1052 invocation information, and add compiler switch :switch:`-gnatE` to the
1053 compilation arguments of selected files only. This approach will yield
1054 safer elaboration orders compared to the other option because it will
1055 minimize the opportunities presented to the dynamic model for ignoring
1056 invocations.
1057
1058 - Add compiler switch :switch:`-gnatE` to the general compilation arguments.
1059
1060 * Use of detailed invocation information
1061
1062 ::
1063
1064 use detailed invocation information (compiler switch -gnatd_F)
1065
1066 This tactic is always suggested with the use of the dynamic model tactic. It
1067 causes the circularity section of the circularity diagnostic to describe the
1068 flow of elaboration code from a unit to a unit, enumerating all such paths in
1069 the process.
1070
1071 The programmer should analyze this information to determine which units
1072 should be compiled with the dynamic model.
1073
1074 * Forced-dependency elimination
1075
1076 ::
1077
1078 remove the dependency of unit "..." on unit "..." from the argument of switch -f
1079
1080 This tactic is suggested when the binder has determined that a dependency
1081 present in the forced-elaboration-order file indicated by binder switch
1082 :switch:`-f`:
1083
1084 - Prevents a set of units from being elaborated.
1085
1086 - The removal of the dependency will enable the successful ordering of the
1087 units.
1088
1089 The programmer should edit the forced-elaboration-order file, remove the
1090 dependency, and rebind the program.
1091
1092 * All forced-dependency elimination
1093
1094 ::
1095
1096 remove switch -f
1097
1098 This tactic is suggested in case editing the forced-elaboration-order file is
1099 not an option.
1100
1101 The programmer should remove binder switch :switch:`-f` from the binder
1102 arguments, and rebind.
1103
1104 * Multiple-circularities diagnostic
1105
1106 ::
1107
1108 diagnose all circularities (binder switch -d_C)
1109
1110 By default, the binder will diagnose only the highest-precedence circularity.
1111 If the program contains multiple circularities, the binder will suggest the
1112 use of binder switch :switch:`-d_C` in order to obtain the diagnostics of all
1113 circularities.
1114
1115 The programmer should add binder switch :switch:`-d_C` to the binder
1116 arguments, and rebind.
1117
1118 If none of the tactics suggested by the binder eliminate the elaboration
1119 circularity, the programmer should consider using one of the legacy elaboration
1120 models, in the following order:
1121
1122 * Use the pre-20.x legacy elaboration-order model, with binder switch
1123 :switch:`-H`.
1124
1125 * Use both pre-18.x and pre-20.x legacy elaboration models, with compiler
1126 switch :switch:`-gnatH` and binder switch :switch:`-H`.
1127
1128 * Use the relaxed static-elaboration model, with compiler switches
1129 :switch:`-gnatH` :switch:`-gnatJ` and binder switch :switch:`-H`.
1130
1131 * Use the relaxed dynamic-elaboration model, with compiler switches
1132 :switch:`-gnatH` :switch:`-gnatJ` :switch:`-gnatE` and binder switch
1133 :switch:`-H`.
1134
1135 .. _Elaboration_Related_Compiler_Switches:
1136
1137 Elaboration-related Compiler Switches
1138 =====================================
1139
1140 GNAT has several switches that affect the elaboration model and consequently
1141 the elaboration order chosen by the binder.
1142
1143 .. index:: -gnatE (gnat)
1144
1145 :switch:`-gnatE`
1146 Dynamic elaboration checking mode enabled
1147
1148 When this switch is in effect, GNAT activates the dynamic model.
1149
1150 .. index:: -gnatel (gnat)
1151
1152 :switch:`-gnatel`
1153 Turn on info messages on generated Elaborate[_All] pragmas
1154
1155 This switch is only applicable to the pre-20.x legacy elaboration models.
1156 The post-20.x elaboration model no longer relies on implicitly generated
1157 ``Elaborate`` and ``Elaborate_All`` pragmas to order units.
1158
1159 When this switch is in effect, GNAT will emit the following supplementary
1160 information depending on the elaboration model in effect.
1161
1162 - *Dynamic model*
1163
1164 GNAT will indicate missing ``Elaborate`` and ``Elaborate_All`` pragmas for
1165 all library-level scenarios within the partition.
1166
1167 - *Static model*
1168
1169 GNAT will indicate all scenarios invoked during elaboration. In addition,
1170 it will provide detailed traceback when an implicit ``Elaborate`` or
1171 ``Elaborate_All`` pragma is generated.
1172
1173 - *SPARK model*
1174
1175 GNAT will indicate how an elaboration requirement is met by the context of
1176 a unit. This diagnostic requires compiler switch :switch:`-gnatd.v`.
1177
1178 ::
1179
1180 1. with Server; pragma Elaborate_All (Server);
1181 2. package Client with SPARK_Mode is
1182 3. Val : constant Integer := Server.Func;
1183 |
1184 >>> info: call to "Func" during elaboration in SPARK
1185 >>> info: "Elaborate_All" requirement for unit "Server" met by pragma at line 1
1186
1187 4. end Client;
1188
1189 .. index:: -gnatH (gnat)
1190
1191 :switch:`-gnatH`
1192 Legacy elaboration checking mode enabled
1193
1194 When this switch is in effect, GNAT will utilize the pre-18.x elaboration
1195 model.
1196
1197 .. index:: -gnatJ (gnat)
1198
1199 :switch:`-gnatJ`
1200 Relaxed elaboration checking mode enabled
1201
1202 When this switch is in effect, GNAT will not process certain scenarios,
1203 resulting in a more permissive elaboration model. Note that this may
1204 eliminate some diagnostics and run-time checks.
1205
1206 .. index:: -gnatw.f (gnat)
1207
1208 :switch:`-gnatw.f`
1209 Turn on warnings for suspicious Subp'Access
1210
1211 When this switch is in effect, GNAT will treat ``'Access`` of an entry,
1212 operator, or subprogram as a potential call to the target and issue warnings:
1213
1214 ::
1215
1216 1. package body Attribute_Call is
1217 2. function Func return Integer;
1218 3. type Func_Ptr is access function return Integer;
1219 4.
1220 5. Ptr : constant Func_Ptr := Func'Access;
1221 |
1222 >>> warning: "Access" attribute of "Func" before body seen
1223 >>> warning: possible Program_Error on later references
1224 >>> warning: body of unit "Attribute_Call" elaborated
1225 >>> warning: "Access" of "Func" taken at line 5
1226
1227 6.
1228 7. function Func return Integer is
1229 8. begin
1230 9. ...
1231 10. end Func;
1232 11. end Attribute_Call;
1233
1234 In the example above, the elaboration of declaration ``Ptr`` is assigned
1235 ``Func'Access`` before the body of ``Func`` has been elaborated.
1236
1237 .. index:: -gnatwl (gnat)
1238
1239 :switch:`-gnatwl`
1240 Turn on warnings for elaboration problems
1241
1242 When this switch is in effect, GNAT emits diagnostics in the form of warnings
1243 concerning various elaboration problems. The warnings are enabled by default.
1244 The switch is provided in case all warnings are suppressed, but elaboration
1245 warnings are still desired.
1246
1247 :switch:`-gnatwL`
1248 Turn off warnings for elaboration problems
1249
1250 When this switch is in effect, GNAT no longer emits any diagnostics in the
1251 form of warnings. Selective suppression of elaboration problems is possible
1252 using ``pragma Warnings (Off)``.
1253
1254 ::
1255
1256 1. package body Selective_Suppression is
1257 2. function ABE return Integer;
1258 3.
1259 4. Val_1 : constant Integer := ABE;
1260 |
1261 >>> warning: cannot call "ABE" before body seen
1262 >>> warning: Program_Error will be raised at run time
1263
1264 5.
1265 6. pragma Warnings (Off);
1266 7. Val_2 : constant Integer := ABE;
1267 8. pragma Warnings (On);
1268 9.
1269 10. function ABE return Integer is
1270 11. begin
1271 12. ...
1272 13. end ABE;
1273 14. end Selective_Suppression;
1274
1275 Note that suppressing elaboration warnings does not eliminate run-time
1276 checks. The example above will still fail at run time with an ABE.
1277
1278 .. _Summary_of_Procedures_for_Elaboration_Control:
1279
1280 Summary of Procedures for Elaboration Control
1281 =============================================
1282
1283 A programmer should first compile the program with the default options, using
1284 none of the binder or compiler switches. If the binder succeeds in finding an
1285 elaboration order, then apart from possible cases involving dispatching calls
1286 and access-to-subprogram types, the program is free of elaboration errors.
1287
1288 If it is important for the program to be portable to compilers other than GNAT,
1289 then the programmer should use compiler switch :switch:`-gnatel` and consider
1290 the messages about missing or implicitly created ``Elaborate`` and
1291 ``Elaborate_All`` pragmas.
1292
1293 If the binder reports an elaboration circularity, the programmer has several
1294 options:
1295
1296 * Ensure that elaboration warnings are enabled. This will allow the static
1297 model to output trace information of elaboration issues. The trace
1298 information could shed light on previously unforeseen dependencies, as well
1299 as their origins. Elaboration warnings are enabled with compiler switch
1300 :switch:`-gnatwl`.
1301
1302 * Cosider the tactics given in the suggestions section of the circularity
1303 diagnostic.
1304
1305 * If none of the steps outlined above resolve the circularity, use a more
1306 permissive elaboration model, in the following order:
1307
1308 - Use the pre-20.x legacy elaboration-order model, with binder switch
1309 :switch:`-H`.
1310
1311 - Use both pre-18.x and pre-20.x legacy elaboration models, with compiler
1312 switch :switch:`-gnatH` and binder switch :switch:`-H`.
1313
1314 - Use the relaxed static elaboration model, with compiler switches
1315 :switch:`-gnatH` :switch:`-gnatJ` and binder switch :switch:`-H`.
1316
1317 - Use the relaxed dynamic elaboration model, with compiler switches
1318 :switch:`-gnatH` :switch:`-gnatJ` :switch:`-gnatE` and binder switch
1319 :switch:`-H`.
1320
1321 .. _Inspecting_the_Chosen_Elaboration_Order:
1322
1323 Inspecting the Chosen Elaboration Order
1324 =======================================
1325
1326 To see the elaboration order chosen by the binder, inspect the contents of file
1327 `b~xxx.adb`. On certain targets, this file appears as `b_xxx.adb`. The
1328 elaboration order appears as a sequence of calls to ``Elab_Body`` and
1329 ``Elab_Spec``, interspersed with assignments to `Exxx` which indicates that a
1330 particular unit is elaborated. For example:
1331
1332 ::
1333
1334 System.Soft_Links'Elab_Body;
1335 E14 := True;
1336 System.Secondary_Stack'Elab_Body;
1337 E18 := True;
1338 System.Exception_Table'Elab_Body;
1339 E24 := True;
1340 Ada.Io_Exceptions'Elab_Spec;
1341 E67 := True;
1342 Ada.Tags'Elab_Spec;
1343 Ada.Streams'Elab_Spec;
1344 E43 := True;
1345 Interfaces.C'Elab_Spec;
1346 E69 := True;
1347 System.Finalization_Root'Elab_Spec;
1348 E60 := True;
1349 System.Os_Lib'Elab_Body;
1350 E71 := True;
1351 System.Finalization_Implementation'Elab_Spec;
1352 System.Finalization_Implementation'Elab_Body;
1353 E62 := True;
1354 Ada.Finalization'Elab_Spec;
1355 E58 := True;
1356 Ada.Finalization.List_Controller'Elab_Spec;
1357 E76 := True;
1358 System.File_Control_Block'Elab_Spec;
1359 E74 := True;
1360 System.File_Io'Elab_Body;
1361 E56 := True;
1362 Ada.Tags'Elab_Body;
1363 E45 := True;
1364 Ada.Text_Io'Elab_Spec;
1365 Ada.Text_Io'Elab_Body;
1366 E07 := True;
1367
1368 Note also binder switch :switch:`-l`, which outputs the chosen elaboration
1369 order and provides a more readable form of the above:
1370
1371 ::
1372
1373 ada (spec)
1374 interfaces (spec)
1375 system (spec)
1376 system.case_util (spec)
1377 system.case_util (body)
1378 system.concat_2 (spec)
1379 system.concat_2 (body)
1380 system.concat_3 (spec)
1381 system.concat_3 (body)
1382 system.htable (spec)
1383 system.parameters (spec)
1384 system.parameters (body)
1385 system.crtl (spec)
1386 interfaces.c_streams (spec)
1387 interfaces.c_streams (body)
1388 system.restrictions (spec)
1389 system.restrictions (body)
1390 system.standard_library (spec)
1391 system.exceptions (spec)
1392 system.exceptions (body)
1393 system.storage_elements (spec)
1394 system.storage_elements (body)
1395 system.secondary_stack (spec)
1396 system.stack_checking (spec)
1397 system.stack_checking (body)
1398 system.string_hash (spec)
1399 system.string_hash (body)
1400 system.htable (body)
1401 system.strings (spec)
1402 system.strings (body)
1403 system.traceback (spec)
1404 system.traceback (body)
1405 system.traceback_entries (spec)
1406 system.traceback_entries (body)
1407 ada.exceptions (spec)
1408 ada.exceptions.last_chance_handler (spec)
1409 system.soft_links (spec)
1410 system.soft_links (body)
1411 ada.exceptions.last_chance_handler (body)
1412 system.secondary_stack (body)
1413 system.exception_table (spec)
1414 system.exception_table (body)
1415 ada.io_exceptions (spec)
1416 ada.tags (spec)
1417 ada.streams (spec)
1418 interfaces.c (spec)
1419 interfaces.c (body)
1420 system.finalization_root (spec)
1421 system.finalization_root (body)
1422 system.memory (spec)
1423 system.memory (body)
1424 system.standard_library (body)
1425 system.os_lib (spec)
1426 system.os_lib (body)
1427 system.unsigned_types (spec)
1428 system.stream_attributes (spec)
1429 system.stream_attributes (body)
1430 system.finalization_implementation (spec)
1431 system.finalization_implementation (body)
1432 ada.finalization (spec)
1433 ada.finalization (body)
1434 ada.finalization.list_controller (spec)
1435 ada.finalization.list_controller (body)
1436 system.file_control_block (spec)
1437 system.file_io (spec)
1438 system.file_io (body)
1439 system.val_uns (spec)
1440 system.val_util (spec)
1441 system.val_util (body)
1442 system.val_uns (body)
1443 system.wch_con (spec)
1444 system.wch_con (body)
1445 system.wch_cnv (spec)
1446 system.wch_jis (spec)
1447 system.wch_jis (body)
1448 system.wch_cnv (body)
1449 system.wch_stw (spec)
1450 system.wch_stw (body)
1451 ada.tags (body)
1452 ada.exceptions (body)
1453 ada.text_io (spec)
1454 ada.text_io (body)
1455 text_io (spec)
1456 gdbstr (body)