|
111
|
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 * *Scenario*
|
|
|
54
|
|
|
55 A construct that is elaborated or executed by elaboration code is referred to
|
|
|
56 as an *elaboration scenario* or simply a **scenario**. GNAT recognizes the
|
|
|
57 following scenarios:
|
|
|
58
|
|
|
59 - ``'Access`` of entries, operators, and subprograms
|
|
|
60
|
|
|
61 - Activation of tasks
|
|
|
62
|
|
|
63 - Calls to entries, operators, and subprograms
|
|
|
64
|
|
|
65 - Instantiations of generic templates
|
|
|
66
|
|
|
67 * *Target*
|
|
|
68
|
|
|
69 A construct elaborated by a scenario is referred to as *elaboration target*
|
|
|
70 or simply **target**. GNAT recognizes the following targets:
|
|
|
71
|
|
|
72 - For ``'Access`` of entries, operators, and subprograms, the target is the
|
|
|
73 entry, operator, or subprogram being aliased.
|
|
|
74
|
|
|
75 - For activation of tasks, the target is the task body
|
|
|
76
|
|
|
77 - For calls to entries, operators, and subprograms, the target is the entry,
|
|
|
78 operator, or subprogram being invoked.
|
|
|
79
|
|
|
80 - For instantiations of generic templates, the target is the generic template
|
|
|
81 being instantiated.
|
|
|
82
|
|
|
83 Elaboration code may appear in two distinct contexts:
|
|
|
84
|
|
|
85 * *Library level*
|
|
|
86
|
|
|
87 A scenario appears at the library level when it is encapsulated by a package
|
|
|
88 [body] compilation unit, ignoring any other package [body] declarations in
|
|
|
89 between.
|
|
|
90
|
|
|
91 ::
|
|
|
92
|
|
|
93 with Server;
|
|
|
94 package Client is
|
|
|
95 procedure Proc;
|
|
|
96
|
|
|
97 package Nested is
|
|
|
98 Val : ... := Server.Func;
|
|
|
99 end Nested;
|
|
|
100 end Client;
|
|
|
101
|
|
|
102 In the example above, the call to ``Server.Func`` is an elaboration scenario
|
|
|
103 because it appears at the library level of package ``Client``. Note that the
|
|
|
104 declaration of package ``Nested`` is ignored according to the definition
|
|
|
105 given above. As a result, the call to ``Server.Func`` will be executed when
|
|
|
106 the spec of unit ``Client`` is elaborated.
|
|
|
107
|
|
|
108 * *Package body statements*
|
|
|
109
|
|
|
110 A scenario appears within the statement sequence of a package body when it is
|
|
|
111 bounded by the region starting from the ``begin`` keyword of the package body
|
|
|
112 and ending at the ``end`` keyword of the package body.
|
|
|
113
|
|
|
114 ::
|
|
|
115
|
|
|
116 package body Client is
|
|
|
117 procedure Proc is
|
|
|
118 begin
|
|
|
119 ...
|
|
|
120 end Proc;
|
|
|
121 begin
|
|
|
122 Proc;
|
|
|
123 end Client;
|
|
|
124
|
|
|
125 In the example above, the call to ``Proc`` is an elaboration scenario because
|
|
|
126 it appears within the statement sequence of package body ``Client``. As a
|
|
|
127 result, the call to ``Proc`` will be executed when the body of ``Client`` is
|
|
|
128 elaborated.
|
|
|
129
|
|
|
130 .. _Elaboration_Order:
|
|
|
131
|
|
|
132 Elaboration Order
|
|
|
133 =================
|
|
|
134
|
|
|
135 The sequence by which the elaboration code of all units within a partition is
|
|
|
136 executed is referred to as **elaboration order**.
|
|
|
137
|
|
|
138 Within a single unit, elaboration code is executed in sequential order.
|
|
|
139
|
|
|
140 ::
|
|
|
141
|
|
|
142 package body Client is
|
|
|
143 Result : ... := Server.Func;
|
|
|
144
|
|
|
145 procedure Proc is
|
|
|
146 package Inst is new Server.Gen;
|
|
|
147 begin
|
|
|
148 Inst.Eval (Result);
|
|
|
149 end Proc;
|
|
|
150 begin
|
|
|
151 Proc;
|
|
|
152 end Client;
|
|
|
153
|
|
|
154 In the example above, the elaboration order within package body ``Client`` is
|
|
|
155 as follows:
|
|
|
156
|
|
|
157 1. The object declaration of ``Result`` is elaborated.
|
|
|
158
|
|
|
159 * Function ``Server.Func`` is invoked.
|
|
|
160
|
|
|
161 2. The subprogram body of ``Proc`` is elaborated.
|
|
|
162
|
|
|
163 3. Procedure ``Proc`` is invoked.
|
|
|
164
|
|
|
165 * Generic unit ``Server.Gen`` is instantiated as ``Inst``.
|
|
|
166
|
|
|
167 * Instance ``Inst`` is elaborated.
|
|
|
168
|
|
|
169 * Procedure ``Inst.Eval`` is invoked.
|
|
|
170
|
|
|
171 The elaboration order of all units within a partition depends on the following
|
|
|
172 factors:
|
|
|
173
|
|
|
174 * |withed| units
|
|
|
175
|
|
|
176 * purity of units
|
|
|
177
|
|
|
178 * preelaborability of units
|
|
|
179
|
|
|
180 * presence of elaboration control pragmas
|
|
|
181
|
|
|
182 A program may have several elaboration orders depending on its structure.
|
|
|
183
|
|
|
184 ::
|
|
|
185
|
|
|
186 package Server is
|
|
|
187 function Func (Index : Integer) return Integer;
|
|
|
188 end Server;
|
|
|
189
|
|
|
190 ::
|
|
|
191
|
|
|
192 package body Server is
|
|
|
193 Results : array (1 .. 5) of Integer := (1, 2, 3, 4, 5);
|
|
|
194
|
|
|
195 function Func (Index : Integer) return Integer is
|
|
|
196 begin
|
|
|
197 return Results (Index);
|
|
|
198 end Func;
|
|
|
199 end Server;
|
|
|
200
|
|
|
201 ::
|
|
|
202
|
|
|
203 with Server;
|
|
|
204 package Client is
|
|
|
205 Val : constant Integer := Server.Func (3);
|
|
|
206 end Client;
|
|
|
207
|
|
|
208 ::
|
|
|
209
|
|
|
210 with Client;
|
|
|
211 procedure Main is begin null; end Main;
|
|
|
212
|
|
|
213 The following elaboration order exhibits a fundamental problem referred to as
|
|
|
214 *access-before-elaboration* or simply **ABE**.
|
|
|
215
|
|
|
216 ::
|
|
|
217
|
|
|
218 spec of Server
|
|
|
219 spec of Client
|
|
|
220 body of Server
|
|
|
221 body of Main
|
|
|
222
|
|
|
223 The elaboration of ``Server``'s spec materializes function ``Func``, making it
|
|
|
224 callable. The elaboration of ``Client``'s spec elaborates the declaration of
|
|
|
225 ``Val``. This invokes function ``Server.Func``, however the body of
|
|
|
226 ``Server.Func`` has not been elaborated yet because ``Server``'s body comes
|
|
|
227 after ``Client``'s spec in the elaboration order. As a result, the value of
|
|
|
228 constant ``Val`` is now undefined.
|
|
|
229
|
|
|
230 Without any guarantees from the language, an undetected ABE problem may hinder
|
|
|
231 proper initialization of data, which in turn may lead to undefined behavior at
|
|
|
232 run time. To prevent such ABE problems, Ada employs dynamic checks in the same
|
|
|
233 vein as index or null exclusion checks. A failed ABE check raises exception
|
|
|
234 ``Program_Error``.
|
|
|
235
|
|
|
236 The following elaboration order avoids the ABE problem and the program can be
|
|
|
237 successfully elaborated.
|
|
|
238
|
|
|
239 ::
|
|
|
240
|
|
|
241 spec of Server
|
|
|
242 body of Server
|
|
|
243 spec of Client
|
|
|
244 body of Main
|
|
|
245
|
|
|
246 Ada states that a total elaboration order must exist, but it does not define
|
|
|
247 what this order is. A compiler is thus tasked with choosing a suitable
|
|
|
248 elaboration order which satisfies the dependencies imposed by |with| clauses,
|
|
|
249 unit categorization, and elaboration control pragmas. Ideally an order which
|
|
|
250 avoids ABE problems should be chosen, however a compiler may not always find
|
|
|
251 such an order due to complications with respect to control and data flow.
|
|
|
252
|
|
|
253 .. _Checking_the_Elaboration_Order:
|
|
|
254
|
|
|
255 Checking the Elaboration Order
|
|
|
256 ==============================
|
|
|
257
|
|
|
258 To avoid placing the entire elaboration order burden on the programmer, Ada
|
|
|
259 provides three lines of defense:
|
|
|
260
|
|
|
261 * *Static semantics*
|
|
|
262
|
|
|
263 Static semantic rules restrict the possible choice of elaboration order. For
|
|
|
264 instance, if unit Client |withs| unit Server, then the spec of Server is
|
|
|
265 always elaborated prior to Client. The same principle applies to child units
|
|
|
266 - the spec of a parent unit is always elaborated prior to the child unit.
|
|
|
267
|
|
|
268 * *Dynamic semantics*
|
|
|
269
|
|
|
270 Dynamic checks are performed at run time, to ensure that a target is
|
|
|
271 elaborated prior to a scenario that executes it, thus avoiding ABE problems.
|
|
|
272 A failed run-time check raises exception ``Program_Error``. The following
|
|
|
273 restrictions apply:
|
|
|
274
|
|
|
275 - *Restrictions on calls*
|
|
|
276
|
|
|
277 An entry, operator, or subprogram can be called from elaboration code only
|
|
|
278 when the corresponding body has been elaborated.
|
|
|
279
|
|
|
280 - *Restrictions on instantiations*
|
|
|
281
|
|
|
282 A generic unit can be instantiated by elaboration code only when the
|
|
|
283 corresponding body has been elaborated.
|
|
|
284
|
|
|
285 - *Restrictions on task activation*
|
|
|
286
|
|
|
287 A task can be activated by elaboration code only when the body of the
|
|
|
288 associated task type has been elaborated.
|
|
|
289
|
|
|
290 The restrictions above can be summarized by the following rule:
|
|
|
291
|
|
|
292 *If a target has a body, then this body must be elaborated prior to the
|
|
|
293 execution of the scenario that invokes, instantiates, or activates the
|
|
|
294 target.*
|
|
|
295
|
|
|
296 * *Elaboration control*
|
|
|
297
|
|
|
298 Pragmas are provided for the programmer to specify the desired elaboration
|
|
|
299 order.
|
|
|
300
|
|
|
301 .. _Controlling_the_Elaboration_Order_in_Ada:
|
|
|
302
|
|
|
303 Controlling the Elaboration Order in Ada
|
|
|
304 ========================================
|
|
|
305
|
|
|
306 Ada provides several idioms and pragmas to aid the programmer with specifying
|
|
|
307 the desired elaboration order and avoiding ABE problems altogether.
|
|
|
308
|
|
|
309 * *Packages without a body*
|
|
|
310
|
|
|
311 A library package which does not require a completing body does not suffer
|
|
|
312 from ABE problems.
|
|
|
313
|
|
|
314 ::
|
|
|
315
|
|
|
316 package Pack is
|
|
|
317 generic
|
|
|
318 type Element is private;
|
|
|
319 package Containers is
|
|
|
320 type Element_Array is array (1 .. 10) of Element;
|
|
|
321 end Containers;
|
|
|
322 end Pack;
|
|
|
323
|
|
|
324 In the example above, package ``Pack`` does not require a body because it
|
|
|
325 does not contain any constructs which require completion in a body. As a
|
|
|
326 result, generic ``Pack.Containers`` can be instantiated without encountering
|
|
|
327 any ABE problems.
|
|
|
328
|
|
|
329 .. index:: pragma Pure
|
|
|
330
|
|
|
331 * *pragma Pure*
|
|
|
332
|
|
|
333 Pragma ``Pure`` places sufficient restrictions on a unit to guarantee that no
|
|
|
334 scenario within the unit can result in an ABE problem.
|
|
|
335
|
|
|
336 .. index:: pragma Preelaborate
|
|
|
337
|
|
|
338 * *pragma Preelaborate*
|
|
|
339
|
|
|
340 Pragma ``Preelaborate`` is slightly less restrictive than pragma ``Pure``,
|
|
|
341 but still strong enough to prevent ABE problems within a unit.
|
|
|
342
|
|
|
343 .. index:: pragma Elaborate_Body
|
|
|
344
|
|
|
345 * *pragma Elaborate_Body*
|
|
|
346
|
|
|
347 Pragma ``Elaborate_Body`` requires that the body of a unit is elaborated
|
|
|
348 immediately after its spec. This restriction guarantees that no client
|
|
|
349 scenario can execute a server target before the target body has been
|
|
|
350 elaborated because the spec and body are effectively "glued" together.
|
|
|
351
|
|
|
352 ::
|
|
|
353
|
|
|
354 package Server is
|
|
|
355 pragma Elaborate_Body;
|
|
|
356
|
|
|
357 function Func return Integer;
|
|
|
358 end Server;
|
|
|
359
|
|
|
360 ::
|
|
|
361
|
|
|
362 package body Server is
|
|
|
363 function Func return Integer is
|
|
|
364 begin
|
|
|
365 ...
|
|
|
366 end Func;
|
|
|
367 end Server;
|
|
|
368
|
|
|
369 ::
|
|
|
370
|
|
|
371 with Server;
|
|
|
372 package Client is
|
|
|
373 Val : constant Integer := Server.Func;
|
|
|
374 end Client;
|
|
|
375
|
|
|
376 In the example above, pragma ``Elaborate_Body`` guarantees the following
|
|
|
377 elaboration order:
|
|
|
378
|
|
|
379 ::
|
|
|
380
|
|
|
381 spec of Server
|
|
|
382 body of Server
|
|
|
383 spec of Client
|
|
|
384
|
|
|
385 because the spec of ``Server`` must be elaborated prior to ``Client`` by
|
|
|
386 virtue of the |with| clause, and in addition the body of ``Server`` must be
|
|
|
387 elaborated immediately after the spec of ``Server``.
|
|
|
388
|
|
|
389 Removing pragma ``Elaborate_Body`` could result in the following incorrect
|
|
|
390 elaboration order:
|
|
|
391
|
|
|
392 ::
|
|
|
393
|
|
|
394 spec of Server
|
|
|
395 spec of Client
|
|
|
396 body of Server
|
|
|
397
|
|
|
398 where ``Client`` invokes ``Server.Func``, but the body of ``Server.Func`` has
|
|
|
399 not been elaborated yet.
|
|
|
400
|
|
|
401 The pragmas outlined above allow a server unit to guarantee safe elaboration
|
|
|
402 use by client units. Thus it is a good rule to mark units as ``Pure`` or
|
|
|
403 ``Preelaborate``, and if this is not possible, mark them as ``Elaborate_Body``.
|
|
|
404
|
|
|
405 There are however situations where ``Pure``, ``Preelaborate``, and
|
|
|
406 ``Elaborate_Body`` are not applicable. Ada provides another set of pragmas for
|
|
|
407 use by client units to help ensure the elaboration safety of server units they
|
|
|
408 depend on.
|
|
|
409
|
|
|
410 .. index:: pragma Elaborate (Unit)
|
|
|
411
|
|
|
412 * *pragma Elaborate (Unit)*
|
|
|
413
|
|
|
414 Pragma ``Elaborate`` can be placed in the context clauses of a unit, after a
|
|
|
415 |with| clause. It guarantees that both the spec and body of its argument will
|
|
|
416 be elaborated prior to the unit with the pragma. Note that other unrelated
|
|
|
417 units may be elaborated in between the spec and the body.
|
|
|
418
|
|
|
419 ::
|
|
|
420
|
|
|
421 package Server is
|
|
|
422 function Func return Integer;
|
|
|
423 end Server;
|
|
|
424
|
|
|
425 ::
|
|
|
426
|
|
|
427 package body Server is
|
|
|
428 function Func return Integer is
|
|
|
429 begin
|
|
|
430 ...
|
|
|
431 end Func;
|
|
|
432 end Server;
|
|
|
433
|
|
|
434 ::
|
|
|
435
|
|
|
436 with Server;
|
|
|
437 pragma Elaborate (Server);
|
|
|
438 package Client is
|
|
|
439 Val : constant Integer := Server.Func;
|
|
|
440 end Client;
|
|
|
441
|
|
|
442 In the example above, pragma ``Elaborate`` guarantees the following
|
|
|
443 elaboration order:
|
|
|
444
|
|
|
445 ::
|
|
|
446
|
|
|
447 spec of Server
|
|
|
448 body of Server
|
|
|
449 spec of Client
|
|
|
450
|
|
|
451 Removing pragma ``Elaborate`` could result in the following incorrect
|
|
|
452 elaboration order:
|
|
|
453
|
|
|
454 ::
|
|
|
455
|
|
|
456 spec of Server
|
|
|
457 spec of Client
|
|
|
458 body of Server
|
|
|
459
|
|
|
460 where ``Client`` invokes ``Server.Func``, but the body of ``Server.Func``
|
|
|
461 has not been elaborated yet.
|
|
|
462
|
|
|
463 .. index:: pragma Elaborate_All (Unit)
|
|
|
464
|
|
|
465 * *pragma Elaborate_All (Unit)*
|
|
|
466
|
|
|
467 Pragma ``Elaborate_All`` is placed in the context clauses of a unit, after
|
|
|
468 a |with| clause. It guarantees that both the spec and body of its argument
|
|
|
469 will be elaborated prior to the unit with the pragma, as well as all units
|
|
|
470 |withed| by the spec and body of the argument, recursively. Note that other
|
|
|
471 unrelated units may be elaborated in between the spec and the body.
|
|
|
472
|
|
|
473 ::
|
|
|
474
|
|
|
475 package Math is
|
|
|
476 function Factorial (Val : Natural) return Natural;
|
|
|
477 end Math;
|
|
|
478
|
|
|
479 ::
|
|
|
480
|
|
|
481 package body Math is
|
|
|
482 function Factorial (Val : Natural) return Natural is
|
|
|
483 begin
|
|
|
484 ...;
|
|
|
485 end Factorial;
|
|
|
486 end Math;
|
|
|
487
|
|
|
488 ::
|
|
|
489
|
|
|
490 package Computer is
|
|
|
491 type Operation_Kind is (None, Op_Factorial);
|
|
|
492
|
|
|
493 function Compute
|
|
|
494 (Val : Natural;
|
|
|
495 Op : Operation_Kind) return Natural;
|
|
|
496 end Computer;
|
|
|
497
|
|
|
498 ::
|
|
|
499
|
|
|
500 with Math;
|
|
|
501 package body Computer is
|
|
|
502 function Compute
|
|
|
503 (Val : Natural;
|
|
|
504 Op : Operation_Kind) return Natural
|
|
|
505 is
|
|
|
506 if Op = Op_Factorial then
|
|
|
507 return Math.Factorial (Val);
|
|
|
508 end if;
|
|
|
509
|
|
|
510 return 0;
|
|
|
511 end Compute;
|
|
|
512 end Computer;
|
|
|
513
|
|
|
514 ::
|
|
|
515
|
|
|
516 with Computer;
|
|
|
517 pragma Elaborate_All (Computer);
|
|
|
518 package Client is
|
|
|
519 Val : constant Natural :=
|
|
|
520 Computer.Compute (123, Computer.Op_Factorial);
|
|
|
521 end Client;
|
|
|
522
|
|
|
523 In the example above, pragma ``Elaborate_All`` can result in the following
|
|
|
524 elaboration order:
|
|
|
525
|
|
|
526 ::
|
|
|
527
|
|
|
528 spec of Math
|
|
|
529 body of Math
|
|
|
530 spec of Computer
|
|
|
531 body of Computer
|
|
|
532 spec of Client
|
|
|
533
|
|
|
534 Note that there are several allowable suborders for the specs and bodies of
|
|
|
535 ``Math`` and ``Computer``, but the point is that these specs and bodies will
|
|
|
536 be elaborated prior to ``Client``.
|
|
|
537
|
|
|
538 Removing pragma ``Elaborate_All`` could result in the following incorrect
|
|
|
539 elaboration order
|
|
|
540
|
|
|
541 ::
|
|
|
542
|
|
|
543 spec of Math
|
|
|
544 spec of Computer
|
|
|
545 body of Computer
|
|
|
546 spec of Client
|
|
|
547 body of Math
|
|
|
548
|
|
|
549 where ``Client`` invokes ``Computer.Compute``, which in turn invokes
|
|
|
550 ``Math.Factorial``, but the body of ``Math.Factorial`` has not been
|
|
|
551 elaborated yet.
|
|
|
552
|
|
|
553 All pragmas shown above can be summarized by the following rule:
|
|
|
554
|
|
|
555 *If a client unit elaborates a server target directly or indirectly, then if
|
|
|
556 the server unit requires a body and does not have pragma Pure, Preelaborate,
|
|
|
557 or Elaborate_Body, then the client unit should have pragma Elaborate or
|
|
|
558 Elaborate_All for the server unit.*
|
|
|
559
|
|
|
560 If the rule outlined above is not followed, then a program may fall in one of
|
|
|
561 the following states:
|
|
|
562
|
|
|
563 * *No elaboration order exists*
|
|
|
564
|
|
|
565 In this case a compiler must diagnose the situation, and refuse to build an
|
|
|
566 executable program.
|
|
|
567
|
|
|
568 * *One or more incorrect elaboration orders exist*
|
|
|
569
|
|
|
570 In this case a compiler can build an executable program, but
|
|
|
571 ``Program_Error`` will be raised when the program is run.
|
|
|
572
|
|
|
573 * *Several elaboration orders exist, some correct, some incorrect*
|
|
|
574
|
|
|
575 In this case the programmer has not controlled the elaboration order. As a
|
|
|
576 result, a compiler may or may not pick one of the correct orders, and the
|
|
|
577 program may or may not raise ``Program_Error`` when it is run. This is the
|
|
|
578 worst possible state because the program may fail on another compiler, or
|
|
|
579 even another version of the same compiler.
|
|
|
580
|
|
|
581 * *One or more correct orders exist*
|
|
|
582
|
|
|
583 In this case a compiler can build an executable program, and the program is
|
|
|
584 run successfully. This state may be guaranteed by following the outlined
|
|
|
585 rules, or may be the result of good program architecture.
|
|
|
586
|
|
|
587 Note that one additional advantage of using ``Elaborate`` and ``Elaborate_All``
|
|
|
588 is that the program continues to stay in the last state (one or more correct
|
|
|
589 orders exist) even if maintenance changes the bodies of targets.
|
|
|
590
|
|
|
591 .. _Controlling_the_Elaboration_Order_in_GNAT:
|
|
|
592
|
|
|
593 Controlling the Elaboration Order in GNAT
|
|
|
594 =========================================
|
|
|
595
|
|
|
596 In addition to Ada semantics and rules synthesized from them, GNAT offers
|
|
|
597 three elaboration models to aid the programmer with specifying the correct
|
|
|
598 elaboration order and to diagnose elaboration problems.
|
|
|
599
|
|
|
600 .. index:: Dynamic elaboration model
|
|
|
601
|
|
|
602 * *Dynamic elaboration model*
|
|
|
603
|
|
|
604 This is the most permissive of the three elaboration models. When the
|
|
|
605 dynamic model is in effect, GNAT assumes that all code within all units in
|
|
|
606 a partition is elaboration code. GNAT performs very few diagnostics and
|
|
|
607 generates run-time checks to verify the elaboration order of a program. This
|
|
|
608 behavior is identical to that specified by the Ada Reference Manual. The
|
|
|
609 dynamic model is enabled with compiler switch :switch:`-gnatE`.
|
|
|
610
|
|
|
611 .. index:: Static elaboration model
|
|
|
612
|
|
|
613 * *Static elaboration model*
|
|
|
614
|
|
|
615 This is the middle ground of the three models. When the static model is in
|
|
|
616 effect, GNAT performs extensive diagnostics on a unit-by-unit basis for all
|
|
|
617 scenarios that elaborate or execute internal targets. GNAT also generates
|
|
|
618 run-time checks for all external targets and for all scenarios that may
|
|
|
619 exhibit ABE problems. Finally, GNAT installs implicit ``Elaborate`` and
|
|
|
620 ``Elaborate_All`` pragmas for server units based on the dependencies of
|
|
|
621 client units. The static model is the default model in GNAT.
|
|
|
622
|
|
|
623 .. index:: SPARK elaboration model
|
|
|
624
|
|
|
625 * *SPARK elaboration model*
|
|
|
626
|
|
|
627 This is the most conservative of the three models and enforces the SPARK
|
|
|
628 rules of elaboration as defined in the SPARK Reference Manual, section 7.7.
|
|
|
629 The SPARK model is in effect only when a scenario and a target reside in a
|
|
|
630 region subject to SPARK_Mode On, otherwise the dynamic or static model is in
|
|
|
631 effect.
|
|
|
632
|
|
131
|
633 .. index:: Legacy elaboration model
|
|
|
634
|
|
|
635 * *Legacy elaboration model*
|
|
|
636
|
|
|
637 In addition to the three elaboration models outlined above, GNAT provides the
|
|
|
638 elaboration model of pre-18.x versions referred to as `legacy elaboration
|
|
|
639 model`. The legacy elaboration model is enabled with compiler switch
|
|
|
640 :switch:`-gnatH`.
|
|
|
641
|
|
|
642 .. index:: Relaxed elaboration mode
|
|
|
643
|
|
|
644 The dynamic, legacy, and static models can be relaxed using compiler switch
|
|
|
645 :switch:`-gnatJ`, making them more permissive. Note that in this mode, GNAT
|
|
|
646 may not diagnose certain elaboration issues or install run-time checks.
|
|
|
647
|
|
111
|
648 .. _Common_Elaboration_Model_Traits":
|
|
|
649
|
|
|
650 Common Elaboration-model Traits
|
|
|
651 ===============================
|
|
|
652
|
|
|
653 All three GNAT models are able to detect elaboration problems related to
|
|
|
654 dispatching calls and a particular kind of ABE referred to as *guaranteed ABE*.
|
|
|
655
|
|
|
656 * *Dispatching calls*
|
|
|
657
|
|
|
658 GNAT installs run-time checks for each primitive subprogram of each tagged
|
|
|
659 type defined in a partition on the assumption that a dispatching call
|
|
|
660 invoked at elaboration time will execute one of these primitives. As a
|
|
|
661 result, a dispatching call that executes a primitive whose body has not
|
|
|
662 been elaborated yet will raise exception ``Program_Error`` at run time. The
|
|
|
663 checks can be suppressed using pragma ``Suppress (Elaboration_Check)``.
|
|
|
664
|
|
|
665 * *Guaranteed ABE*
|
|
|
666
|
|
|
667 A guaranteed ABE arises when the body of a target is not elaborated early
|
|
|
668 enough, and causes all scenarios that directly execute the target to fail.
|
|
|
669
|
|
|
670 ::
|
|
|
671
|
|
|
672 package body Guaranteed_ABE is
|
|
|
673 function ABE return Integer;
|
|
|
674
|
|
|
675 Val : constant Integer := ABE;
|
|
|
676
|
|
|
677 function ABE return Integer is
|
|
|
678 begin
|
|
|
679 ...
|
|
|
680 end ABE;
|
|
|
681 end Guaranteed_ABE;
|
|
|
682
|
|
|
683 In the example above, the elaboration of ``Guaranteed_ABE``'s body elaborates
|
|
|
684 the declaration of ``Val``. This invokes function ``ABE``, however the body
|
|
|
685 of ``ABE`` has not been elaborated yet. GNAT emits similar diagnostics in all
|
|
|
686 three models:
|
|
|
687
|
|
|
688 ::
|
|
|
689
|
|
|
690 1. package body Guaranteed_ABE is
|
|
|
691 2. function ABE return Integer;
|
|
|
692 3.
|
|
|
693 4. Val : constant Integer := ABE;
|
|
|
694 |
|
|
|
695 >>> warning: cannot call "ABE" before body seen
|
|
|
696 >>> warning: Program_Error will be raised at run time
|
|
|
697
|
|
|
698 5.
|
|
|
699 6. function ABE return Integer is
|
|
|
700 7. begin
|
|
|
701 8. ...
|
|
|
702 9. end ABE;
|
|
|
703 10. end Guaranteed_ABE;
|
|
|
704
|
|
|
705 Note that GNAT emits warnings rather than hard errors whenever it encounters an
|
|
|
706 elaboration problem. This is because the elaboration model in effect may be too
|
|
|
707 conservative, or a particular scenario may not be elaborated or executed due to
|
|
131
|
708 data and control flow. The warnings can be suppressed selectively with ``pragma
|
|
|
709 Warnigns (Off)`` or globally with compiler switch :switch:`-gnatwL`.
|
|
111
|
710
|
|
|
711 .. _Dynamic_Elaboration_Model_in_GNAT:
|
|
|
712
|
|
|
713 Dynamic Elaboration Model in GNAT
|
|
|
714 =================================
|
|
|
715
|
|
|
716 The dynamic model assumes that all code within all units in a partition is
|
|
|
717 elaboration code. As a result, run-time checks are installed for each scenario
|
|
|
718 regardless of whether the target is internal or external. The checks can be
|
|
|
719 suppressed using pragma ``Suppress (Elaboration_Check)``. This behavior is
|
|
|
720 identical to that specified by the Ada Reference Manual. The following example
|
|
|
721 showcases run-time checks installed by GNAT to verify the elaboration state of
|
|
|
722 package ``Dynamic_Model``.
|
|
|
723
|
|
|
724 ::
|
|
|
725
|
|
|
726 with Server;
|
|
|
727 package body Dynamic_Model is
|
|
|
728 procedure API is
|
|
|
729 begin
|
|
|
730 ...
|
|
|
731 end API;
|
|
|
732
|
|
|
733 <check that the body of Server.Gen is elaborated>
|
|
|
734 package Inst is new Server.Gen;
|
|
|
735
|
|
|
736 T : Server.Task_Type;
|
|
|
737
|
|
|
738 begin
|
|
|
739 <check that the body of Server.Task_Type is elaborated>
|
|
|
740
|
|
|
741 <check that the body of Server.Proc is elaborated>
|
|
|
742 Server.Proc;
|
|
|
743 end Dynamic_Model;
|
|
|
744
|
|
|
745 The checks verify that the body of a target has been successfully elaborated
|
|
|
746 before a scenario activates, calls, or instantiates a target.
|
|
|
747
|
|
|
748 Note that no scenario within package ``Dynamic_Model`` calls procedure ``API``.
|
|
|
749 In fact, procedure ``API`` may not be invoked by elaboration code within the
|
|
|
750 partition, however the dynamic model assumes that this can happen.
|
|
|
751
|
|
|
752 The dynamic model emits very few diagnostics, but can make suggestions on
|
|
|
753 missing ``Elaborate`` and ``Elaborate_All`` pragmas for library-level
|
|
|
754 scenarios. This information is available when compiler switch :switch:`-gnatel`
|
|
|
755 is in effect.
|
|
|
756
|
|
|
757 ::
|
|
|
758
|
|
|
759 1. with Server;
|
|
|
760 2. package body Dynamic_Model is
|
|
|
761 3. Val : constant Integer := Server.Func;
|
|
|
762 |
|
|
|
763 >>> info: call to "Func" during elaboration
|
|
|
764 >>> info: missing pragma "Elaborate_All" for unit "Server"
|
|
|
765
|
|
|
766 4. end Dynamic_Model;
|
|
|
767
|
|
|
768 .. _Static_Elaboration_Model_in_GNAT:
|
|
|
769
|
|
|
770 Static Elaboration Model in GNAT
|
|
|
771 ================================
|
|
|
772
|
|
|
773 In contrast to the dynamic model, the static model is more precise in its
|
|
|
774 analysis of elaboration code. The model makes a clear distinction between
|
|
|
775 internal and external targets, and resorts to different diagnostics and
|
|
|
776 run-time checks based on the nature of the target.
|
|
|
777
|
|
|
778 * *Internal targets*
|
|
|
779
|
|
|
780 The static model performs extensive diagnostics on scenarios which elaborate
|
|
|
781 or execute internal targets. The warnings resulting from these diagnostics
|
|
131
|
782 are enabled by default, but can be suppressed selectively with ``pragma
|
|
|
783 Warnings (Off)`` or globally with compiler switch :switch:`-gnatwL`.
|
|
111
|
784
|
|
|
785 ::
|
|
|
786
|
|
|
787 1. package body Static_Model is
|
|
|
788 2. generic
|
|
|
789 3. with function Func return Integer;
|
|
|
790 4. package Gen is
|
|
|
791 5. Val : constant Integer := Func;
|
|
|
792 6. end Gen;
|
|
|
793 7.
|
|
|
794 8. function ABE return Integer;
|
|
|
795 9.
|
|
|
796 10. function Cause_ABE return Boolean is
|
|
|
797 11. package Inst is new Gen (ABE);
|
|
|
798 |
|
|
|
799 >>> warning: in instantiation at line 5
|
|
|
800 >>> warning: cannot call "ABE" before body seen
|
|
|
801 >>> warning: Program_Error may be raised at run time
|
|
|
802 >>> warning: body of unit "Static_Model" elaborated
|
|
|
803 >>> warning: function "Cause_ABE" called at line 16
|
|
|
804 >>> warning: function "ABE" called at line 5, instance at line 11
|
|
|
805
|
|
|
806 12. begin
|
|
|
807 13. ...
|
|
|
808 14. end Cause_ABE;
|
|
|
809 15.
|
|
|
810 16. Val : constant Boolean := Cause_ABE;
|
|
|
811 17.
|
|
|
812 18. function ABE return Integer is
|
|
|
813 19. begin
|
|
|
814 20. ...
|
|
|
815 21. end ABE;
|
|
|
816 22. end Static_Model;
|
|
|
817
|
|
|
818 The example above illustrates an ABE problem within package ``Static_Model``,
|
|
|
819 which is hidden by several layers of indirection. The elaboration of package
|
|
|
820 body ``Static_Model`` elaborates the declaration of ``Val``. This invokes
|
|
|
821 function ``Cause_ABE``, which instantiates generic unit ``Gen`` as ``Inst``.
|
|
|
822 The elaboration of ``Inst`` invokes function ``ABE``, however the body of
|
|
|
823 ``ABE`` has not been elaborated yet.
|
|
|
824
|
|
|
825 * *External targets*
|
|
|
826
|
|
|
827 The static model installs run-time checks to verify the elaboration status
|
|
|
828 of server targets only when the scenario that elaborates or executes that
|
|
|
829 target is part of the elaboration code of the client unit. The checks can be
|
|
|
830 suppressed using pragma ``Suppress (Elaboration_Check)``.
|
|
|
831
|
|
|
832 ::
|
|
|
833
|
|
|
834 with Server;
|
|
|
835 package body Static_Model is
|
|
|
836 generic
|
|
|
837 with function Func return Integer;
|
|
|
838 package Gen is
|
|
|
839 Val : constant Integer := Func;
|
|
|
840 end Gen;
|
|
|
841
|
|
|
842 function Call_Func return Boolean is
|
|
|
843 <check that the body of Server.Func is elaborated>
|
|
|
844 package Inst is new Gen (Server.Func);
|
|
|
845 begin
|
|
|
846 ...
|
|
|
847 end Call_Func;
|
|
|
848
|
|
|
849 Val : constant Boolean := Call_Func;
|
|
|
850 end Static_Model;
|
|
|
851
|
|
|
852 In the example above, the elaboration of package body ``Static_Model``
|
|
|
853 elaborates the declaration of ``Val``. This invokes function ``Call_Func``,
|
|
|
854 which instantiates generic unit ``Gen`` as ``Inst``. The elaboration of
|
|
|
855 ``Inst`` invokes function ``Server.Func``. Since ``Server.Func`` is an
|
|
|
856 external target, GNAT installs a run-time check to verify that its body has
|
|
|
857 been elaborated.
|
|
|
858
|
|
|
859 In addition to checks, the static model installs implicit ``Elaborate`` and
|
|
|
860 ``Elaborate_All`` pragmas to guarantee safe elaboration use of server units.
|
|
|
861 This information is available when compiler switch :switch:`-gnatel` is in
|
|
|
862 effect.
|
|
|
863
|
|
|
864 ::
|
|
|
865
|
|
|
866 1. with Server;
|
|
|
867 2. package body Static_Model is
|
|
|
868 3. generic
|
|
|
869 4. with function Func return Integer;
|
|
|
870 5. package Gen is
|
|
|
871 6. Val : constant Integer := Func;
|
|
|
872 7. end Gen;
|
|
|
873 8.
|
|
|
874 9. function Call_Func return Boolean is
|
|
|
875 10. package Inst is new Gen (Server.Func);
|
|
|
876 |
|
|
|
877 >>> info: instantiation of "Gen" during elaboration
|
|
|
878 >>> info: in instantiation at line 6
|
|
|
879 >>> info: call to "Func" during elaboration
|
|
|
880 >>> info: in instantiation at line 6
|
|
|
881 >>> info: implicit pragma "Elaborate_All" generated for unit "Server"
|
|
|
882 >>> info: body of unit "Static_Model" elaborated
|
|
|
883 >>> info: function "Call_Func" called at line 15
|
|
|
884 >>> info: function "Func" called at line 6, instance at line 10
|
|
|
885
|
|
|
886 11. begin
|
|
|
887 12. ...
|
|
|
888 13. end Call_Func;
|
|
|
889 14.
|
|
|
890 15. Val : constant Boolean := Call_Func;
|
|
|
891 |
|
|
|
892 >>> info: call to "Call_Func" during elaboration
|
|
|
893
|
|
|
894 16. end Static_Model;
|
|
|
895
|
|
|
896 In the example above, the elaboration of package body ``Static_Model``
|
|
|
897 elaborates the declaration of ``Val``. This invokes function ``Call_Func``,
|
|
|
898 which instantiates generic unit ``Gen`` as ``Inst``. The elaboration of
|
|
|
899 ``Inst`` invokes function ``Server.Func``. Since ``Server.Func`` is an
|
|
|
900 external target, GNAT installs an implicit ``Elaborate_All`` pragma for unit
|
|
|
901 ``Server``. The pragma guarantees that both the spec and body of ``Server``,
|
|
|
902 along with any additional dependencies that ``Server`` may require, are
|
|
|
903 elaborated prior to the body of ``Static_Model``.
|
|
|
904
|
|
|
905 .. _SPARK_Elaboration_Model_in_GNAT:
|
|
|
906
|
|
|
907 SPARK Elaboration Model in GNAT
|
|
|
908 ===============================
|
|
|
909
|
|
|
910 The SPARK model is identical to the static model in its handling of internal
|
|
|
911 targets. The SPARK model, however, requires explicit ``Elaborate`` or
|
|
|
912 ``Elaborate_All`` pragmas to be present in the program when a target is
|
|
|
913 external, and compiler switch :switch:`-gnatd.v` is in effect.
|
|
|
914
|
|
|
915 ::
|
|
|
916
|
|
|
917 1. with Server;
|
|
|
918 2. package body SPARK_Model with SPARK_Mode is
|
|
|
919 3. Val : constant Integer := Server.Func;
|
|
|
920 |
|
|
|
921 >>> call to "Func" during elaboration in SPARK
|
|
|
922 >>> unit "SPARK_Model" requires pragma "Elaborate_All" for "Server"
|
|
|
923 >>> body of unit "SPARK_Model" elaborated
|
|
|
924 >>> function "Func" called at line 3
|
|
|
925
|
|
|
926 4. end SPARK_Model;
|
|
|
927
|
|
131
|
928 Legacy Elaboration Model in GNAT
|
|
|
929 ================================
|
|
|
930
|
|
|
931 The legacy elaboration model is provided for compatibility with code bases
|
|
|
932 developed with pre-18.x versions of GNAT. It is similar in functionality to
|
|
|
933 the dynamic and static models of post-18.x version of GNAT, but may differ
|
|
|
934 in terms of diagnostics and run-time checks. The legacy elaboration model is
|
|
|
935 enabled with compiler switch :switch:`-gnatH`.
|
|
|
936
|
|
111
|
937 .. _Mixing_Elaboration_Models:
|
|
|
938
|
|
|
939 Mixing Elaboration Models
|
|
|
940 =========================
|
|
|
941
|
|
|
942 It is possible to mix units compiled with a different elaboration model,
|
|
|
943 however the following rules must be observed:
|
|
|
944
|
|
|
945 * A client unit compiled with the dynamic model can only |with| a server unit
|
|
|
946 that meets at least one of the following criteria:
|
|
|
947
|
|
|
948 - The server unit is compiled with the dynamic model.
|
|
|
949
|
|
|
950 - The server unit is a GNAT implementation unit from the Ada, GNAT,
|
|
|
951 Interfaces, or System hierarchies.
|
|
|
952
|
|
|
953 - The server unit has pragma ``Pure`` or ``Preelaborate``.
|
|
|
954
|
|
|
955 - The client unit has an explicit ``Elaborate_All`` pragma for the server
|
|
|
956 unit.
|
|
|
957
|
|
|
958 These rules ensure that elaboration checks are not omitted. If the rules are
|
|
|
959 violated, the binder emits a warning:
|
|
|
960
|
|
|
961 ::
|
|
|
962
|
|
|
963 warning: "x.ads" has dynamic elaboration checks and with's
|
|
|
964 warning: "y.ads" which has static elaboration checks
|
|
|
965
|
|
|
966 The warnings can be suppressed by binder switch :switch:`-ws`.
|
|
|
967
|
|
|
968 .. _Elaboration_Circularities:
|
|
|
969
|
|
|
970 Elaboration Circularities
|
|
|
971 =========================
|
|
|
972
|
|
|
973 If the binder cannot find an acceptable elaboration order, it outputs detailed
|
|
|
974 diagnostics describing an **elaboration circularity**.
|
|
|
975
|
|
|
976 ::
|
|
|
977
|
|
|
978 package Server is
|
|
|
979 function Func return Integer;
|
|
|
980 end Server;
|
|
|
981
|
|
|
982 ::
|
|
|
983
|
|
|
984 with Client;
|
|
|
985 package body Server is
|
|
|
986 function Func return Integer is
|
|
|
987 begin
|
|
|
988 ...
|
|
|
989 end Func;
|
|
|
990 end Server;
|
|
|
991
|
|
|
992 ::
|
|
|
993
|
|
|
994 with Server;
|
|
|
995 package Client is
|
|
|
996 Val : constant Integer := Server.Func;
|
|
|
997 end Client;
|
|
|
998
|
|
|
999 ::
|
|
|
1000
|
|
|
1001 with Client;
|
|
|
1002 procedure Main is begin null; end Main;
|
|
|
1003
|
|
|
1004 ::
|
|
|
1005
|
|
|
1006 error: elaboration circularity detected
|
|
|
1007 info: "server (body)" must be elaborated before "client (spec)"
|
|
|
1008 info: reason: implicit Elaborate_All in unit "client (spec)"
|
|
|
1009 info: recompile "client (spec)" with -gnatel for full details
|
|
|
1010 info: "server (body)"
|
|
|
1011 info: must be elaborated along with its spec:
|
|
|
1012 info: "server (spec)"
|
|
|
1013 info: which is withed by:
|
|
|
1014 info: "client (spec)"
|
|
|
1015 info: "client (spec)" must be elaborated before "server (body)"
|
|
|
1016 info: reason: with clause
|
|
|
1017
|
|
|
1018 In the example above, ``Client`` must be elaborated prior to ``Main`` by virtue
|
|
|
1019 of a |with| clause. The elaboration of ``Client`` invokes ``Server.Func``, and
|
|
|
1020 static model generates an implicit ``Elaborate_All`` pragma for ``Server``. The
|
|
|
1021 pragma implies that both the spec and body of ``Server``, along with any units
|
|
|
1022 they |with|, must be elaborated prior to ``Client``. However, ``Server``'s body
|
|
|
1023 |withs| ``Client``, implying that ``Client`` must be elaborated prior to
|
|
|
1024 ``Server``. The end result is that ``Client`` must be elaborated prior to
|
|
|
1025 ``Client``, and this leads to a circularity.
|
|
|
1026
|
|
|
1027 .. _Resolving_Elaboration_Circularities:
|
|
|
1028
|
|
|
1029 Resolving Elaboration Circularities
|
|
|
1030 ===================================
|
|
|
1031
|
|
|
1032 When faced with an elaboration circularity, a programmer has several options
|
|
|
1033 available.
|
|
|
1034
|
|
|
1035 * *Fix the program*
|
|
|
1036
|
|
|
1037 The most desirable option from the point of view of long-term maintenance
|
|
|
1038 is to rearrange the program so that the elaboration problems are avoided.
|
|
|
1039 One useful technique is to place the elaboration code into separate child
|
|
|
1040 packages. Another is to move some of the initialization code to explicitly
|
|
|
1041 invoked subprograms, where the program controls the order of initialization
|
|
|
1042 explicitly. Although this is the most desirable option, it may be impractical
|
|
|
1043 and involve too much modification, especially in the case of complex legacy
|
|
|
1044 code.
|
|
|
1045
|
|
|
1046 * *Switch to more permissive elaboration model*
|
|
|
1047
|
|
|
1048 If the compilation was performed using the static model, enable the dynamic
|
|
|
1049 model with compiler switch :switch:`-gnatE`. GNAT will no longer generate
|
|
|
1050 implicit ``Elaborate`` and ``Elaborate_All`` pragmas, resulting in a behavior
|
|
|
1051 identical to that specified by the Ada Reference Manual. The binder will
|
|
|
1052 generate an executable program that may or may not raise ``Program_Error``,
|
|
|
1053 and it is the programmer's responsibility to ensure that it does not raise
|
|
|
1054 ``Program_Error``.
|
|
|
1055
|
|
131
|
1056 If the compilation was performed using a post-18.x version of GNAT, consider
|
|
|
1057 using the legacy elaboration model, in the following order:
|
|
|
1058
|
|
|
1059 - Use the legacy static elaboration model, with compiler switch
|
|
|
1060 :switch:`-gnatH`.
|
|
|
1061
|
|
|
1062 - Use the legacy dynamic elaboration model, with compiler switches
|
|
|
1063 :switch:`-gnatH` :switch:`-gnatE`.
|
|
|
1064
|
|
|
1065 - Use the relaxed legacy static elaboration model, with compiler switches
|
|
|
1066 :switch:`-gnatH` :switch:`-gnatJ`.
|
|
|
1067
|
|
|
1068 - Use the relaxed legacy dynamic elaboration model, with compiler switches
|
|
|
1069 :switch:`-gnatH` :switch:`-gnatJ` :switch:`-gnatE`.
|
|
|
1070
|
|
111
|
1071 * *Suppress all elaboration checks*
|
|
|
1072
|
|
|
1073 The drawback of run-time checks is that they generate overhead at run time,
|
|
|
1074 both in space and time. If the programmer is absolutely sure that a program
|
|
|
1075 will not raise an elaboration-related ``Program_Error``, then using the
|
|
|
1076 pragma ``Suppress (Elaboration_Check)`` globally (as a configuration pragma)
|
|
|
1077 will eliminate all run-time checks.
|
|
|
1078
|
|
|
1079 * *Suppress elaboration checks selectively*
|
|
|
1080
|
|
|
1081 If a scenario cannot possibly lead to an elaboration ``Program_Error``,
|
|
|
1082 and the binder nevertheless complains about implicit ``Elaborate`` and
|
|
|
1083 ``Elaborate_All`` pragmas that lead to elaboration circularities, it
|
|
|
1084 is possible to suppress the generation of implicit ``Elaborate`` and
|
|
|
1085 ``Elaborate_All`` pragmas, as well as run-time checks. Clearly this can
|
|
|
1086 be unsafe, and it is the responsibility of the programmer to make sure
|
|
|
1087 that the resulting program has no elaboration anomalies. Pragma
|
|
|
1088 ``Suppress (Elaboration_Check)`` can be used with different levels of
|
|
|
1089 granularity to achieve these effects.
|
|
|
1090
|
|
|
1091 - *Target suppression*
|
|
|
1092
|
|
|
1093 When the pragma is placed in a declarative part, without a second argument
|
|
|
1094 naming an entity, it will suppress implicit ``Elaborate`` and
|
|
|
1095 ``Elaborate_All`` pragma generation, as well as run-time checks, on all
|
|
|
1096 targets within the region.
|
|
|
1097
|
|
|
1098 ::
|
|
|
1099
|
|
|
1100 package Range_Suppress is
|
|
|
1101 pragma Suppress (Elaboration_Check);
|
|
|
1102
|
|
|
1103 function Func return Integer;
|
|
|
1104
|
|
|
1105 generic
|
|
|
1106 procedure Gen;
|
|
|
1107
|
|
|
1108 pragma Unsuppress (Elaboration_Check);
|
|
|
1109
|
|
|
1110 task type Tsk;
|
|
|
1111 end Range_Suppress;
|
|
|
1112
|
|
|
1113 In the example above, a pair of Suppress/Unsuppress pragmas define a region
|
|
|
1114 of suppression within package ``Range_Suppress``. As a result, no implicit
|
|
|
1115 ``Elaborate`` and ``Elaborate_All`` pragmas, nor any run-time checks, will
|
|
|
1116 be generated by callers of ``Func`` and instantiators of ``Gen``. Note that
|
|
|
1117 task type ``Tsk`` is not within this region.
|
|
|
1118
|
|
|
1119 An alternative to the region-based suppression is to use multiple
|
|
|
1120 ``Suppress`` pragmas with arguments naming specific entities for which
|
|
|
1121 elaboration checks should be suppressed:
|
|
|
1122
|
|
|
1123 ::
|
|
|
1124
|
|
|
1125 package Range_Suppress is
|
|
|
1126 function Func return Integer;
|
|
|
1127 pragma Suppress (Elaboration_Check, Func);
|
|
|
1128
|
|
|
1129 generic
|
|
|
1130 procedure Gen;
|
|
|
1131 pragma Suppress (Elaboration_Check, Gen);
|
|
|
1132
|
|
|
1133 task type Tsk;
|
|
|
1134 end Range_Suppress;
|
|
|
1135
|
|
|
1136 - *Scenario suppression*
|
|
|
1137
|
|
|
1138 When the pragma ``Suppress`` is placed in a declarative or statement
|
|
|
1139 part, without an entity argument, it will suppress implicit ``Elaborate``
|
|
|
1140 and ``Elaborate_All`` pragma generation, as well as run-time checks, on
|
|
|
1141 all scenarios within the region.
|
|
|
1142
|
|
|
1143 ::
|
|
|
1144
|
|
|
1145 with Server;
|
|
|
1146 package body Range_Suppress is
|
|
|
1147 pragma Suppress (Elaboration_Check);
|
|
|
1148
|
|
|
1149 function Func return Integer is
|
|
|
1150 begin
|
|
|
1151 return Server.Func;
|
|
|
1152 end Func;
|
|
|
1153
|
|
|
1154 procedure Gen is
|
|
|
1155 begin
|
|
|
1156 Server.Proc;
|
|
|
1157 end Gen;
|
|
|
1158
|
|
|
1159 pragma Unsuppress (Elaboration_Check);
|
|
|
1160
|
|
|
1161 task body Tsk is
|
|
|
1162 begin
|
|
|
1163 Server.Proc;
|
|
|
1164 end Tsk;
|
|
|
1165 end Range_Suppress;
|
|
|
1166
|
|
|
1167 In the example above, a pair of Suppress/Unsuppress pragmas define a region
|
|
|
1168 of suppression within package body ``Range_Suppress``. As a result, the
|
|
|
1169 calls to ``Server.Func`` in ``Func`` and ``Server.Proc`` in ``Gen`` will
|
|
|
1170 not generate any implicit ``Elaborate`` and ``Elaborate_All`` pragmas or
|
|
|
1171 run-time checks.
|
|
|
1172
|
|
|
1173 .. _Resolving_Task_Issues:
|
|
|
1174
|
|
|
1175 Resolving Task Issues
|
|
|
1176 =====================
|
|
|
1177
|
|
|
1178 The model of execution in Ada dictates that elaboration must first take place,
|
|
|
1179 and only then can the main program be started. Tasks which are activated during
|
|
|
1180 elaboration violate this model and may lead to serious concurrent problems at
|
|
|
1181 elaboration time.
|
|
|
1182
|
|
|
1183 A task can be activated in two different ways:
|
|
|
1184
|
|
|
1185 * The task is created by an allocator in which case it is activated immediately
|
|
|
1186 after the allocator is evaluated.
|
|
|
1187
|
|
|
1188 * The task is declared at the library level or within some nested master in
|
|
|
1189 which case it is activated before starting execution of the statement
|
|
|
1190 sequence of the master defining the task.
|
|
|
1191
|
|
|
1192 Since the elaboration of a partition is performed by the environment task
|
|
|
1193 servicing that partition, any tasks activated during elaboration may be in
|
|
|
1194 a race with the environment task, and lead to unpredictable state and behavior.
|
|
|
1195 The static model seeks to avoid such interactions by assuming that all code in
|
|
|
1196 the task body is executed at elaboration time, if the task was activated by
|
|
|
1197 elaboration code.
|
|
|
1198
|
|
|
1199 ::
|
|
|
1200
|
|
|
1201 package Decls is
|
|
|
1202 task Lib_Task is
|
|
|
1203 entry Start;
|
|
|
1204 end Lib_Task;
|
|
|
1205
|
|
|
1206 type My_Int is new Integer;
|
|
|
1207
|
|
|
1208 function Ident (M : My_Int) return My_Int;
|
|
|
1209 end Decls;
|
|
|
1210
|
|
|
1211 ::
|
|
|
1212
|
|
|
1213 with Utils;
|
|
|
1214 package body Decls is
|
|
|
1215 task body Lib_Task is
|
|
|
1216 begin
|
|
|
1217 accept Start;
|
|
|
1218 Utils.Put_Val (2);
|
|
|
1219 end Lib_Task;
|
|
|
1220
|
|
|
1221 function Ident (M : My_Int) return My_Int is
|
|
|
1222 begin
|
|
|
1223 return M;
|
|
|
1224 end Ident;
|
|
|
1225 end Decls;
|
|
|
1226
|
|
|
1227 ::
|
|
|
1228
|
|
|
1229 with Decls;
|
|
|
1230 package Utils is
|
|
|
1231 procedure Put_Val (Arg : Decls.My_Int);
|
|
|
1232 end Utils;
|
|
|
1233
|
|
|
1234 ::
|
|
|
1235
|
|
|
1236 with Ada.Text_IO; use Ada.Text_IO;
|
|
|
1237 package body Utils is
|
|
|
1238 procedure Put_Val (Arg : Decls.My_Int) is
|
|
|
1239 begin
|
|
|
1240 Put_Line (Arg'Img);
|
|
|
1241 end Put_Val;
|
|
|
1242 end Utils;
|
|
|
1243
|
|
|
1244 ::
|
|
|
1245
|
|
|
1246 with Decls;
|
|
|
1247 procedure Main is
|
|
|
1248 begin
|
|
|
1249 Decls.Lib_Task.Start;
|
|
|
1250 end Main;
|
|
|
1251
|
|
|
1252 When the above example is compiled with the static model, an elaboration
|
|
|
1253 circularity arises:
|
|
|
1254
|
|
|
1255 ::
|
|
|
1256
|
|
|
1257 error: elaboration circularity detected
|
|
|
1258 info: "decls (body)" must be elaborated before "decls (body)"
|
|
|
1259 info: reason: implicit Elaborate_All in unit "decls (body)"
|
|
|
1260 info: recompile "decls (body)" with -gnatel for full details
|
|
|
1261 info: "decls (body)"
|
|
|
1262 info: must be elaborated along with its spec:
|
|
|
1263 info: "decls (spec)"
|
|
|
1264 info: which is withed by:
|
|
|
1265 info: "utils (spec)"
|
|
|
1266 info: which is withed by:
|
|
|
1267 info: "decls (body)"
|
|
|
1268
|
|
|
1269 In the above example, ``Decls`` must be elaborated prior to ``Main`` by virtue
|
|
|
1270 of a with clause. The elaboration of ``Decls`` activates task ``Lib_Task``. The
|
|
|
1271 static model conservatibely assumes that all code within the body of
|
|
|
1272 ``Lib_Task`` is executed, and generates an implicit ``Elaborate_All`` pragma
|
|
|
1273 for ``Units`` due to the call to ``Utils.Put_Val``. The pragma implies that
|
|
|
1274 both the spec and body of ``Utils``, along with any units they |with|,
|
|
|
1275 must be elaborated prior to ``Decls``. However, ``Utils``'s spec |withs|
|
|
|
1276 ``Decls``, implying that ``Decls`` must be elaborated before ``Utils``. The end
|
|
|
1277 result is that ``Utils`` must be elaborated prior to ``Utils``, and this
|
|
|
1278 leads to a circularity.
|
|
|
1279
|
|
|
1280 In reality, the example above will not exhibit an ABE problem at run time.
|
|
|
1281 When the body of task ``Lib_Task`` is activated, execution will wait for entry
|
|
|
1282 ``Start`` to be accepted, and the call to ``Utils.Put_Val`` will not take place
|
|
|
1283 at elaboration time. Task ``Lib_Task`` will resume its execution after the main
|
|
|
1284 program is executed because ``Main`` performs a rendezvous with
|
|
|
1285 ``Lib_Task.Start``, and at that point all units have already been elaborated.
|
|
|
1286 As a result, the static model may seem overly conservative, partly because it
|
|
|
1287 does not take control and data flow into account.
|
|
|
1288
|
|
|
1289 When faced with a task elaboration circularity, a programmer has several
|
|
|
1290 options available:
|
|
|
1291
|
|
|
1292 * *Use the dynamic model*
|
|
|
1293
|
|
|
1294 The dynamic model does not generate implicit ``Elaborate`` and
|
|
|
1295 ``Elaborate_All`` pragmas. Instead, it will install checks prior to every
|
|
|
1296 call in the example above, thus verifying the successful elaboration of
|
|
|
1297 ``Utils.Put_Val`` in case the call to it takes place at elaboration time.
|
|
|
1298 The dynamic model is enabled with compiler switch :switch:`-gnatE`.
|
|
|
1299
|
|
|
1300 * *Isolate the tasks*
|
|
|
1301
|
|
|
1302 Relocating tasks in their own separate package could decouple them from
|
|
|
1303 dependencies that would otherwise cause an elaboration circularity. The
|
|
|
1304 example above can be rewritten as follows:
|
|
|
1305
|
|
|
1306 ::
|
|
|
1307
|
|
|
1308 package Decls1 is -- new
|
|
|
1309 task Lib_Task is
|
|
|
1310 entry Start;
|
|
|
1311 end Lib_Task;
|
|
|
1312 end Decls1;
|
|
|
1313
|
|
|
1314 ::
|
|
|
1315
|
|
|
1316 with Utils;
|
|
|
1317 package body Decls1 is -- new
|
|
|
1318 task body Lib_Task is
|
|
|
1319 begin
|
|
|
1320 accept Start;
|
|
|
1321 Utils.Put_Val (2);
|
|
|
1322 end Lib_Task;
|
|
|
1323 end Decls1;
|
|
|
1324
|
|
|
1325 ::
|
|
|
1326
|
|
|
1327 package Decls2 is -- new
|
|
|
1328 type My_Int is new Integer;
|
|
|
1329 function Ident (M : My_Int) return My_Int;
|
|
|
1330 end Decls2;
|
|
|
1331
|
|
|
1332 ::
|
|
|
1333
|
|
|
1334 with Utils;
|
|
|
1335 package body Decls2 is -- new
|
|
|
1336 function Ident (M : My_Int) return My_Int is
|
|
|
1337 begin
|
|
|
1338 return M;
|
|
|
1339 end Ident;
|
|
|
1340 end Decls2;
|
|
|
1341
|
|
|
1342 ::
|
|
|
1343
|
|
|
1344 with Decls2;
|
|
|
1345 package Utils is
|
|
|
1346 procedure Put_Val (Arg : Decls2.My_Int);
|
|
|
1347 end Utils;
|
|
|
1348
|
|
|
1349 ::
|
|
|
1350
|
|
|
1351 with Ada.Text_IO; use Ada.Text_IO;
|
|
|
1352 package body Utils is
|
|
|
1353 procedure Put_Val (Arg : Decls2.My_Int) is
|
|
|
1354 begin
|
|
|
1355 Put_Line (Arg'Img);
|
|
|
1356 end Put_Val;
|
|
|
1357 end Utils;
|
|
|
1358
|
|
|
1359 ::
|
|
|
1360
|
|
|
1361 with Decls1;
|
|
|
1362 procedure Main is
|
|
|
1363 begin
|
|
|
1364 Decls1.Lib_Task.Start;
|
|
|
1365 end Main;
|
|
|
1366
|
|
|
1367 * *Declare the tasks*
|
|
|
1368
|
|
|
1369 The original example uses a single task declaration for ``Lib_Task``. An
|
|
|
1370 explicit task type declaration and a properly placed task object could avoid
|
|
|
1371 the dependencies that would otherwise cause an elaboration circularity. The
|
|
|
1372 example can be rewritten as follows:
|
|
|
1373
|
|
|
1374 ::
|
|
|
1375
|
|
|
1376 package Decls is
|
|
|
1377 task type Lib_Task is -- new
|
|
|
1378 entry Start;
|
|
|
1379 end Lib_Task;
|
|
|
1380
|
|
|
1381 type My_Int is new Integer;
|
|
|
1382
|
|
|
1383 function Ident (M : My_Int) return My_Int;
|
|
|
1384 end Decls;
|
|
|
1385
|
|
|
1386 ::
|
|
|
1387
|
|
|
1388 with Utils;
|
|
|
1389 package body Decls is
|
|
|
1390 task body Lib_Task is
|
|
|
1391 begin
|
|
|
1392 accept Start;
|
|
|
1393 Utils.Put_Val (2);
|
|
|
1394 end Lib_Task;
|
|
|
1395
|
|
|
1396 function Ident (M : My_Int) return My_Int is
|
|
|
1397 begin
|
|
|
1398 return M;
|
|
|
1399 end Ident;
|
|
|
1400 end Decls;
|
|
|
1401
|
|
|
1402 ::
|
|
|
1403
|
|
|
1404 with Decls;
|
|
|
1405 package Utils is
|
|
|
1406 procedure Put_Val (Arg : Decls.My_Int);
|
|
|
1407 end Utils;
|
|
|
1408
|
|
|
1409 ::
|
|
|
1410
|
|
|
1411 with Ada.Text_IO; use Ada.Text_IO;
|
|
|
1412 package body Utils is
|
|
|
1413 procedure Put_Val (Arg : Decls.My_Int) is
|
|
|
1414 begin
|
|
|
1415 Put_Line (Arg'Img);
|
|
|
1416 end Put_Val;
|
|
|
1417 end Utils;
|
|
|
1418
|
|
|
1419 ::
|
|
|
1420
|
|
|
1421 with Decls;
|
|
|
1422 package Obj_Decls is -- new
|
|
|
1423 Task_Obj : Decls.Lib_Task;
|
|
|
1424 end Obj_Decls;
|
|
|
1425
|
|
|
1426 ::
|
|
|
1427
|
|
|
1428 with Obj_Decls;
|
|
|
1429 procedure Main is
|
|
|
1430 begin
|
|
|
1431 Obj_Decls.Task_Obj.Start; -- new
|
|
|
1432 end Main;
|
|
|
1433
|
|
|
1434 * *Use restriction No_Entry_Calls_In_Elaboration_Code*
|
|
|
1435
|
|
|
1436 The issue exhibited in the original example under this section revolves
|
|
|
1437 around the body of ``Lib_Task`` blocking on an accept statement. There is
|
|
|
1438 no rule to prevent elaboration code from performing entry calls, however in
|
|
|
1439 practice this is highly unusual. In addition, the pattern of starting tasks
|
|
|
1440 at elaboration time and then immediately blocking on accept or select
|
|
|
1441 statements is quite common.
|
|
|
1442
|
|
|
1443 If a programmer knows that elaboration code will not perform any entry
|
|
|
1444 calls, then the programmer can indicate that the static model should not
|
|
|
1445 process the remainder of a task body once an accept or select statement has
|
|
|
1446 been encountered. This behavior can be specified by a configuration pragma:
|
|
|
1447
|
|
|
1448 ::
|
|
|
1449
|
|
|
1450 pragma Restrictions (No_Entry_Calls_In_Elaboration_Code);
|
|
|
1451
|
|
|
1452 In addition to the change in behavior with respect to task bodies, the
|
|
|
1453 static model will verify that no entry calls take place at elaboration time.
|
|
|
1454
|
|
|
1455 .. _Elaboration_Related_Compiler_Switches:
|
|
|
1456
|
|
|
1457 Elaboration-related Compiler Switches
|
|
|
1458 =====================================
|
|
|
1459
|
|
|
1460 GNAT has several switches that affect the elaboration model and consequently
|
|
|
1461 the elaboration order chosen by the binder.
|
|
|
1462
|
|
|
1463 .. index:: -gnatE (gnat)
|
|
|
1464
|
|
|
1465 :switch:`-gnatE`
|
|
|
1466 Dynamic elaboration checking mode enabled
|
|
|
1467
|
|
|
1468 When this switch is in effect, GNAT activates the dynamic elaboration model.
|
|
|
1469
|
|
|
1470 .. index:: -gnatel (gnat)
|
|
|
1471
|
|
|
1472 :switch:`-gnatel`
|
|
|
1473 Turn on info messages on generated Elaborate[_All] pragmas
|
|
|
1474
|
|
|
1475 When this switch is in effect, GNAT will emit the following supplementary
|
|
|
1476 information depending on the elaboration model in effect.
|
|
|
1477
|
|
|
1478 - *Dynamic model*
|
|
|
1479
|
|
|
1480 GNAT will indicate missing ``Elaborate`` and ``Elaborate_All`` pragmas for
|
|
|
1481 all library-level scenarios within the partition.
|
|
|
1482
|
|
|
1483 - *Static model*
|
|
|
1484
|
|
|
1485 GNAT will indicate all scenarios executed during elaboration. In addition,
|
|
|
1486 it will provide detailed traceback when an implicit ``Elaborate`` or
|
|
|
1487 ``Elaborate_All`` pragma is generated.
|
|
|
1488
|
|
|
1489 - *SPARK model*
|
|
|
1490
|
|
|
1491 GNAT will indicate how an elaboration requirement is met by the context of
|
|
|
1492 a unit. This diagnostic requires compiler switch :switch:`-gnatd.v`.
|
|
|
1493
|
|
|
1494 ::
|
|
|
1495
|
|
|
1496 1. with Server; pragma Elaborate_All (Server);
|
|
|
1497 2. package Client with SPARK_Mode is
|
|
|
1498 3. Val : constant Integer := Server.Func;
|
|
|
1499 |
|
|
|
1500 >>> info: call to "Func" during elaboration in SPARK
|
|
|
1501 >>> info: "Elaborate_All" requirement for unit "Server" met by pragma at line 1
|
|
|
1502
|
|
|
1503 4. end Client;
|
|
|
1504
|
|
131
|
1505 .. index:: -gnatH (gnat)
|
|
|
1506
|
|
|
1507 :switch:`-gnatH`
|
|
|
1508 Legacy elaboration checking mode enabled
|
|
|
1509
|
|
|
1510 When this switch is in effect, GNAT will utilize the pre-18.x elaboration
|
|
|
1511 model.
|
|
|
1512
|
|
|
1513 .. index:: -gnatJ (gnat)
|
|
|
1514
|
|
|
1515 :switch:`-gnatJ`
|
|
|
1516 Relaxed elaboration checking mode enabled
|
|
|
1517
|
|
|
1518 When this switch is in effect, GNAT will not process certain scenarios,
|
|
|
1519 resulting in a more permissive elaboration model. Note that this may
|
|
|
1520 eliminate some diagnostics and run-time checks.
|
|
|
1521
|
|
111
|
1522 .. index:: -gnatw.f (gnat)
|
|
|
1523
|
|
|
1524 :switch:`-gnatw.f`
|
|
|
1525 Turn on warnings for suspicious Subp'Access
|
|
|
1526
|
|
|
1527 When this switch is in effect, GNAT will treat ``'Access`` of an entry,
|
|
|
1528 operator, or subprogram as a potential call to the target and issue warnings:
|
|
|
1529
|
|
|
1530 ::
|
|
|
1531
|
|
|
1532 1. package body Attribute_Call is
|
|
|
1533 2. function Func return Integer;
|
|
|
1534 3. type Func_Ptr is access function return Integer;
|
|
|
1535 4.
|
|
|
1536 5. Ptr : constant Func_Ptr := Func'Access;
|
|
|
1537 |
|
|
|
1538 >>> warning: "Access" attribute of "Func" before body seen
|
|
|
1539 >>> warning: possible Program_Error on later references
|
|
|
1540 >>> warning: body of unit "Attribute_Call" elaborated
|
|
|
1541 >>> warning: "Access" of "Func" taken at line 5
|
|
|
1542
|
|
|
1543 6.
|
|
|
1544 7. function Func return Integer is
|
|
|
1545 8. begin
|
|
|
1546 9. ...
|
|
|
1547 10. end Func;
|
|
|
1548 11. end Attribute_Call;
|
|
|
1549
|
|
|
1550 In the example above, the elaboration of declaration ``Ptr`` is assigned
|
|
|
1551 ``Func'Access`` before the body of ``Func`` has been elaborated.
|
|
|
1552
|
|
131
|
1553 .. index:: -gnatwl (gnat)
|
|
|
1554
|
|
|
1555 :switch:`-gnatwl`
|
|
|
1556 Turn on warnings for elaboration problems
|
|
|
1557
|
|
|
1558 When this switch is in effect, GNAT emits diagnostics in the form of warnings
|
|
|
1559 concerning various elaboration problems. The warnings are enabled by default.
|
|
|
1560 The switch is provided in case all warnings are suppressed, but elaboration
|
|
|
1561 warnings are still desired.
|
|
|
1562
|
|
|
1563 :switch:`-gnatwL`
|
|
|
1564 Turn off warnings for elaboration problems
|
|
|
1565
|
|
|
1566 When this switch is in effect, GNAT no longer emits any diagnostics in the
|
|
|
1567 form of warnings. Selective suppression of elaboration problems is possible
|
|
|
1568 using ``pragma Warnings (Off)``.
|
|
|
1569
|
|
|
1570 ::
|
|
|
1571
|
|
|
1572 1. package body Selective_Suppression is
|
|
|
1573 2. function ABE return Integer;
|
|
|
1574 3.
|
|
|
1575 4. Val_1 : constant Integer := ABE;
|
|
|
1576 |
|
|
|
1577 >>> warning: cannot call "ABE" before body seen
|
|
|
1578 >>> warning: Program_Error will be raised at run time
|
|
|
1579
|
|
|
1580 5.
|
|
|
1581 6. pragma Warnings (Off);
|
|
|
1582 7. Val_2 : constant Integer := ABE;
|
|
|
1583 8. pragma Warnings (On);
|
|
|
1584 9.
|
|
|
1585 10. function ABE return Integer is
|
|
|
1586 11. begin
|
|
|
1587 12. ...
|
|
|
1588 13. end ABE;
|
|
|
1589 14. end Selective_Suppression;
|
|
|
1590
|
|
|
1591 Note that suppressing elaboration warnings does not eliminate run-time
|
|
|
1592 checks. The example above will still fail at run time with an ABE.
|
|
|
1593
|
|
111
|
1594 .. _Summary_of_Procedures_for_Elaboration_Control:
|
|
|
1595
|
|
|
1596 Summary of Procedures for Elaboration Control
|
|
|
1597 =============================================
|
|
|
1598
|
|
|
1599 A programmer should first compile the program with the default options, using
|
|
|
1600 none of the binder or compiler switches. If the binder succeeds in finding an
|
|
|
1601 elaboration order, then apart from possible cases involing dispatching calls
|
|
|
1602 and access-to-subprogram types, the program is free of elaboration errors.
|
|
131
|
1603
|
|
111
|
1604 If it is important for the program to be portable to compilers other than GNAT,
|
|
|
1605 then the programmer should use compiler switch :switch:`-gnatel` and consider
|
|
|
1606 the messages about missing or implicitly created ``Elaborate`` and
|
|
|
1607 ``Elaborate_All`` pragmas.
|
|
|
1608
|
|
|
1609 If the binder reports an elaboration circularity, the programmer has several
|
|
|
1610 options:
|
|
|
1611
|
|
131
|
1612 * Ensure that elaboration warnings are enabled. This will allow the static
|
|
|
1613 model to output trace information of elaboration issues. The trace
|
|
|
1614 information could shed light on previously unforeseen dependencies, as well
|
|
|
1615 as their origins. Elaboration warnings are enabled with compiler switch
|
|
|
1616 :switch:`-gnatwl`.
|
|
111
|
1617
|
|
|
1618 * Use switch :switch:`-gnatel` to obtain messages on generated implicit
|
|
|
1619 ``Elaborate`` and ``Elaborate_All`` pragmas. The trace information could
|
|
|
1620 indicate why a server unit must be elaborated prior to a client unit.
|
|
|
1621
|
|
|
1622 * If the warnings produced by the static model indicate that a task is
|
|
131
|
1623 involved, consider the options in section `Resolving Task Issues`_.
|
|
|
1624
|
|
|
1625 * If none of the steps outlined above resolve the circularity, use a more
|
|
|
1626 permissive elaboration model, in the following order:
|
|
|
1627
|
|
|
1628 - Use the dynamic elaboration model, with compiler switch :switch:`-gnatE`.
|
|
111
|
1629
|
|
131
|
1630 - Use the legacy static elaboration model, with compiler switch
|
|
|
1631 :switch:`-gnatH`.
|
|
|
1632
|
|
|
1633 - Use the legacy dynamic elaboration model, with compiler switches
|
|
|
1634 :switch:`-gnatH` :switch:`-gnatE`.
|
|
111
|
1635
|
|
131
|
1636 - Use the relaxed legacy static elaboration model, with compiler switches
|
|
|
1637 :switch:`-gnatH` :switch:`-gnatJ`.
|
|
|
1638
|
|
|
1639 - Use the relaxed legacy dynamic elaboration model, with compiler switches
|
|
|
1640 :switch:`-gnatH` :switch:`-gnatJ` :switch:`-gnatE`.
|
|
111
|
1641
|
|
|
1642 .. _Inspecting_the_Chosen_Elaboration_Order:
|
|
|
1643
|
|
|
1644 Inspecting the Chosen Elaboration Order
|
|
|
1645 =======================================
|
|
|
1646
|
|
|
1647 To see the elaboration order chosen by the binder, inspect the contents of file
|
|
|
1648 `b~xxx.adb`. On certain targets, this file appears as `b_xxx.adb`. The
|
|
|
1649 elaboration order appears as a sequence of calls to ``Elab_Body`` and
|
|
|
1650 ``Elab_Spec``, interspersed with assignments to `Exxx` which indicates that a
|
|
|
1651 particular unit is elaborated. For example:
|
|
|
1652
|
|
|
1653 ::
|
|
|
1654
|
|
|
1655 System.Soft_Links'Elab_Body;
|
|
|
1656 E14 := True;
|
|
|
1657 System.Secondary_Stack'Elab_Body;
|
|
|
1658 E18 := True;
|
|
|
1659 System.Exception_Table'Elab_Body;
|
|
|
1660 E24 := True;
|
|
|
1661 Ada.Io_Exceptions'Elab_Spec;
|
|
|
1662 E67 := True;
|
|
|
1663 Ada.Tags'Elab_Spec;
|
|
|
1664 Ada.Streams'Elab_Spec;
|
|
|
1665 E43 := True;
|
|
|
1666 Interfaces.C'Elab_Spec;
|
|
|
1667 E69 := True;
|
|
|
1668 System.Finalization_Root'Elab_Spec;
|
|
|
1669 E60 := True;
|
|
|
1670 System.Os_Lib'Elab_Body;
|
|
|
1671 E71 := True;
|
|
|
1672 System.Finalization_Implementation'Elab_Spec;
|
|
|
1673 System.Finalization_Implementation'Elab_Body;
|
|
|
1674 E62 := True;
|
|
|
1675 Ada.Finalization'Elab_Spec;
|
|
|
1676 E58 := True;
|
|
|
1677 Ada.Finalization.List_Controller'Elab_Spec;
|
|
|
1678 E76 := True;
|
|
|
1679 System.File_Control_Block'Elab_Spec;
|
|
|
1680 E74 := True;
|
|
|
1681 System.File_Io'Elab_Body;
|
|
|
1682 E56 := True;
|
|
|
1683 Ada.Tags'Elab_Body;
|
|
|
1684 E45 := True;
|
|
|
1685 Ada.Text_Io'Elab_Spec;
|
|
|
1686 Ada.Text_Io'Elab_Body;
|
|
|
1687 E07 := True;
|
|
|
1688
|
|
|
1689 Note also binder switch :switch:`-l`, which outputs the chosen elaboration
|
|
|
1690 order and provides a more readable form of the above:
|
|
|
1691
|
|
|
1692 ::
|
|
|
1693
|
|
|
1694 ada (spec)
|
|
|
1695 interfaces (spec)
|
|
|
1696 system (spec)
|
|
|
1697 system.case_util (spec)
|
|
|
1698 system.case_util (body)
|
|
|
1699 system.concat_2 (spec)
|
|
|
1700 system.concat_2 (body)
|
|
|
1701 system.concat_3 (spec)
|
|
|
1702 system.concat_3 (body)
|
|
|
1703 system.htable (spec)
|
|
|
1704 system.parameters (spec)
|
|
|
1705 system.parameters (body)
|
|
|
1706 system.crtl (spec)
|
|
|
1707 interfaces.c_streams (spec)
|
|
|
1708 interfaces.c_streams (body)
|
|
|
1709 system.restrictions (spec)
|
|
|
1710 system.restrictions (body)
|
|
|
1711 system.standard_library (spec)
|
|
|
1712 system.exceptions (spec)
|
|
|
1713 system.exceptions (body)
|
|
|
1714 system.storage_elements (spec)
|
|
|
1715 system.storage_elements (body)
|
|
|
1716 system.secondary_stack (spec)
|
|
|
1717 system.stack_checking (spec)
|
|
|
1718 system.stack_checking (body)
|
|
|
1719 system.string_hash (spec)
|
|
|
1720 system.string_hash (body)
|
|
|
1721 system.htable (body)
|
|
|
1722 system.strings (spec)
|
|
|
1723 system.strings (body)
|
|
|
1724 system.traceback (spec)
|
|
|
1725 system.traceback (body)
|
|
|
1726 system.traceback_entries (spec)
|
|
|
1727 system.traceback_entries (body)
|
|
|
1728 ada.exceptions (spec)
|
|
|
1729 ada.exceptions.last_chance_handler (spec)
|
|
|
1730 system.soft_links (spec)
|
|
|
1731 system.soft_links (body)
|
|
|
1732 ada.exceptions.last_chance_handler (body)
|
|
|
1733 system.secondary_stack (body)
|
|
|
1734 system.exception_table (spec)
|
|
|
1735 system.exception_table (body)
|
|
|
1736 ada.io_exceptions (spec)
|
|
|
1737 ada.tags (spec)
|
|
|
1738 ada.streams (spec)
|
|
|
1739 interfaces.c (spec)
|
|
|
1740 interfaces.c (body)
|
|
|
1741 system.finalization_root (spec)
|
|
|
1742 system.finalization_root (body)
|
|
|
1743 system.memory (spec)
|
|
|
1744 system.memory (body)
|
|
|
1745 system.standard_library (body)
|
|
|
1746 system.os_lib (spec)
|
|
|
1747 system.os_lib (body)
|
|
|
1748 system.unsigned_types (spec)
|
|
|
1749 system.stream_attributes (spec)
|
|
|
1750 system.stream_attributes (body)
|
|
|
1751 system.finalization_implementation (spec)
|
|
|
1752 system.finalization_implementation (body)
|
|
|
1753 ada.finalization (spec)
|
|
|
1754 ada.finalization (body)
|
|
|
1755 ada.finalization.list_controller (spec)
|
|
|
1756 ada.finalization.list_controller (body)
|
|
|
1757 system.file_control_block (spec)
|
|
|
1758 system.file_io (spec)
|
|
|
1759 system.file_io (body)
|
|
|
1760 system.val_uns (spec)
|
|
|
1761 system.val_util (spec)
|
|
|
1762 system.val_util (body)
|
|
|
1763 system.val_uns (body)
|
|
|
1764 system.wch_con (spec)
|
|
|
1765 system.wch_con (body)
|
|
|
1766 system.wch_cnv (spec)
|
|
|
1767 system.wch_jis (spec)
|
|
|
1768 system.wch_jis (body)
|
|
|
1769 system.wch_cnv (body)
|
|
|
1770 system.wch_stw (spec)
|
|
|
1771 system.wch_stw (body)
|
|
|
1772 ada.tags (body)
|
|
|
1773 ada.exceptions (body)
|
|
|
1774 ada.text_io (spec)
|
|
|
1775 ada.text_io (body)
|
|
|
1776 text_io (spec)
|
|
|
1777 gdbstr (body)
|
