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