]>
Commit | Line | Data |
---|---|---|
e94434ba | 1 | .. role:: switch(samp) |
2 | ||
bf5dffd3 | 3 | .. _Implementation_Defined_Pragmas: |
4 | ||
5 | ****************************** | |
6 | Implementation Defined Pragmas | |
7 | ****************************** | |
8 | ||
9 | Ada defines a set of pragmas that can be used to supply additional | |
10 | information to the compiler. These language defined pragmas are | |
11 | implemented in GNAT and work as described in the Ada Reference Manual. | |
12 | ||
13 | In addition, Ada allows implementations to define additional pragmas | |
14 | whose meaning is defined by the implementation. GNAT provides a number | |
15 | of these implementation-defined pragmas, which can be used to extend | |
16 | and enhance the functionality of the compiler. This section of the GNAT | |
17 | Reference Manual describes these additional pragmas. | |
18 | ||
19 | Note that any program using these pragmas might not be portable to other | |
20 | compilers (although GNAT implements this set of pragmas on all | |
21 | platforms). Therefore if portability to other compilers is an important | |
22 | consideration, the use of these pragmas should be minimized. | |
23 | ||
24 | Pragma Abort_Defer | |
25 | ================== | |
26 | ||
27 | .. index:: Deferring aborts | |
28 | ||
29 | Syntax: | |
30 | ||
31 | .. code-block:: ada | |
32 | ||
33 | pragma Abort_Defer; | |
34 | ||
35 | ||
36 | This pragma must appear at the start of the statement sequence of a | |
e94434ba | 37 | handled sequence of statements (right after the ``begin``). It has |
bf5dffd3 | 38 | the effect of deferring aborts for the sequence of statements (but not |
39 | for the declarations or handlers, if any, associated with this statement | |
40 | sequence). | |
41 | ||
39adf1e6 | 42 | .. _Pragma-Abstract_State: |
43 | ||
bf5dffd3 | 44 | Pragma Abstract_State |
45 | ===================== | |
46 | ||
d5dcec30 | 47 | Syntax: |
48 | ||
49 | .. code-block:: ada | |
50 | ||
51 | pragma Abstract_State (ABSTRACT_STATE_LIST); | |
52 | ||
53 | ABSTRACT_STATE_LIST ::= | |
54 | null | |
55 | | STATE_NAME_WITH_OPTIONS | |
56 | | (STATE_NAME_WITH_OPTIONS {, STATE_NAME_WITH_OPTIONS} ) | |
57 | ||
58 | STATE_NAME_WITH_OPTIONS ::= | |
59 | STATE_NAME | |
60 | | (STATE_NAME with OPTION_LIST) | |
61 | ||
62 | OPTION_LIST ::= OPTION {, OPTION} | |
63 | ||
64 | OPTION ::= | |
65 | SIMPLE_OPTION | |
66 | | NAME_VALUE_OPTION | |
67 | ||
68 | SIMPLE_OPTION ::= Ghost | Synchronous | |
69 | ||
70 | NAME_VALUE_OPTION ::= | |
71 | Part_Of => ABSTRACT_STATE | |
72 | | External [=> EXTERNAL_PROPERTY_LIST] | |
73 | ||
74 | EXTERNAL_PROPERTY_LIST ::= | |
75 | EXTERNAL_PROPERTY | |
76 | | (EXTERNAL_PROPERTY {, EXTERNAL_PROPERTY} ) | |
77 | ||
78 | EXTERNAL_PROPERTY ::= | |
79 | Async_Readers [=> boolean_EXPRESSION] | |
80 | | Async_Writers [=> boolean_EXPRESSION] | |
81 | | Effective_Reads [=> boolean_EXPRESSION] | |
82 | | Effective_Writes [=> boolean_EXPRESSION] | |
83 | others => boolean_EXPRESSION | |
84 | ||
85 | STATE_NAME ::= defining_identifier | |
86 | ||
87 | ABSTRACT_STATE ::= name | |
88 | ||
e94434ba | 89 | For the semantics of this pragma, see the entry for aspect ``Abstract_State`` in |
d5dcec30 | 90 | the SPARK 2014 Reference Manual, section 7.1.4. |
bf5dffd3 | 91 | |
d1540be4 | 92 | Pragma Acc_Parallel |
93 | =================== | |
94 | Syntax: | |
95 | ||
96 | .. code-block:: ada | |
97 | ||
98 | pragma Acc_Parallel [( ACC_PARALLEL_CLAUSE [, ACC_PARALLEL_CLAUSE... ])]; | |
99 | ||
100 | ACC_PARALLEL_CLAUSE ::= | |
101 | Acc_If => boolean_EXPRESSION | |
102 | | Acc_Private => IDENTIFIERS | |
103 | | Async => integer_EXPRESSION | |
104 | | Copy => IDENTIFIERS | |
105 | | Copy_In => IDENTIFIERS | |
106 | | Copy_Out => IDENTIFIERS | |
107 | | Create => IDENTIFIERS | |
108 | | Default => None | |
109 | | Device_Ptr => IDENTIFIERS | |
110 | | First_Private => IDENTIFIERS | |
111 | | Num_Gangs => integer_EXPRESSION | |
112 | | Num_Workers => integer_EXPRESSION | |
113 | | Present => IDENTIFIERS | |
114 | | Reduction => (REDUCTION_RECORD) | |
115 | | Vector_Length => integer_EXPRESSION | |
116 | | Wait => INTEGERS | |
117 | ||
118 | REDUCTION_RECORD ::= | |
119 | "+" => IDENTIFIERS | |
120 | | "*" => IDENTIFIERS | |
121 | | "min" => IDENTIFIERS | |
122 | | "max" => IDENTIFIERS | |
123 | | "or" => IDENTIFIERS | |
124 | | "and" => IDENTIFIERS | |
125 | ||
126 | IDENTIFIERS ::= | |
127 | | IDENTIFIER | |
128 | | (IDENTIFIER, IDENTIFIERS) | |
129 | ||
130 | INTEGERS ::= | |
131 | | integer_EXPRESSION | |
132 | | (integer_EXPRESSION, INTEGERS) | |
133 | ||
134 | Requires the :switch:`-fopenacc` flag. | |
135 | ||
136 | Equivalent to the ``parallel`` directive of the OpenAcc standard. This pragma | |
137 | should be placed in loops. It offloads the content of the loop to an | |
138 | accelerator device. | |
139 | ||
140 | For more information about the effect of the clauses, see the OpenAcc | |
141 | specification. | |
142 | ||
143 | Pragma Acc_Loop | |
144 | =============== | |
145 | Syntax: | |
146 | ||
147 | .. code-block:: ada | |
148 | ||
149 | pragma Acc_Loop [( ACC_LOOP_CLAUSE [, ACC_LOOP_CLAUSE... ])]; | |
150 | ||
151 | ACC_LOOP_CLAUSE ::= | |
152 | Auto | |
153 | | Collapse => INTEGER_LITERAL | |
154 | | Gang [=> GANG_ARG] | |
155 | | Independent | |
156 | | Private => IDENTIFIERS | |
157 | | Reduction => (REDUCTION_RECORD) | |
158 | | Seq | |
159 | | Tile => SIZE_EXPRESSION | |
160 | | Vector [=> integer_EXPRESSION] | |
161 | | Worker [=> integer_EXPRESSION] | |
162 | ||
163 | GANG_ARG ::= | |
164 | integer_EXPRESSION | |
165 | | Static => SIZE_EXPRESSION | |
166 | ||
167 | SIZE_EXPRESSION ::= | |
168 | * | |
169 | | integer_EXPRESSION | |
170 | ||
171 | Requires the :switch:`-fopenacc` flag. | |
172 | ||
173 | Equivalent to the ``loop`` directive of the OpenAcc standard. This pragma | |
174 | should be placed in for loops after the "Acc_Parallel" pragma. It tells the | |
175 | compiler how to parallelize the loop. | |
176 | ||
177 | For more information about the effect of the clauses, see the OpenAcc | |
178 | specification. | |
179 | ||
180 | Pragma Acc_Kernels | |
181 | ================== | |
182 | Syntax: | |
183 | ||
184 | .. code-block:: ada | |
185 | ||
186 | pragma Acc_Kernels [( ACC_KERNELS_CLAUSE [, ACC_KERNELS_CLAUSE...])]; | |
187 | ||
188 | ACC_KERNELS_CLAUSE ::= | |
189 | Acc_If => boolean_EXPRESSION | |
190 | | Async => integer_EXPRESSION | |
191 | | Copy => IDENTIFIERS | |
192 | | Copy_In => IDENTIFIERS | |
193 | | Copy_Out => IDENTIFIERS | |
194 | | Create => IDENTIFIERS | |
195 | | Default => None | |
196 | | Device_Ptr => IDENTIFIERS | |
197 | | Num_Gangs => integer_EXPRESSION | |
198 | | Num_Workers => integer_EXPRESSION | |
199 | | Present => IDENTIFIERS | |
200 | | Vector_Length => integer_EXPRESSION | |
201 | | Wait => INTEGERS | |
202 | ||
203 | IDENTIFIERS ::= | |
204 | | IDENTIFIER | |
205 | | (IDENTIFIER, IDENTIFIERS) | |
206 | ||
207 | INTEGERS ::= | |
208 | | integer_EXPRESSION | |
209 | | (integer_EXPRESSION, INTEGERS) | |
210 | ||
211 | Requires the :switch:`-fopenacc` flag. | |
212 | ||
213 | Equivalent to the kernels directive of the OpenAcc standard. This pragma should | |
214 | be placed in loops. | |
215 | ||
216 | For more information about the effect of the clauses, see the OpenAcc | |
217 | specification. | |
218 | ||
219 | Pragma Acc_Data | |
220 | =============== | |
221 | Syntax: | |
222 | ||
223 | .. code-block:: ada | |
224 | ||
225 | pragma Acc_Data ([ ACC_DATA_CLAUSE [, ACC_DATA_CLAUSE...]]); | |
226 | ||
227 | ACC_DATA_CLAUSE ::= | |
228 | Copy => IDENTIFIERS | |
229 | | Copy_In => IDENTIFIERS | |
230 | | Copy_Out => IDENTIFIERS | |
231 | | Create => IDENTIFIERS | |
232 | | Device_Ptr => IDENTIFIERS | |
233 | | Present => IDENTIFIERS | |
234 | ||
235 | Requires the :switch:`-fopenacc` flag. | |
236 | ||
237 | Equivalent to the ``data`` directive of the OpenAcc standard. This pragma | |
238 | should be placed in loops. | |
239 | ||
240 | For more information about the effect of the clauses, see the OpenAcc | |
241 | specification. | |
242 | ||
243 | ||
bf5dffd3 | 244 | Pragma Ada_83 |
245 | ============= | |
246 | ||
247 | Syntax: | |
248 | ||
249 | .. code-block:: ada | |
250 | ||
251 | pragma Ada_83; | |
252 | ||
253 | ||
254 | A configuration pragma that establishes Ada 83 mode for the unit to | |
255 | which it applies, regardless of the mode set by the command line | |
256 | switches. In Ada 83 mode, GNAT attempts to be as compatible with | |
257 | the syntax and semantics of Ada 83, as defined in the original Ada | |
258 | 83 Reference Manual as possible. In particular, the keywords added by Ada 95 | |
259 | and Ada 2005 are not recognized, optional package bodies are allowed, | |
260 | and generics may name types with unknown discriminants without using | |
e94434ba | 261 | the ``(<>)`` notation. In addition, some but not all of the additional |
bf5dffd3 | 262 | restrictions of Ada 83 are enforced. |
263 | ||
264 | Ada 83 mode is intended for two purposes. Firstly, it allows existing | |
265 | Ada 83 code to be compiled and adapted to GNAT with less effort. | |
266 | Secondly, it aids in keeping code backwards compatible with Ada 83. | |
267 | However, there is no guarantee that code that is processed correctly | |
268 | by GNAT in Ada 83 mode will in fact compile and execute with an Ada | |
269 | 83 compiler, since GNAT does not enforce all the additional checks | |
270 | required by Ada 83. | |
271 | ||
272 | Pragma Ada_95 | |
273 | ============= | |
274 | ||
275 | Syntax: | |
276 | ||
277 | .. code-block:: ada | |
278 | ||
279 | pragma Ada_95; | |
280 | ||
281 | ||
282 | A configuration pragma that establishes Ada 95 mode for the unit to which | |
283 | it applies, regardless of the mode set by the command line switches. | |
e94434ba | 284 | This mode is set automatically for the ``Ada`` and ``System`` |
bf5dffd3 | 285 | packages and their children, so you need not specify it in these |
286 | contexts. This pragma is useful when writing a reusable component that | |
287 | itself uses Ada 95 features, but which is intended to be usable from | |
288 | either Ada 83 or Ada 95 programs. | |
289 | ||
290 | Pragma Ada_05 | |
291 | ============= | |
292 | ||
293 | Syntax: | |
294 | ||
295 | .. code-block:: ada | |
296 | ||
297 | pragma Ada_05; | |
298 | pragma Ada_05 (local_NAME); | |
299 | ||
300 | ||
301 | A configuration pragma that establishes Ada 2005 mode for the unit to which | |
302 | it applies, regardless of the mode set by the command line switches. | |
303 | This pragma is useful when writing a reusable component that | |
304 | itself uses Ada 2005 features, but which is intended to be usable from | |
305 | either Ada 83 or Ada 95 programs. | |
306 | ||
307 | The one argument form (which is not a configuration pragma) | |
308 | is used for managing the transition from | |
309 | Ada 95 to Ada 2005 in the run-time library. If an entity is marked | |
310 | as Ada_2005 only, then referencing the entity in Ada_83 or Ada_95 | |
311 | mode will generate a warning. In addition, in Ada_83 or Ada_95 | |
312 | mode, a preference rule is established which does not choose | |
313 | such an entity unless it is unambiguously specified. This avoids | |
314 | extra subprograms marked this way from generating ambiguities in | |
315 | otherwise legal pre-Ada_2005 programs. The one argument form is | |
316 | intended for exclusive use in the GNAT run-time library. | |
317 | ||
318 | Pragma Ada_2005 | |
319 | =============== | |
320 | ||
321 | Syntax: | |
322 | ||
323 | .. code-block:: ada | |
324 | ||
325 | pragma Ada_2005; | |
326 | ||
327 | ||
328 | This configuration pragma is a synonym for pragma Ada_05 and has the | |
329 | same syntax and effect. | |
330 | ||
331 | Pragma Ada_12 | |
332 | ============= | |
333 | ||
334 | Syntax: | |
335 | ||
336 | .. code-block:: ada | |
337 | ||
338 | pragma Ada_12; | |
339 | pragma Ada_12 (local_NAME); | |
340 | ||
341 | ||
342 | A configuration pragma that establishes Ada 2012 mode for the unit to which | |
343 | it applies, regardless of the mode set by the command line switches. | |
e94434ba | 344 | This mode is set automatically for the ``Ada`` and ``System`` |
bf5dffd3 | 345 | packages and their children, so you need not specify it in these |
346 | contexts. This pragma is useful when writing a reusable component that | |
347 | itself uses Ada 2012 features, but which is intended to be usable from | |
348 | Ada 83, Ada 95, or Ada 2005 programs. | |
349 | ||
350 | The one argument form, which is not a configuration pragma, | |
351 | is used for managing the transition from Ada | |
352 | 2005 to Ada 2012 in the run-time library. If an entity is marked | |
6df5adf1 | 353 | as Ada_2012 only, then referencing the entity in any pre-Ada_2012 |
bf5dffd3 | 354 | mode will generate a warning. In addition, in any pre-Ada_2012 |
355 | mode, a preference rule is established which does not choose | |
356 | such an entity unless it is unambiguously specified. This avoids | |
357 | extra subprograms marked this way from generating ambiguities in | |
358 | otherwise legal pre-Ada_2012 programs. The one argument form is | |
359 | intended for exclusive use in the GNAT run-time library. | |
360 | ||
361 | Pragma Ada_2012 | |
362 | =============== | |
363 | ||
364 | Syntax: | |
365 | ||
366 | .. code-block:: ada | |
367 | ||
368 | pragma Ada_2012; | |
369 | ||
370 | ||
371 | This configuration pragma is a synonym for pragma Ada_12 and has the | |
372 | same syntax and effect. | |
373 | ||
6b0b9e72 | 374 | Pragma Aggregate_Individually_Assign |
375 | ==================================== | |
376 | ||
377 | Syntax: | |
378 | ||
379 | .. code-block:: ada | |
380 | ||
381 | pragma Aggregate_Individually_Assign; | |
382 | ||
7a5b8c31 | 383 | Where possible, GNAT will store the binary representation of a record aggregate |
6b0b9e72 | 384 | in memory for space and performance reasons. This configuration pragma changes |
7a5b8c31 | 385 | this behavior so that record aggregates are instead always converted into |
6b0b9e72 | 386 | individual assignment statements. |
387 | ||
388 | ||
bf5dffd3 | 389 | Pragma Allow_Integer_Address |
390 | ============================ | |
391 | ||
392 | Syntax: | |
393 | ||
394 | .. code-block:: ada | |
395 | ||
396 | pragma Allow_Integer_Address; | |
397 | ||
398 | ||
e94434ba | 399 | In almost all versions of GNAT, ``System.Address`` is a private |
bf5dffd3 | 400 | type in accordance with the implementation advice in the RM. This |
401 | means that integer values, | |
402 | in particular integer literals, are not allowed as address values. | |
403 | If the configuration pragma | |
e94434ba | 404 | ``Allow_Integer_Address`` is given, then integer expressions may |
405 | be used anywhere a value of type ``System.Address`` is required. | |
bf5dffd3 | 406 | The effect is to introduce an implicit unchecked conversion from the |
e94434ba | 407 | integer value to type ``System.Address``. The reverse case of using |
bf5dffd3 | 408 | an address where an integer type is required is handled analogously. |
409 | The following example compiles without errors: | |
410 | ||
411 | ||
412 | .. code-block:: ada | |
413 | ||
414 | pragma Allow_Integer_Address; | |
415 | with System; use System; | |
416 | package AddrAsInt is | |
417 | X : Integer; | |
418 | Y : Integer; | |
419 | for X'Address use 16#1240#; | |
420 | for Y use at 16#3230#; | |
421 | m : Address := 16#4000#; | |
422 | n : constant Address := 4000; | |
423 | p : constant Address := Address (X + Y); | |
424 | v : Integer := y'Address; | |
425 | w : constant Integer := Integer (Y'Address); | |
426 | type R is new integer; | |
427 | RR : R := 1000; | |
428 | Z : Integer; | |
429 | for Z'Address use RR; | |
430 | end AddrAsInt; | |
431 | ||
432 | ||
e94434ba | 433 | Note that pragma ``Allow_Integer_Address`` is ignored if ``System.Address`` |
434 | is not a private type. In implementations of ``GNAT`` where | |
bf5dffd3 | 435 | System.Address is a visible integer type, |
436 | this pragma serves no purpose but is ignored | |
437 | rather than rejected to allow common sets of sources to be used | |
438 | in the two situations. | |
439 | ||
39adf1e6 | 440 | .. _Pragma-Annotate: |
441 | ||
bf5dffd3 | 442 | Pragma Annotate |
443 | =============== | |
444 | ||
445 | Syntax:: | |
446 | ||
447 | pragma Annotate (IDENTIFIER [, IDENTIFIER {, ARG}] [, entity => local_NAME]); | |
448 | ||
449 | ARG ::= NAME | EXPRESSION | |
450 | ||
451 | ||
e94434ba | 452 | This pragma is used to annotate programs. IDENTIFIER identifies |
bf5dffd3 | 453 | the type of annotation. GNAT verifies that it is an identifier, but does |
454 | not otherwise analyze it. The second optional identifier is also left | |
455 | unanalyzed, and by convention is used to control the action of the tool to | |
e94434ba | 456 | which the annotation is addressed. The remaining ARG arguments |
bf5dffd3 | 457 | can be either string literals or more generally expressions. |
458 | String literals are assumed to be either of type | |
e94434ba | 459 | ``Standard.String`` or else ``Wide_String`` or ``Wide_Wide_String`` |
bf5dffd3 | 460 | depending on the character literals they contain. |
461 | All other kinds of arguments are analyzed as expressions, and must be | |
462 | unambiguous. The last argument if present must have the identifier | |
e94434ba | 463 | ``Entity`` and GNAT verifies that a local name is given. |
bf5dffd3 | 464 | |
465 | The analyzed pragma is retained in the tree, but not otherwise processed | |
466 | by any part of the GNAT compiler, except to generate corresponding note | |
467 | lines in the generated ALI file. For the format of these note lines, see | |
468 | the compiler source file lib-writ.ads. This pragma is intended for use by | |
469 | external tools, including ASIS. The use of pragma Annotate does not | |
470 | affect the compilation process in any way. This pragma may be used as | |
471 | a configuration pragma. | |
472 | ||
473 | Pragma Assert | |
474 | ============= | |
475 | ||
476 | Syntax:: | |
477 | ||
478 | pragma Assert ( | |
479 | boolean_EXPRESSION | |
480 | [, string_EXPRESSION]); | |
481 | ||
482 | ||
483 | The effect of this pragma depends on whether the corresponding command | |
484 | line switch is set to activate assertions. The pragma expands into code | |
485 | equivalent to the following: | |
486 | ||
487 | .. code-block:: ada | |
488 | ||
489 | if assertions-enabled then | |
490 | if not boolean_EXPRESSION then | |
491 | System.Assertions.Raise_Assert_Failure | |
492 | (string_EXPRESSION); | |
493 | end if; | |
494 | end if; | |
495 | ||
496 | ||
497 | The string argument, if given, is the message that will be associated | |
498 | with the exception occurrence if the exception is raised. If no second | |
e94434ba | 499 | argument is given, the default message is ``file``:``nnn``, |
500 | where ``file`` is the name of the source file containing the assert, | |
501 | and ``nnn`` is the line number of the assert. | |
bf5dffd3 | 502 | |
e94434ba | 503 | Note that, as with the ``if`` statement to which it is equivalent, the |
504 | type of the expression is either ``Standard.Boolean``, or any type derived | |
bf5dffd3 | 505 | from this standard type. |
506 | ||
507 | Assert checks can be either checked or ignored. By default they are ignored. | |
508 | They will be checked if either the command line switch *-gnata* is | |
e94434ba | 509 | used, or if an ``Assertion_Policy`` or ``Check_Policy`` pragma is used |
510 | to enable ``Assert_Checks``. | |
bf5dffd3 | 511 | |
512 | If assertions are ignored, then there | |
513 | is no run-time effect (and in particular, any side effects from the | |
514 | expression will not occur at run time). (The expression is still | |
515 | analyzed at compile time, and may cause types to be frozen if they are | |
516 | mentioned here for the first time). | |
517 | ||
518 | If assertions are checked, then the given expression is tested, and if | |
e94434ba | 519 | it is ``False`` then ``System.Assertions.Raise_Assert_Failure`` is called |
520 | which results in the raising of ``Assert_Failure`` with the given message. | |
bf5dffd3 | 521 | |
522 | You should generally avoid side effects in the expression arguments of | |
523 | this pragma, because these side effects will turn on and off with the | |
524 | setting of the assertions mode, resulting in assertions that have an | |
525 | effect on the program. However, the expressions are analyzed for | |
526 | semantic correctness whether or not assertions are enabled, so turning | |
527 | assertions on and off cannot affect the legality of a program. | |
528 | ||
e94434ba | 529 | Note that the implementation defined policy ``DISABLE``, given in a |
530 | pragma ``Assertion_Policy``, can be used to suppress this semantic analysis. | |
bf5dffd3 | 531 | |
532 | Note: this is a standard language-defined pragma in versions | |
533 | of Ada from 2005 on. In GNAT, it is implemented in all versions | |
534 | of Ada, and the DISABLE policy is an implementation-defined | |
535 | addition. | |
536 | ||
537 | Pragma Assert_And_Cut | |
538 | ===================== | |
539 | ||
540 | Syntax:: | |
541 | ||
542 | pragma Assert_And_Cut ( | |
543 | boolean_EXPRESSION | |
544 | [, string_EXPRESSION]); | |
545 | ||
546 | ||
e94434ba | 547 | The effect of this pragma is identical to that of pragma ``Assert``, |
548 | except that in an ``Assertion_Policy`` pragma, the identifier | |
549 | ``Assert_And_Cut`` is used to control whether it is ignored or checked | |
bf5dffd3 | 550 | (or disabled). |
551 | ||
552 | The intention is that this be used within a subprogram when the | |
553 | given test expresion sums up all the work done so far in the | |
554 | subprogram, so that the rest of the subprogram can be verified | |
555 | (informally or formally) using only the entry preconditions, | |
556 | and the expression in this pragma. This allows dividing up | |
557 | a subprogram into sections for the purposes of testing or | |
558 | formal verification. The pragma also serves as useful | |
559 | documentation. | |
560 | ||
561 | Pragma Assertion_Policy | |
562 | ======================= | |
563 | ||
564 | Syntax:: | |
565 | ||
114e77f8 | 566 | pragma Assertion_Policy (CHECK | DISABLE | IGNORE | SUPPRESSIBLE); |
bf5dffd3 | 567 | |
568 | pragma Assertion_Policy ( | |
569 | ASSERTION_KIND => POLICY_IDENTIFIER | |
570 | {, ASSERTION_KIND => POLICY_IDENTIFIER}); | |
571 | ||
572 | ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND | |
573 | ||
574 | RM_ASSERTION_KIND ::= Assert | | |
575 | Static_Predicate | | |
576 | Dynamic_Predicate | | |
577 | Pre | | |
578 | Pre'Class | | |
579 | Post | | |
580 | Post'Class | | |
581 | Type_Invariant | | |
582 | Type_Invariant'Class | |
583 | ||
584 | ID_ASSERTION_KIND ::= Assertions | | |
585 | Assert_And_Cut | | |
586 | Assume | | |
587 | Contract_Cases | | |
588 | Debug | | |
62c47568 | 589 | Ghost | |
bf5dffd3 | 590 | Invariant | |
591 | Invariant'Class | | |
592 | Loop_Invariant | | |
593 | Loop_Variant | | |
594 | Postcondition | | |
595 | Precondition | | |
596 | Predicate | | |
597 | Refined_Post | | |
598 | Statement_Assertions | |
599 | ||
0c01a524 | 600 | POLICY_IDENTIFIER ::= Check | Disable | Ignore | Suppressible |
bf5dffd3 | 601 | |
602 | ||
603 | This is a standard Ada 2012 pragma that is available as an | |
604 | implementation-defined pragma in earlier versions of Ada. | |
e94434ba | 605 | The assertion kinds ``RM_ASSERTION_KIND`` are those defined in |
606 | the Ada standard. The assertion kinds ``ID_ASSERTION_KIND`` | |
bf5dffd3 | 607 | are implementation defined additions recognized by the GNAT compiler. |
608 | ||
609 | The pragma applies in both cases to pragmas and aspects with matching | |
e94434ba | 610 | names, e.g. ``Pre`` applies to the Pre aspect, and ``Precondition`` |
611 | applies to both the ``Precondition`` pragma | |
612 | and the aspect ``Precondition``. Note that the identifiers for | |
bf5dffd3 | 613 | pragmas Pre_Class and Post_Class are Pre'Class and Post'Class (not |
614 | Pre_Class and Post_Class), since these pragmas are intended to be | |
615 | identical to the corresponding aspects). | |
616 | ||
e94434ba | 617 | If the policy is ``CHECK``, then assertions are enabled, i.e. |
bf5dffd3 | 618 | the corresponding pragma or aspect is activated. |
e94434ba | 619 | If the policy is ``IGNORE``, then assertions are ignored, i.e. |
bf5dffd3 | 620 | the corresponding pragma or aspect is deactivated. |
621 | This pragma overrides the effect of the *-gnata* switch on the | |
622 | command line. | |
e94434ba | 623 | If the policy is ``SUPPRESSIBLE``, then assertions are enabled by default, |
0c01a524 | 624 | however, if the *-gnatp* switch is specified all assertions are ignored. |
bf5dffd3 | 625 | |
e94434ba | 626 | The implementation defined policy ``DISABLE`` is like |
627 | ``IGNORE`` except that it completely disables semantic | |
bf5dffd3 | 628 | checking of the corresponding pragma or aspect. This is |
629 | useful when the pragma or aspect argument references subprograms | |
630 | in a with'ed package which is replaced by a dummy package | |
631 | for the final build. | |
632 | ||
e94434ba | 633 | The implementation defined assertion kind ``Assertions`` applies to all |
bf5dffd3 | 634 | assertion kinds. The form with no assertion kind given implies this |
635 | choice, so it applies to all assertion kinds (RM defined, and | |
636 | implementation defined). | |
637 | ||
e94434ba | 638 | The implementation defined assertion kind ``Statement_Assertions`` |
639 | applies to ``Assert``, ``Assert_And_Cut``, | |
640 | ``Assume``, ``Loop_Invariant``, and ``Loop_Variant``. | |
bf5dffd3 | 641 | |
642 | Pragma Assume | |
643 | ============= | |
644 | ||
645 | Syntax: | |
646 | ||
647 | :: | |
648 | ||
649 | pragma Assume ( | |
650 | boolean_EXPRESSION | |
651 | [, string_EXPRESSION]); | |
652 | ||
653 | ||
e94434ba | 654 | The effect of this pragma is identical to that of pragma ``Assert``, |
655 | except that in an ``Assertion_Policy`` pragma, the identifier | |
656 | ``Assume`` is used to control whether it is ignored or checked | |
bf5dffd3 | 657 | (or disabled). |
658 | ||
659 | The intention is that this be used for assumptions about the | |
660 | external environment. So you cannot expect to verify formally | |
661 | or informally that the condition is met, this must be | |
662 | established by examining things outside the program itself. | |
663 | For example, we may have code that depends on the size of | |
e94434ba | 664 | ``Long_Long_Integer`` being at least 64. So we could write: |
bf5dffd3 | 665 | |
666 | .. code-block:: ada | |
667 | ||
668 | pragma Assume (Long_Long_Integer'Size >= 64); | |
669 | ||
670 | ||
671 | This assumption cannot be proved from the program itself, | |
672 | but it acts as a useful run-time check that the assumption | |
673 | is met, and documents the need to ensure that it is met by | |
674 | reference to information outside the program. | |
675 | ||
676 | Pragma Assume_No_Invalid_Values | |
677 | =============================== | |
678 | .. index:: Invalid representations | |
679 | ||
680 | .. index:: Invalid values | |
681 | ||
682 | Syntax: | |
683 | ||
684 | .. code-block:: ada | |
685 | ||
686 | pragma Assume_No_Invalid_Values (On | Off); | |
687 | ||
688 | ||
689 | This is a configuration pragma that controls the assumptions made by the | |
690 | compiler about the occurrence of invalid representations (invalid values) | |
691 | in the code. | |
692 | ||
693 | The default behavior (corresponding to an Off argument for this pragma), is | |
694 | to assume that values may in general be invalid unless the compiler can | |
695 | prove they are valid. Consider the following example: | |
696 | ||
697 | .. code-block:: ada | |
698 | ||
699 | V1 : Integer range 1 .. 10; | |
700 | V2 : Integer range 11 .. 20; | |
701 | ... | |
702 | for J in V2 .. V1 loop | |
703 | ... | |
704 | end loop; | |
705 | ||
706 | ||
707 | if V1 and V2 have valid values, then the loop is known at compile | |
708 | time not to execute since the lower bound must be greater than the | |
709 | upper bound. However in default mode, no such assumption is made, | |
e94434ba | 710 | and the loop may execute. If ``Assume_No_Invalid_Values (On)`` |
bf5dffd3 | 711 | is given, the compiler will assume that any occurrence of a variable |
e94434ba | 712 | other than in an explicit ``'Valid`` test always has a valid |
bf5dffd3 | 713 | value, and the loop above will be optimized away. |
714 | ||
e94434ba | 715 | The use of ``Assume_No_Invalid_Values (On)`` is appropriate if |
bf5dffd3 | 716 | you know your code is free of uninitialized variables and other |
717 | possible sources of invalid representations, and may result in | |
718 | more efficient code. A program that accesses an invalid representation | |
719 | with this pragma in effect is erroneous, so no guarantees can be made | |
720 | about its behavior. | |
721 | ||
722 | It is peculiar though permissible to use this pragma in conjunction | |
723 | with validity checking (-gnatVa). In such cases, accessing invalid | |
724 | values will generally give an exception, though formally the program | |
725 | is erroneous so there are no guarantees that this will always be the | |
726 | case, and it is recommended that these two options not be used together. | |
727 | ||
39adf1e6 | 728 | .. _Pragma-Async_Readers: |
729 | ||
bf5dffd3 | 730 | Pragma Async_Readers |
731 | ==================== | |
732 | ||
d5dcec30 | 733 | Syntax: |
734 | ||
735 | .. code-block:: ada | |
736 | ||
e94f4600 | 737 | pragma Async_Readers [ (boolean_EXPRESSION) ]; |
d5dcec30 | 738 | |
e94434ba | 739 | For the semantics of this pragma, see the entry for aspect ``Async_Readers`` in |
d5dcec30 | 740 | the SPARK 2014 Reference Manual, section 7.1.2. |
bf5dffd3 | 741 | |
39adf1e6 | 742 | .. _Pragma-Async_Writers: |
743 | ||
bf5dffd3 | 744 | Pragma Async_Writers |
745 | ==================== | |
746 | ||
d5dcec30 | 747 | Syntax: |
748 | ||
749 | .. code-block:: ada | |
750 | ||
e94f4600 | 751 | pragma Async_Writers [ (boolean_EXPRESSION) ]; |
d5dcec30 | 752 | |
e94434ba | 753 | For the semantics of this pragma, see the entry for aspect ``Async_Writers`` in |
d5dcec30 | 754 | the SPARK 2014 Reference Manual, section 7.1.2. |
bf5dffd3 | 755 | |
756 | Pragma Attribute_Definition | |
757 | =========================== | |
758 | ||
759 | Syntax: | |
760 | ||
761 | :: | |
762 | ||
763 | pragma Attribute_Definition | |
764 | ([Attribute =>] ATTRIBUTE_DESIGNATOR, | |
765 | [Entity =>] LOCAL_NAME, | |
766 | [Expression =>] EXPRESSION | NAME); | |
767 | ||
768 | ||
e94434ba | 769 | If ``Attribute`` is a known attribute name, this pragma is equivalent to |
bf5dffd3 | 770 | the attribute definition clause: |
771 | ||
772 | ||
773 | .. code-block:: ada | |
774 | ||
775 | for Entity'Attribute use Expression; | |
776 | ||
777 | ||
e94434ba | 778 | If ``Attribute`` is not a recognized attribute name, the pragma is |
bf5dffd3 | 779 | ignored, and a warning is emitted. This allows source |
780 | code to be written that takes advantage of some new attribute, while remaining | |
781 | compilable with earlier compilers. | |
782 | ||
783 | Pragma C_Pass_By_Copy | |
784 | ===================== | |
785 | .. index:: Passing by copy | |
786 | ||
787 | ||
788 | Syntax: | |
789 | ||
790 | :: | |
791 | ||
792 | pragma C_Pass_By_Copy | |
793 | ([Max_Size =>] static_integer_EXPRESSION); | |
794 | ||
795 | ||
796 | Normally the default mechanism for passing C convention records to C | |
797 | convention subprograms is to pass them by reference, as suggested by RM | |
e94434ba | 798 | B.3(69). Use the configuration pragma ``C_Pass_By_Copy`` to change |
bf5dffd3 | 799 | this default, by requiring that record formal parameters be passed by |
800 | copy if all of the following conditions are met: | |
801 | ||
802 | * | |
803 | The size of the record type does not exceed the value specified for | |
e94434ba | 804 | ``Max_Size``. |
bf5dffd3 | 805 | * |
e94434ba | 806 | The record type has ``Convention C``. |
bf5dffd3 | 807 | * |
808 | The formal parameter has this record type, and the subprogram has a | |
809 | foreign (non-Ada) convention. | |
810 | ||
811 | If these conditions are met the argument is passed by copy; i.e., in a | |
812 | manner consistent with what C expects if the corresponding formal in the | |
813 | C prototype is a struct (rather than a pointer to a struct). | |
814 | ||
815 | You can also pass records by copy by specifying the convention | |
e94434ba | 816 | ``C_Pass_By_Copy`` for the record type, or by using the extended |
817 | ``Import`` and ``Export`` pragmas, which allow specification of | |
bf5dffd3 | 818 | passing mechanisms on a parameter by parameter basis. |
819 | ||
820 | Pragma Check | |
821 | ============ | |
822 | .. index:: Assertions | |
823 | ||
824 | .. index:: Named assertions | |
825 | ||
826 | ||
827 | Syntax: | |
828 | ||
829 | :: | |
830 | ||
831 | pragma Check ( | |
832 | [Name =>] CHECK_KIND, | |
833 | [Check =>] Boolean_EXPRESSION | |
834 | [, [Message =>] string_EXPRESSION] ); | |
835 | ||
836 | CHECK_KIND ::= IDENTIFIER | | |
837 | Pre'Class | | |
838 | Post'Class | | |
839 | Type_Invariant'Class | | |
840 | Invariant'Class | |
841 | ||
842 | ||
e94434ba | 843 | This pragma is similar to the predefined pragma ``Assert`` except that an |
bf5dffd3 | 844 | extra identifier argument is present. In conjunction with pragma |
e94434ba | 845 | ``Check_Policy``, this can be used to define groups of assertions that can |
846 | be independently controlled. The identifier ``Assertion`` is special, it | |
847 | refers to the normal set of pragma ``Assert`` statements. | |
bf5dffd3 | 848 | |
849 | Checks introduced by this pragma are normally deactivated by default. They can | |
850 | be activated either by the command line option *-gnata*, which turns on | |
e94434ba | 851 | all checks, or individually controlled using pragma ``Check_Policy``. |
bf5dffd3 | 852 | |
e94434ba | 853 | The identifiers ``Assertions`` and ``Statement_Assertions`` are not |
bf5dffd3 | 854 | permitted as check kinds, since this would cause confusion with the use |
e94434ba | 855 | of these identifiers in ``Assertion_Policy`` and ``Check_Policy`` |
bf5dffd3 | 856 | pragmas, where they are used to refer to sets of assertions. |
857 | ||
858 | Pragma Check_Float_Overflow | |
859 | =========================== | |
860 | .. index:: Floating-point overflow | |
861 | ||
862 | ||
863 | Syntax: | |
864 | ||
865 | .. code-block:: ada | |
866 | ||
867 | pragma Check_Float_Overflow; | |
868 | ||
869 | ||
e94434ba | 870 | In Ada, the predefined floating-point types (``Short_Float``, |
871 | ``Float``, ``Long_Float``, ``Long_Long_Float``) are | |
bf5dffd3 | 872 | defined to be *unconstrained*. This means that even though each |
873 | has a well-defined base range, an operation that delivers a result | |
874 | outside this base range is not required to raise an exception. | |
875 | This implementation permission accommodates the notion | |
876 | of infinities in IEEE floating-point, and corresponds to the | |
877 | efficient execution mode on most machines. GNAT will not raise | |
878 | overflow exceptions on these machines; instead it will generate | |
879 | infinities and NaN's as defined in the IEEE standard. | |
880 | ||
881 | Generating infinities, although efficient, is not always desirable. | |
882 | Often the preferable approach is to check for overflow, even at the | |
883 | (perhaps considerable) expense of run-time performance. | |
884 | This can be accomplished by defining your own constrained floating-point subtypes -- i.e., by supplying explicit | |
885 | range constraints -- and indeed such a subtype | |
886 | can have the same base range as its base type. For example: | |
887 | ||
888 | ||
889 | .. code-block:: ada | |
890 | ||
891 | subtype My_Float is Float range Float'Range; | |
892 | ||
893 | ||
e94434ba | 894 | Here ``My_Float`` has the same range as |
895 | ``Float`` but is constrained, so operations on | |
896 | ``My_Float`` values will be checked for overflow | |
bf5dffd3 | 897 | against this range. |
898 | ||
899 | This style will achieve the desired goal, but | |
900 | it is often more convenient to be able to simply use | |
901 | the standard predefined floating-point types as long | |
902 | as overflow checking could be guaranteed. | |
e94434ba | 903 | The ``Check_Float_Overflow`` |
bf5dffd3 | 904 | configuration pragma achieves this effect. If a unit is compiled |
905 | subject to this configuration pragma, then all operations | |
906 | on predefined floating-point types including operations on | |
907 | base types of these floating-point types will be treated as | |
908 | though those types were constrained, and overflow checks | |
e94434ba | 909 | will be generated. The ``Constraint_Error`` |
bf5dffd3 | 910 | exception is raised if the result is out of range. |
911 | ||
912 | This mode can also be set by use of the compiler | |
913 | switch *-gnateF*. | |
914 | ||
915 | Pragma Check_Name | |
916 | ================= | |
917 | .. index:: Defining check names | |
918 | ||
919 | .. index:: Check names, defining | |
920 | ||
921 | ||
922 | Syntax: | |
923 | ||
924 | .. code-block:: ada | |
925 | ||
926 | pragma Check_Name (check_name_IDENTIFIER); | |
927 | ||
928 | ||
929 | This is a configuration pragma that defines a new implementation | |
930 | defined check name (unless IDENTIFIER matches one of the predefined | |
931 | check names, in which case the pragma has no effect). Check names | |
932 | are global to a partition, so if two or more configuration pragmas | |
933 | are present in a partition mentioning the same name, only one new | |
934 | check name is introduced. | |
935 | ||
936 | An implementation defined check name introduced with this pragma may | |
e94434ba | 937 | be used in only three contexts: ``pragma Suppress``, |
938 | ``pragma Unsuppress``, | |
939 | and as the prefix of a ``Check_Name'Enabled`` attribute reference. For | |
bf5dffd3 | 940 | any of these three cases, the check name must be visible. A check |
941 | name is visible if it is in the configuration pragmas applying to | |
942 | the current unit, or if it appears at the start of any unit that | |
943 | is part of the dependency set of the current unit (e.g., units that | |
e94434ba | 944 | are mentioned in ``with`` clauses). |
bf5dffd3 | 945 | |
946 | Check names introduced by this pragma are subject to control by compiler | |
947 | switches (in particular -gnatp) in the usual manner. | |
948 | ||
949 | Pragma Check_Policy | |
950 | =================== | |
951 | .. index:: Controlling assertions | |
952 | ||
953 | .. index:: Assertions, control | |
954 | ||
955 | .. index:: Check pragma control | |
956 | ||
957 | .. index:: Named assertions | |
958 | ||
959 | ||
960 | Syntax: | |
961 | ||
962 | :: | |
963 | ||
964 | pragma Check_Policy | |
965 | ([Name =>] CHECK_KIND, | |
966 | [Policy =>] POLICY_IDENTIFIER); | |
967 | ||
968 | pragma Check_Policy ( | |
969 | CHECK_KIND => POLICY_IDENTIFIER | |
970 | {, CHECK_KIND => POLICY_IDENTIFIER}); | |
971 | ||
972 | ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND | |
973 | ||
974 | CHECK_KIND ::= IDENTIFIER | | |
975 | Pre'Class | | |
976 | Post'Class | | |
977 | Type_Invariant'Class | | |
978 | Invariant'Class | |
979 | ||
980 | The identifiers Name and Policy are not allowed as CHECK_KIND values. This | |
981 | avoids confusion between the two possible syntax forms for this pragma. | |
982 | ||
983 | POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE | |
984 | ||
985 | ||
986 | This pragma is used to set the checking policy for assertions (specified | |
e94434ba | 987 | by aspects or pragmas), the ``Debug`` pragma, or additional checks |
988 | to be checked using the ``Check`` pragma. It may appear either as | |
bf5dffd3 | 989 | a configuration pragma, or within a declarative part of package. In the |
990 | latter case, it applies from the point where it appears to the end of | |
e94434ba | 991 | the declarative region (like pragma ``Suppress``). |
bf5dffd3 | 992 | |
e94434ba | 993 | The ``Check_Policy`` pragma is similar to the |
994 | predefined ``Assertion_Policy`` pragma, | |
bf5dffd3 | 995 | and if the check kind corresponds to one of the assertion kinds that |
e94434ba | 996 | are allowed by ``Assertion_Policy``, then the effect is identical. |
bf5dffd3 | 997 | |
998 | If the first argument is Debug, then the policy applies to Debug pragmas, | |
e94434ba | 999 | disabling their effect if the policy is ``OFF``, ``DISABLE``, or |
1000 | ``IGNORE``, and allowing them to execute with normal semantics if | |
1001 | the policy is ``ON`` or ``CHECK``. In addition if the policy is | |
1002 | ``DISABLE``, then the procedure call in ``Debug`` pragmas will | |
bf5dffd3 | 1003 | be totally ignored and not analyzed semantically. |
1004 | ||
1005 | Finally the first argument may be some other identifier than the above | |
1006 | possibilities, in which case it controls a set of named assertions | |
e94434ba | 1007 | that can be checked using pragma ``Check``. For example, if the pragma: |
bf5dffd3 | 1008 | |
1009 | ||
1010 | .. code-block:: ada | |
1011 | ||
1012 | pragma Check_Policy (Critical_Error, OFF); | |
1013 | ||
1014 | ||
e94434ba | 1015 | is given, then subsequent ``Check`` pragmas whose first argument is also |
1016 | ``Critical_Error`` will be disabled. | |
bf5dffd3 | 1017 | |
e94434ba | 1018 | The check policy is ``OFF`` to turn off corresponding checks, and ``ON`` |
bf5dffd3 | 1019 | to turn on corresponding checks. The default for a set of checks for which no |
e94434ba | 1020 | ``Check_Policy`` is given is ``OFF`` unless the compiler switch |
bf5dffd3 | 1021 | *-gnata* is given, which turns on all checks by default. |
1022 | ||
e94434ba | 1023 | The check policy settings ``CHECK`` and ``IGNORE`` are recognized |
1024 | as synonyms for ``ON`` and ``OFF``. These synonyms are provided for | |
1025 | compatibility with the standard ``Assertion_Policy`` pragma. The check | |
1026 | policy setting ``DISABLE`` causes the second argument of a corresponding | |
1027 | ``Check`` pragma to be completely ignored and not analyzed. | |
bf5dffd3 | 1028 | |
bf5dffd3 | 1029 | Pragma Comment |
1030 | ============== | |
1031 | ||
1032 | Syntax: | |
1033 | ||
1034 | ||
1035 | .. code-block:: ada | |
1036 | ||
1037 | pragma Comment (static_string_EXPRESSION); | |
1038 | ||
1039 | ||
e94434ba | 1040 | This is almost identical in effect to pragma ``Ident``. It allows the |
bf5dffd3 | 1041 | placement of a comment into the object file and hence into the |
1042 | executable file if the operating system permits such usage. The | |
e94434ba | 1043 | difference is that ``Comment``, unlike ``Ident``, has |
bf5dffd3 | 1044 | no limitations on placement of the pragma (it can be placed |
1045 | anywhere in the main source unit), and if more than one pragma | |
1046 | is used, all comments are retained. | |
1047 | ||
1048 | Pragma Common_Object | |
1049 | ==================== | |
1050 | ||
1051 | Syntax: | |
1052 | ||
1053 | ||
1054 | :: | |
1055 | ||
1056 | pragma Common_Object ( | |
1057 | [Internal =>] LOCAL_NAME | |
1058 | [, [External =>] EXTERNAL_SYMBOL] | |
1059 | [, [Size =>] EXTERNAL_SYMBOL] ); | |
1060 | ||
1061 | EXTERNAL_SYMBOL ::= | |
1062 | IDENTIFIER | |
1063 | | static_string_EXPRESSION | |
1064 | ||
1065 | ||
1066 | This pragma enables the shared use of variables stored in overlaid | |
e94434ba | 1067 | linker areas corresponding to the use of ``COMMON`` |
bf5dffd3 | 1068 | in Fortran. The single |
e94434ba | 1069 | object ``LOCAL_NAME`` is assigned to the area designated by |
1070 | the ``External`` argument. | |
bf5dffd3 | 1071 | You may define a record to correspond to a series |
e94434ba | 1072 | of fields. The ``Size`` argument |
bf5dffd3 | 1073 | is syntax checked in GNAT, but otherwise ignored. |
1074 | ||
e94434ba | 1075 | ``Common_Object`` is not supported on all platforms. If no |
bf5dffd3 | 1076 | support is available, then the code generator will issue a message |
1077 | indicating that the necessary attribute for implementation of this | |
1078 | pragma is not available. | |
1079 | ||
1080 | Pragma Compile_Time_Error | |
1081 | ========================= | |
1082 | ||
1083 | Syntax: | |
1084 | ||
1085 | ||
1086 | .. code-block:: ada | |
1087 | ||
1088 | pragma Compile_Time_Error | |
1089 | (boolean_EXPRESSION, static_string_EXPRESSION); | |
1090 | ||
1091 | ||
1092 | This pragma can be used to generate additional compile time | |
1093 | error messages. It | |
1094 | is particularly useful in generics, where errors can be issued for | |
1095 | specific problematic instantiations. The first parameter is a boolean | |
1096 | expression. The pragma is effective only if the value of this expression | |
1097 | is known at compile time, and has the value True. The set of expressions | |
1098 | whose values are known at compile time includes all static boolean | |
1099 | expressions, and also other values which the compiler can determine | |
1100 | at compile time (e.g., the size of a record type set by an explicit | |
1101 | size representation clause, or the value of a variable which was | |
1102 | initialized to a constant and is known not to have been modified). | |
1103 | If these conditions are met, an error message is generated using | |
1104 | the value given as the second argument. This string value may contain | |
1105 | embedded ASCII.LF characters to break the message into multiple lines. | |
1106 | ||
1107 | Pragma Compile_Time_Warning | |
1108 | =========================== | |
1109 | ||
1110 | Syntax: | |
1111 | ||
1112 | ||
1113 | .. code-block:: ada | |
1114 | ||
1115 | pragma Compile_Time_Warning | |
1116 | (boolean_EXPRESSION, static_string_EXPRESSION); | |
1117 | ||
1118 | ||
1119 | Same as pragma Compile_Time_Error, except a warning is issued instead | |
1120 | of an error message. Note that if this pragma is used in a package that | |
1121 | is with'ed by a client, the client will get the warning even though it | |
1122 | is issued by a with'ed package (normally warnings in with'ed units are | |
1123 | suppressed, but this is a special exception to that rule). | |
1124 | ||
1125 | One typical use is within a generic where compile time known characteristics | |
1126 | of formal parameters are tested, and warnings given appropriately. Another use | |
1127 | with a first parameter of True is to warn a client about use of a package, | |
1128 | for example that it is not fully implemented. | |
1129 | ||
1130 | Pragma Compiler_Unit | |
1131 | ==================== | |
1132 | ||
1133 | Syntax: | |
1134 | ||
1135 | ||
1136 | .. code-block:: ada | |
1137 | ||
1138 | pragma Compiler_Unit; | |
1139 | ||
1140 | ||
1141 | This pragma is obsolete. It is equivalent to Compiler_Unit_Warning. It is | |
1142 | retained so that old versions of the GNAT run-time that use this pragma can | |
1143 | be compiled with newer versions of the compiler. | |
1144 | ||
1145 | Pragma Compiler_Unit_Warning | |
1146 | ============================ | |
1147 | ||
1148 | Syntax: | |
1149 | ||
1150 | ||
1151 | .. code-block:: ada | |
1152 | ||
1153 | pragma Compiler_Unit_Warning; | |
1154 | ||
1155 | ||
1156 | This pragma is intended only for internal use in the GNAT run-time library. | |
1157 | It indicates that the unit is used as part of the compiler build. The effect | |
1158 | is to generate warnings for the use of constructs (for example, conditional | |
1159 | expressions) that would cause trouble when bootstrapping using an older | |
1160 | version of GNAT. For the exact list of restrictions, see the compiler sources | |
1161 | and references to Check_Compiler_Unit. | |
1162 | ||
1163 | Pragma Complete_Representation | |
1164 | ============================== | |
1165 | ||
1166 | Syntax: | |
1167 | ||
1168 | ||
1169 | .. code-block:: ada | |
1170 | ||
1171 | pragma Complete_Representation; | |
1172 | ||
1173 | ||
1174 | This pragma must appear immediately within a record representation | |
1175 | clause. Typical placements are before the first component clause | |
1176 | or after the last component clause. The effect is to give an error | |
1177 | message if any component is missing a component clause. This pragma | |
1178 | may be used to ensure that a record representation clause is | |
1179 | complete, and that this invariant is maintained if fields are | |
1180 | added to the record in the future. | |
1181 | ||
1182 | Pragma Complex_Representation | |
1183 | ============================= | |
1184 | ||
1185 | Syntax: | |
1186 | ||
1187 | ||
1188 | :: | |
1189 | ||
1190 | pragma Complex_Representation | |
1191 | ([Entity =>] LOCAL_NAME); | |
1192 | ||
1193 | ||
e94434ba | 1194 | The ``Entity`` argument must be the name of a record type which has |
bf5dffd3 | 1195 | two fields of the same floating-point type. The effect of this pragma is |
1196 | to force gcc to use the special internal complex representation form for | |
1197 | this record, which may be more efficient. Note that this may result in | |
1198 | the code for this type not conforming to standard ABI (application | |
1199 | binary interface) requirements for the handling of record types. For | |
1200 | example, in some environments, there is a requirement for passing | |
1201 | records by pointer, and the use of this pragma may result in passing | |
1202 | this type in floating-point registers. | |
1203 | ||
1204 | Pragma Component_Alignment | |
1205 | ========================== | |
1206 | .. index:: Alignments of components | |
1207 | .. index:: Pragma Component_Alignment | |
1208 | ||
1209 | ||
1210 | Syntax: | |
1211 | ||
1212 | :: | |
1213 | ||
1214 | pragma Component_Alignment ( | |
1215 | [Form =>] ALIGNMENT_CHOICE | |
1216 | [, [Name =>] type_LOCAL_NAME]); | |
1217 | ||
1218 | ALIGNMENT_CHOICE ::= | |
1219 | Component_Size | |
1220 | | Component_Size_4 | |
1221 | | Storage_Unit | |
1222 | | Default | |
1223 | ||
1224 | ||
1225 | Specifies the alignment of components in array or record types. | |
e94434ba | 1226 | The meaning of the ``Form`` argument is as follows: |
bf5dffd3 | 1227 | |
1228 | ||
1229 | .. index:: Component_Size (in pragma Component_Alignment) | |
1230 | ||
1231 | *Component_Size* | |
1232 | Aligns scalar components and subcomponents of the array or record type | |
1233 | on boundaries appropriate to their inherent size (naturally | |
1234 | aligned). For example, 1-byte components are aligned on byte boundaries, | |
1235 | 2-byte integer components are aligned on 2-byte boundaries, 4-byte | |
1236 | integer components are aligned on 4-byte boundaries and so on. These | |
1237 | alignment rules correspond to the normal rules for C compilers on all | |
1238 | machines except the VAX. | |
1239 | ||
1240 | .. index:: Component_Size_4 (in pragma Component_Alignment) | |
1241 | ||
1242 | *Component_Size_4* | |
1243 | Naturally aligns components with a size of four or fewer | |
1244 | bytes. Components that are larger than 4 bytes are placed on the next | |
1245 | 4-byte boundary. | |
1246 | ||
1247 | .. index:: Storage_Unit (in pragma Component_Alignment) | |
1248 | ||
1249 | *Storage_Unit* | |
1250 | Specifies that array or record components are byte aligned, i.e., | |
1251 | aligned on boundaries determined by the value of the constant | |
e94434ba | 1252 | ``System.Storage_Unit``. |
bf5dffd3 | 1253 | |
1254 | .. index:: Default (in pragma Component_Alignment) | |
1255 | ||
1256 | *Default* | |
1257 | Specifies that array or record components are aligned on default | |
1258 | boundaries, appropriate to the underlying hardware or operating system or | |
e94434ba | 1259 | both. The ``Default`` choice is the same as ``Component_Size`` (natural |
bf5dffd3 | 1260 | alignment). |
1261 | ||
e94434ba | 1262 | If the ``Name`` parameter is present, ``type_LOCAL_NAME`` must |
bf5dffd3 | 1263 | refer to a local record or array type, and the specified alignment |
1264 | choice applies to the specified type. The use of | |
e94434ba | 1265 | ``Component_Alignment`` together with a pragma ``Pack`` causes the |
1266 | ``Component_Alignment`` pragma to be ignored. The use of | |
1267 | ``Component_Alignment`` together with a record representation clause | |
bf5dffd3 | 1268 | is only effective for fields not specified by the representation clause. |
1269 | ||
e94434ba | 1270 | If the ``Name`` parameter is absent, the pragma can be used as either |
bf5dffd3 | 1271 | a configuration pragma, in which case it applies to one or more units in |
1272 | accordance with the normal rules for configuration pragmas, or it can be | |
1273 | used within a declarative part, in which case it applies to types that | |
1274 | are declared within this declarative part, or within any nested scope | |
1275 | within this declarative part. In either case it specifies the alignment | |
1276 | to be applied to any record or array type which has otherwise standard | |
1277 | representation. | |
1278 | ||
1279 | If the alignment for a record or array type is not specified (using | |
e94434ba | 1280 | pragma ``Pack``, pragma ``Component_Alignment``, or a record rep |
bf5dffd3 | 1281 | clause), the GNAT uses the default alignment as described previously. |
1282 | ||
39adf1e6 | 1283 | .. _Pragma-Constant_After_Elaboration: |
1284 | ||
4a7c3b2f | 1285 | Pragma Constant_After_Elaboration |
1286 | ================================= | |
1287 | ||
d5dcec30 | 1288 | Syntax: |
1289 | ||
1290 | .. code-block:: ada | |
1291 | ||
1292 | pragma Constant_After_Elaboration [ (boolean_EXPRESSION) ]; | |
1293 | ||
1294 | For the semantics of this pragma, see the entry for aspect | |
e94434ba | 1295 | ``Constant_After_Elaboration`` in the SPARK 2014 Reference Manual, section 3.3.1. |
4a7c3b2f | 1296 | |
39adf1e6 | 1297 | .. _Pragma-Contract_Cases: |
1298 | ||
bf5dffd3 | 1299 | Pragma Contract_Cases |
1300 | ===================== | |
1301 | .. index:: Contract cases | |
1302 | ||
bf5dffd3 | 1303 | Syntax: |
1304 | ||
d5dcec30 | 1305 | .. code-block:: ada |
bf5dffd3 | 1306 | |
d5dcec30 | 1307 | pragma Contract_Cases ((CONTRACT_CASE {, CONTRACT_CASE)); |
bf5dffd3 | 1308 | |
d5dcec30 | 1309 | CONTRACT_CASE ::= CASE_GUARD => CONSEQUENCE |
1310 | ||
1311 | CASE_GUARD ::= boolean_EXPRESSION | others | |
bf5dffd3 | 1312 | |
d5dcec30 | 1313 | CONSEQUENCE ::= boolean_EXPRESSION |
bf5dffd3 | 1314 | |
e94434ba | 1315 | The ``Contract_Cases`` pragma allows defining fine-grain specifications |
bf5dffd3 | 1316 | that can complement or replace the contract given by a precondition and a |
e94434ba | 1317 | postcondition. Additionally, the ``Contract_Cases`` pragma can be used |
bf5dffd3 | 1318 | by testing and formal verification tools. The compiler checks its validity and, |
1319 | depending on the assertion policy at the point of declaration of the pragma, | |
1320 | it may insert a check in the executable. For code generation, the contract | |
1321 | cases | |
1322 | ||
1323 | ||
1324 | .. code-block:: ada | |
1325 | ||
1326 | pragma Contract_Cases ( | |
1327 | Cond1 => Pred1, | |
1328 | Cond2 => Pred2); | |
1329 | ||
1330 | ||
1331 | are equivalent to | |
1332 | ||
1333 | ||
1334 | .. code-block:: ada | |
1335 | ||
1336 | C1 : constant Boolean := Cond1; -- evaluated at subprogram entry | |
1337 | C2 : constant Boolean := Cond2; -- evaluated at subprogram entry | |
1338 | pragma Precondition ((C1 and not C2) or (C2 and not C1)); | |
1339 | pragma Postcondition (if C1 then Pred1); | |
1340 | pragma Postcondition (if C2 then Pred2); | |
1341 | ||
1342 | ||
5e138851 | 1343 | The precondition ensures that one and only one of the case guards is |
bf5dffd3 | 1344 | satisfied on entry to the subprogram. |
5e138851 | 1345 | The postcondition ensures that for the case guard that was True on entry, |
bf5dffd3 | 1346 | the corrresponding consequence is True on exit. Other consequence expressions |
1347 | are not evaluated. | |
1348 | ||
e94434ba | 1349 | A precondition ``P`` and postcondition ``Q`` can also be |
bf5dffd3 | 1350 | expressed as contract cases: |
1351 | ||
1352 | .. code-block:: ada | |
1353 | ||
1354 | pragma Contract_Cases (P => Q); | |
1355 | ||
1356 | ||
e94434ba | 1357 | The placement and visibility rules for ``Contract_Cases`` pragmas are |
bf5dffd3 | 1358 | identical to those described for preconditions and postconditions. |
1359 | ||
5e138851 | 1360 | The compiler checks that boolean expressions given in case guards and |
1361 | consequences are valid, where the rules for case guards are the same as | |
e94434ba | 1362 | the rule for an expression in ``Precondition`` and the rules for |
bf5dffd3 | 1363 | consequences are the same as the rule for an expression in |
e94434ba | 1364 | ``Postcondition``. In particular, attributes ``'Old`` and |
1365 | ``'Result`` can only be used within consequence expressions. | |
5e138851 | 1366 | The case guard for the last contract case may be ``others``, to denote |
bf5dffd3 | 1367 | any case not captured by the previous cases. The |
1368 | following is an example of use within a package spec: | |
1369 | ||
1370 | ||
1371 | .. code-block:: ada | |
1372 | ||
1373 | package Math_Functions is | |
1374 | ... | |
1375 | function Sqrt (Arg : Float) return Float; | |
8f09eafa | 1376 | pragma Contract_Cases (((Arg in 0.0 .. 99.0) => Sqrt'Result < 10.0, |
1377 | Arg >= 100.0 => Sqrt'Result >= 10.0, | |
1378 | others => Sqrt'Result = 0.0)); | |
bf5dffd3 | 1379 | ... |
1380 | end Math_Functions; | |
1381 | ||
1382 | ||
1383 | The meaning of contract cases is that only one case should apply at each | |
5e138851 | 1384 | call, as determined by the corresponding case guard evaluating to True, |
bf5dffd3 | 1385 | and that the consequence for this case should hold when the subprogram |
1386 | returns. | |
1387 | ||
1388 | Pragma Convention_Identifier | |
1389 | ============================ | |
1390 | .. index:: Conventions, synonyms | |
1391 | ||
1392 | Syntax: | |
1393 | ||
1394 | ||
1395 | :: | |
1396 | ||
1397 | pragma Convention_Identifier ( | |
1398 | [Name =>] IDENTIFIER, | |
1399 | [Convention =>] convention_IDENTIFIER); | |
1400 | ||
1401 | ||
1402 | This pragma provides a mechanism for supplying synonyms for existing | |
e94434ba | 1403 | convention identifiers. The ``Name`` identifier can subsequently |
bf5dffd3 | 1404 | be used as a synonym for the given convention in other pragmas (including |
e94434ba | 1405 | for example pragma ``Import`` or another ``Convention_Identifier`` |
bf5dffd3 | 1406 | pragma). As an example of the use of this, suppose you had legacy code |
1407 | which used Fortran77 as the identifier for Fortran. Then the pragma: | |
1408 | ||
1409 | ||
1410 | .. code-block:: ada | |
1411 | ||
1412 | pragma Convention_Identifier (Fortran77, Fortran); | |
1413 | ||
1414 | ||
e94434ba | 1415 | would allow the use of the convention identifier ``Fortran77`` in |
bf5dffd3 | 1416 | subsequent code, avoiding the need to modify the sources. As another |
1417 | example, you could use this to parameterize convention requirements | |
e94434ba | 1418 | according to systems. Suppose you needed to use ``Stdcall`` on |
1419 | windows systems, and ``C`` on some other system, then you could | |
1420 | define a convention identifier ``Library`` and use a single | |
1421 | ``Convention_Identifier`` pragma to specify which convention | |
bf5dffd3 | 1422 | would be used system-wide. |
1423 | ||
1424 | Pragma CPP_Class | |
1425 | ================ | |
1426 | .. index:: Interfacing with C++ | |
1427 | ||
1428 | Syntax: | |
1429 | ||
1430 | ||
1431 | :: | |
1432 | ||
1433 | pragma CPP_Class ([Entity =>] LOCAL_NAME); | |
1434 | ||
1435 | ||
1436 | The argument denotes an entity in the current declarative region that is | |
1437 | declared as a record type. It indicates that the type corresponds to an | |
1438 | externally declared C++ class type, and is to be laid out the same way | |
1439 | that C++ would lay out the type. If the C++ class has virtual primitives | |
1440 | then the record must be declared as a tagged record type. | |
1441 | ||
e94434ba | 1442 | Types for which ``CPP_Class`` is specified do not have assignment or |
bf5dffd3 | 1443 | equality operators defined (such operations can be imported or declared |
1444 | as subprograms as required). Initialization is allowed only by constructor | |
e94434ba | 1445 | functions (see pragma ``CPP_Constructor``). Such types are implicitly |
bf5dffd3 | 1446 | limited if not explicitly declared as limited or derived from a limited |
1447 | type, and an error is issued in that case. | |
1448 | ||
1449 | See :ref:`Interfacing_to_C++` for related information. | |
1450 | ||
e94434ba | 1451 | Note: Pragma ``CPP_Class`` is currently obsolete. It is supported |
bf5dffd3 | 1452 | for backward compatibility but its functionality is available |
e94434ba | 1453 | using pragma ``Import`` with ``Convention`` = ``CPP``. |
bf5dffd3 | 1454 | |
1455 | Pragma CPP_Constructor | |
1456 | ====================== | |
1457 | .. index:: Interfacing with C++ | |
1458 | ||
1459 | ||
1460 | Syntax: | |
1461 | ||
1462 | ||
1463 | :: | |
1464 | ||
1465 | pragma CPP_Constructor ([Entity =>] LOCAL_NAME | |
1466 | [, [External_Name =>] static_string_EXPRESSION ] | |
1467 | [, [Link_Name =>] static_string_EXPRESSION ]); | |
1468 | ||
1469 | ||
1470 | This pragma identifies an imported function (imported in the usual way | |
e94434ba | 1471 | with pragma ``Import``) as corresponding to a C++ constructor. If |
1472 | ``External_Name`` and ``Link_Name`` are not specified then the | |
1473 | ``Entity`` argument is a name that must have been previously mentioned | |
1474 | in a pragma ``Import`` with ``Convention`` = ``CPP``. Such name | |
bf5dffd3 | 1475 | must be of one of the following forms: |
1476 | ||
1477 | * | |
e94434ba | 1478 | **function** ``Fname`` **return** T` |
bf5dffd3 | 1479 | |
1480 | * | |
e94434ba | 1481 | **function** ``Fname`` **return** T'Class |
bf5dffd3 | 1482 | |
1483 | * | |
e94434ba | 1484 | **function** ``Fname`` (...) **return** T` |
bf5dffd3 | 1485 | |
1486 | * | |
e94434ba | 1487 | **function** ``Fname`` (...) **return** T'Class |
bf5dffd3 | 1488 | |
e94434ba | 1489 | where ``T`` is a limited record type imported from C++ with pragma |
1490 | ``Import`` and ``Convention`` = ``CPP``. | |
bf5dffd3 | 1491 | |
1492 | The first two forms import the default constructor, used when an object | |
e94434ba | 1493 | of type ``T`` is created on the Ada side with no explicit constructor. |
bf5dffd3 | 1494 | The latter two forms cover all the non-default constructors of the type. |
1495 | See the GNAT User's Guide for details. | |
1496 | ||
1497 | If no constructors are imported, it is impossible to create any objects | |
1498 | on the Ada side and the type is implicitly declared abstract. | |
1499 | ||
e94434ba | 1500 | Pragma ``CPP_Constructor`` is intended primarily for automatic generation |
1501 | using an automatic binding generator tool (such as the :switch:`-fdump-ada-spec` | |
bf5dffd3 | 1502 | GCC switch). |
1503 | See :ref:`Interfacing_to_C++` for more related information. | |
1504 | ||
1505 | Note: The use of functions returning class-wide types for constructors is | |
1506 | currently obsolete. They are supported for backward compatibility. The | |
1507 | use of functions returning the type T leave the Ada sources more clear | |
1508 | because the imported C++ constructors always return an object of type T; | |
1509 | that is, they never return an object whose type is a descendant of type T. | |
1510 | ||
1511 | Pragma CPP_Virtual | |
1512 | ================== | |
1513 | .. index:: Interfacing to C++ | |
1514 | ||
1515 | ||
1516 | This pragma is now obsolete and, other than generating a warning if warnings | |
1517 | on obsolescent features are enabled, is completely ignored. | |
1518 | It is retained for compatibility | |
1519 | purposes. It used to be required to ensure compoatibility with C++, but | |
1520 | is no longer required for that purpose because GNAT generates | |
1521 | the same object layout as the G++ compiler by default. | |
1522 | ||
1523 | See :ref:`Interfacing_to_C++` for related information. | |
1524 | ||
1525 | Pragma CPP_Vtable | |
1526 | ================= | |
1527 | .. index:: Interfacing with C++ | |
1528 | ||
1529 | ||
1530 | This pragma is now obsolete and, other than generating a warning if warnings | |
1531 | on obsolescent features are enabled, is completely ignored. | |
1532 | It used to be required to ensure compatibility with C++, but | |
1533 | is no longer required for that purpose because GNAT generates | |
1534 | the same object layout as the G++ compiler by default. | |
1535 | ||
1536 | See :ref:`Interfacing_to_C++` for related information. | |
1537 | ||
1538 | Pragma CPU | |
1539 | ========== | |
1540 | ||
1541 | Syntax: | |
1542 | ||
1543 | ||
1544 | .. code-block:: ada | |
1545 | ||
1546 | pragma CPU (EXPRESSION); | |
1547 | ||
1548 | ||
1549 | This pragma is standard in Ada 2012, but is available in all earlier | |
1550 | versions of Ada as an implementation-defined pragma. | |
1551 | See Ada 2012 Reference Manual for details. | |
1552 | ||
8f09eafa | 1553 | Pragma Deadline_Floor |
1554 | ===================== | |
1555 | ||
1556 | Syntax: | |
1557 | ||
1558 | ||
1559 | .. code-block:: ada | |
1560 | ||
1561 | pragma Deadline_Floor (time_span_EXPRESSION); | |
1562 | ||
1563 | ||
1564 | This pragma applies only to protected types and specifies the floor | |
1565 | deadline inherited by a task when the task enters a protected object. | |
1566 | It is effective only when the EDF scheduling policy is used. | |
1567 | ||
39adf1e6 | 1568 | .. _Pragma-Default_Initial_Condition: |
1569 | ||
4a7c3b2f | 1570 | Pragma Default_Initial_Condition |
1571 | ================================ | |
1572 | ||
d5dcec30 | 1573 | Syntax: |
1574 | ||
1575 | .. code-block:: ada | |
1576 | ||
1577 | pragma Default_Initial_Condition [ (null | boolean_EXPRESSION) ]; | |
1578 | ||
1579 | For the semantics of this pragma, see the entry for aspect | |
e94434ba | 1580 | ``Default_Initial_Condition`` in the SPARK 2014 Reference Manual, section 7.3.3. |
4a7c3b2f | 1581 | |
bf5dffd3 | 1582 | Pragma Debug |
1583 | ============ | |
1584 | ||
1585 | Syntax: | |
1586 | ||
1587 | ||
1588 | :: | |
1589 | ||
1590 | pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON); | |
1591 | ||
1592 | PROCEDURE_CALL_WITHOUT_SEMICOLON ::= | |
1593 | PROCEDURE_NAME | |
1594 | | PROCEDURE_PREFIX ACTUAL_PARAMETER_PART | |
1595 | ||
1596 | ||
1597 | The procedure call argument has the syntactic form of an expression, meeting | |
1598 | the syntactic requirements for pragmas. | |
1599 | ||
1600 | If debug pragmas are not enabled or if the condition is present and evaluates | |
1601 | to False, this pragma has no effect. If debug pragmas are enabled, the | |
1602 | semantics of the pragma is exactly equivalent to the procedure call statement | |
1603 | corresponding to the argument with a terminating semicolon. Pragmas are | |
e94434ba | 1604 | permitted in sequences of declarations, so you can use pragma ``Debug`` to |
bf5dffd3 | 1605 | intersperse calls to debug procedures in the middle of declarations. Debug |
1606 | pragmas can be enabled either by use of the command line switch *-gnata* | |
e94434ba | 1607 | or by use of the pragma ``Check_Policy`` with a first argument of |
1608 | ``Debug``. | |
bf5dffd3 | 1609 | |
1610 | Pragma Debug_Policy | |
1611 | =================== | |
1612 | ||
1613 | Syntax: | |
1614 | ||
1615 | ||
1616 | .. code-block:: ada | |
1617 | ||
1618 | pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF); | |
1619 | ||
1620 | ||
e94434ba | 1621 | This pragma is equivalent to a corresponding ``Check_Policy`` pragma |
1622 | with a first argument of ``Debug``. It is retained for historical | |
bf5dffd3 | 1623 | compatibility reasons. |
1624 | ||
1625 | Pragma Default_Scalar_Storage_Order | |
1626 | =================================== | |
1627 | .. index:: Default_Scalar_Storage_Order | |
1628 | ||
1629 | .. index:: Scalar_Storage_Order | |
1630 | ||
1631 | ||
1632 | Syntax: | |
1633 | ||
1634 | ||
1635 | .. code-block:: ada | |
1636 | ||
1637 | pragma Default_Scalar_Storage_Order (High_Order_First | Low_Order_First); | |
1638 | ||
1639 | ||
e94434ba | 1640 | Normally if no explicit ``Scalar_Storage_Order`` is given for a record |
bf5dffd3 | 1641 | type or array type, then the scalar storage order defaults to the ordinary |
1642 | default for the target. But this default may be overridden using this pragma. | |
1643 | The pragma may appear as a configuration pragma, or locally within a package | |
1644 | spec or declarative part. In the latter case, it applies to all subsequent | |
1645 | types declared within that package spec or declarative part. | |
1646 | ||
1647 | The following example shows the use of this pragma: | |
1648 | ||
1649 | ||
1650 | .. code-block:: ada | |
1651 | ||
1652 | pragma Default_Scalar_Storage_Order (High_Order_First); | |
1653 | with System; use System; | |
1654 | package DSSO1 is | |
1655 | type H1 is record | |
1656 | a : Integer; | |
1657 | end record; | |
1658 | ||
1659 | type L2 is record | |
1660 | a : Integer; | |
1661 | end record; | |
1662 | for L2'Scalar_Storage_Order use Low_Order_First; | |
1663 | ||
1664 | type L2a is new L2; | |
1665 | ||
1666 | package Inner is | |
1667 | type H3 is record | |
1668 | a : Integer; | |
1669 | end record; | |
1670 | ||
1671 | pragma Default_Scalar_Storage_Order (Low_Order_First); | |
1672 | ||
1673 | type L4 is record | |
1674 | a : Integer; | |
1675 | end record; | |
1676 | end Inner; | |
1677 | ||
1678 | type H4a is new Inner.L4; | |
1679 | ||
1680 | type H5 is record | |
1681 | a : Integer; | |
1682 | end record; | |
1683 | end DSSO1; | |
1684 | ||
1685 | ||
e94434ba | 1686 | In this example record types with names starting with *L* have `Low_Order_First` scalar |
1687 | storage order, and record types with names starting with *H* have ``High_Order_First``. | |
1688 | Note that in the case of ``H4a``, the order is not inherited | |
1689 | from the parent type. Only an explicitly set ``Scalar_Storage_Order`` | |
bf5dffd3 | 1690 | gets inherited on type derivation. |
1691 | ||
1692 | If this pragma is used as a configuration pragma which appears within a | |
1693 | configuration pragma file (as opposed to appearing explicitly at the start | |
1694 | of a single unit), then the binder will require that all units in a partition | |
1695 | be compiled in a similar manner, other than run-time units, which are not | |
1696 | affected by this pragma. Note that the use of this form is discouraged because | |
1697 | it may significantly degrade the run-time performance of the software, instead | |
1698 | the default scalar storage order ought to be changed only on a local basis. | |
1699 | ||
1700 | Pragma Default_Storage_Pool | |
1701 | =========================== | |
1702 | .. index:: Default_Storage_Pool | |
1703 | ||
1704 | ||
1705 | Syntax: | |
1706 | ||
1707 | ||
1708 | .. code-block:: ada | |
1709 | ||
1710 | pragma Default_Storage_Pool (storage_pool_NAME | null); | |
1711 | ||
1712 | ||
1713 | This pragma is standard in Ada 2012, but is available in all earlier | |
1714 | versions of Ada as an implementation-defined pragma. | |
1715 | See Ada 2012 Reference Manual for details. | |
1716 | ||
39adf1e6 | 1717 | .. _Pragma-Depends: |
1718 | ||
bf5dffd3 | 1719 | Pragma Depends |
1720 | ============== | |
1721 | ||
d5dcec30 | 1722 | Syntax: |
1723 | ||
1724 | .. code-block:: ada | |
1725 | ||
1726 | pragma Depends (DEPENDENCY_RELATION); | |
1727 | ||
1728 | DEPENDENCY_RELATION ::= | |
1729 | null | |
1730 | | (DEPENDENCY_CLAUSE {, DEPENDENCY_CLAUSE}) | |
1731 | ||
1732 | DEPENDENCY_CLAUSE ::= | |
1733 | OUTPUT_LIST =>[+] INPUT_LIST | |
1734 | | NULL_DEPENDENCY_CLAUSE | |
1735 | ||
1736 | NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST | |
1737 | ||
1738 | OUTPUT_LIST ::= OUTPUT | (OUTPUT {, OUTPUT}) | |
1739 | ||
1740 | INPUT_LIST ::= null | INPUT | (INPUT {, INPUT}) | |
1741 | ||
1742 | OUTPUT ::= NAME | FUNCTION_RESULT | |
1743 | INPUT ::= NAME | |
1744 | ||
1745 | where FUNCTION_RESULT is a function Result attribute_reference | |
1746 | ||
e94434ba | 1747 | For the semantics of this pragma, see the entry for aspect ``Depends`` in the |
d5dcec30 | 1748 | SPARK 2014 Reference Manual, section 6.1.5. |
bf5dffd3 | 1749 | |
1750 | Pragma Detect_Blocking | |
1751 | ====================== | |
1752 | ||
1753 | Syntax: | |
1754 | ||
1755 | .. code-block:: ada | |
1756 | ||
1757 | pragma Detect_Blocking; | |
1758 | ||
1759 | ||
1760 | This is a standard pragma in Ada 2005, that is available in all earlier | |
1761 | versions of Ada as an implementation-defined pragma. | |
1762 | ||
1763 | This is a configuration pragma that forces the detection of potentially | |
1764 | blocking operations within a protected operation, and to raise Program_Error | |
1765 | if that happens. | |
1766 | ||
1767 | Pragma Disable_Atomic_Synchronization | |
1768 | ===================================== | |
1769 | ||
1770 | .. index:: Atomic Synchronization | |
1771 | ||
1772 | Syntax: | |
1773 | ||
1774 | :: | |
1775 | ||
1776 | pragma Disable_Atomic_Synchronization [(Entity)]; | |
1777 | ||
1778 | ||
1779 | Ada requires that accesses (reads or writes) of an atomic variable be | |
1780 | regarded as synchronization points in the case of multiple tasks. | |
1781 | Particularly in the case of multi-processors this may require special | |
1782 | handling, e.g. the generation of memory barriers. This capability may | |
1783 | be turned off using this pragma in cases where it is known not to be | |
1784 | required. | |
1785 | ||
1786 | The placement and scope rules for this pragma are the same as those | |
e94434ba | 1787 | for ``pragma Suppress``. In particular it can be used as a |
bf5dffd3 | 1788 | configuration pragma, or in a declaration sequence where it applies |
e94434ba | 1789 | till the end of the scope. If an ``Entity`` argument is present, |
bf5dffd3 | 1790 | the action applies only to that entity. |
1791 | ||
1792 | Pragma Dispatching_Domain | |
1793 | ========================= | |
1794 | ||
1795 | Syntax: | |
1796 | ||
1797 | ||
1798 | .. code-block:: ada | |
1799 | ||
1800 | pragma Dispatching_Domain (EXPRESSION); | |
1801 | ||
1802 | ||
1803 | This pragma is standard in Ada 2012, but is available in all earlier | |
1804 | versions of Ada as an implementation-defined pragma. | |
1805 | See Ada 2012 Reference Manual for details. | |
1806 | ||
39adf1e6 | 1807 | .. _Pragma-Effective_Reads: |
1808 | ||
bf5dffd3 | 1809 | Pragma Effective_Reads |
1810 | ====================== | |
1811 | ||
d5dcec30 | 1812 | Syntax: |
1813 | ||
1814 | .. code-block:: ada | |
1815 | ||
8f09eafa | 1816 | pragma Effective_Reads [ (boolean_EXPRESSION) ]; |
d5dcec30 | 1817 | |
e94434ba | 1818 | For the semantics of this pragma, see the entry for aspect ``Effective_Reads`` in |
d5dcec30 | 1819 | the SPARK 2014 Reference Manual, section 7.1.2. |
bf5dffd3 | 1820 | |
39adf1e6 | 1821 | .. _Pragma-Effective_Writes: |
1822 | ||
bf5dffd3 | 1823 | Pragma Effective_Writes |
1824 | ======================= | |
1825 | ||
d5dcec30 | 1826 | Syntax: |
1827 | ||
1828 | .. code-block:: ada | |
1829 | ||
1830 | pragma Effective_Writes [ (boolean_EXPRESSION) ]; | |
1831 | ||
e94434ba | 1832 | For the semantics of this pragma, see the entry for aspect ``Effective_Writes`` |
d5dcec30 | 1833 | in the SPARK 2014 Reference Manual, section 7.1.2. |
bf5dffd3 | 1834 | |
1835 | Pragma Elaboration_Checks | |
1836 | ========================= | |
1837 | .. index:: Elaboration control | |
1838 | ||
1839 | ||
1840 | Syntax: | |
1841 | ||
1842 | ||
1843 | .. code-block:: ada | |
1844 | ||
1845 | pragma Elaboration_Checks (Dynamic | Static); | |
1846 | ||
1847 | ||
aed346af | 1848 | This is a configuration pragma which specifies the elaboration model to be |
1849 | used during compilation. For more information on the elaboration models of | |
1850 | GNAT, consult the chapter on elaboration order handling in the *GNAT User's | |
1851 | Guide*. | |
bf5dffd3 | 1852 | |
aed346af | 1853 | The pragma may appear in the following contexts: |
1854 | ||
1855 | * Configuration pragmas file | |
1856 | ||
1857 | * Prior to the context clauses of a compilation unit's initial declaration | |
1858 | ||
1859 | Any other placement of the pragma will result in a warning and the effects of | |
1860 | the offending pragma will be ignored. | |
1861 | ||
1862 | If the pragma argument is ``Dynamic``, then the dynamic elaboration model is in | |
1863 | effect. If the pragma argument is ``Static``, then the static elaboration model | |
1864 | is in effect. | |
e94434ba | 1865 | |
bf5dffd3 | 1866 | Pragma Eliminate |
1867 | ================ | |
1868 | .. index:: Elimination of unused subprograms | |
1869 | ||
1870 | ||
1871 | Syntax: | |
1872 | ||
1873 | ||
1874 | :: | |
1875 | ||
e94434ba | 1876 | pragma Eliminate ( |
1877 | [ Unit_Name => ] IDENTIFIER | SELECTED_COMPONENT , | |
1878 | [ Entity => ] IDENTIFIER | | |
1879 | SELECTED_COMPONENT | | |
1880 | STRING_LITERAL | |
1881 | [, Source_Location => SOURCE_TRACE ] ); | |
bf5dffd3 | 1882 | |
e94434ba | 1883 | SOURCE_TRACE ::= STRING_LITERAL |
bf5dffd3 | 1884 | |
bf5dffd3 | 1885 | |
e94434ba | 1886 | This pragma indicates that the given entity is not used in the program to be |
1887 | compiled and built, thus allowing the compiler to | |
1888 | eliminate the code or data associated with the named entity. Any reference to | |
1889 | an eliminated entity causes a compile-time or link-time error. | |
bf5dffd3 | 1890 | |
e94434ba | 1891 | The pragma has the following semantics, where ``U`` is the unit specified by |
1892 | the ``Unit_Name`` argument and ``E`` is the entity specified by the ``Entity`` | |
1893 | argument: | |
bf5dffd3 | 1894 | |
e94434ba | 1895 | * ``E`` must be a subprogram that is explicitly declared either: |
bf5dffd3 | 1896 | |
e94434ba | 1897 | o Within ``U``, or |
bf5dffd3 | 1898 | |
e94434ba | 1899 | o Within a generic package that is instantiated in ``U``, or |
bf5dffd3 | 1900 | |
e94434ba | 1901 | o As an instance of generic subprogram instantiated in ``U``. |
bf5dffd3 | 1902 | |
e94434ba | 1903 | Otherwise the pragma is ignored. |
bf5dffd3 | 1904 | |
e94434ba | 1905 | * If ``E`` is overloaded within ``U`` then, in the absence of a |
1906 | ``Source_Location`` argument, all overloadings are eliminated. | |
bf5dffd3 | 1907 | |
e94434ba | 1908 | * If ``E`` is overloaded within ``U`` and only some overloadings |
1909 | are to be eliminated, then each overloading to be eliminated | |
1910 | must be specified in a corresponding pragma ``Eliminate`` | |
1911 | with a ``Source_Location`` argument identifying the line where the | |
1912 | declaration appears, as described below. | |
1913 | ||
1914 | * If ``E`` is declared as the result of a generic instantiation, then | |
1915 | a ``Source_Location`` argument is needed, as described below | |
bf5dffd3 | 1916 | |
e94434ba | 1917 | Pragma ``Eliminate`` allows a program to be compiled in a system-independent |
1918 | manner, so that unused entities are eliminated but without | |
bf5dffd3 | 1919 | needing to modify the source text. Normally the required set of |
e94434ba | 1920 | ``Eliminate`` pragmas is constructed automatically using the ``gnatelim`` tool. |
bf5dffd3 | 1921 | |
1922 | Any source file change that removes, splits, or | |
e94434ba | 1923 | adds lines may make the set of ``Eliminate`` pragmas invalid because their |
1924 | ``Source_Location`` argument values may get out of date. | |
bf5dffd3 | 1925 | |
e94434ba | 1926 | Pragma ``Eliminate`` may be used where the referenced entity is a dispatching |
bf5dffd3 | 1927 | operation. In this case all the subprograms to which the given operation can |
1928 | dispatch are considered to be unused (are never called as a result of a direct | |
1929 | or a dispatching call). | |
1930 | ||
e94434ba | 1931 | The string literal given for the source location specifies the line number |
1932 | of the declaration of the entity, using the following syntax for ``SOURCE_TRACE``: | |
1933 | ||
1934 | :: | |
1935 | ||
1936 | SOURCE_TRACE ::= SOURCE_REFERENCE [ LBRACKET SOURCE_TRACE RBRACKET ] | |
1937 | ||
1938 | LBRACKET ::= '[' | |
1939 | RBRACKET ::= ']' | |
1940 | ||
1941 | SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER | |
1942 | ||
1943 | LINE_NUMBER ::= DIGIT {DIGIT} | |
1944 | ||
1945 | ||
1946 | Spaces around the colon in a ``SOURCE_REFERENCE`` are optional. | |
1947 | ||
1948 | The source trace that is given as the ``Source_Location`` must obey the | |
1949 | following rules (or else the pragma is ignored), where ``U`` is | |
1950 | the unit ``U`` specified by the ``Unit_Name`` argument and ``E`` is the | |
1951 | subprogram specified by the ``Entity`` argument: | |
1952 | ||
1953 | * ``FILE_NAME`` is the short name (with no directory | |
1954 | information) of the Ada source file for ``U``, using the required syntax | |
1955 | for the underlying file system (e.g. case is significant if the underlying | |
1956 | operating system is case sensitive). | |
1957 | If ``U`` is a package and ``E`` is a subprogram declared in the package | |
1958 | specification and its full declaration appears in the package body, | |
1959 | then the relevant source file is the one for the package specification; | |
1960 | analogously if ``U`` is a generic package. | |
1961 | ||
1962 | * If ``E`` is not declared in a generic instantiation (this includes | |
1963 | generic subprogram instances), the source trace includes only one source | |
1964 | line reference. ``LINE_NUMBER`` gives the line number of the occurrence | |
1965 | of the declaration of ``E`` within the source file (as a decimal literal | |
1966 | without an exponent or point). | |
1967 | ||
1968 | * If ``E`` is declared by a generic instantiation, its source trace | |
1969 | (from left to right) starts with the source location of the | |
1970 | declaration of ``E`` in the generic unit and ends with the source | |
1971 | location of the instantiation, given in square brackets. This approach is | |
1972 | applied recursively with nested instantiations: the rightmost (nested | |
1973 | most deeply in square brackets) element of the source trace is the location | |
1974 | of the outermost instantiation, and the leftmost element (that is, outside | |
1975 | of any square brackets) is the location of the declaration of ``E`` in | |
1976 | the generic unit. | |
1977 | ||
1978 | Examples: | |
1979 | ||
1980 | .. code-block:: ada | |
1981 | ||
1982 | pragma Eliminate (Pkg0, Proc); | |
1983 | -- Eliminate (all overloadings of) Proc in Pkg0 | |
1984 | ||
1985 | pragma Eliminate (Pkg1, Proc, | |
1986 | Source_Location => "pkg1.ads:8"); | |
1987 | -- Eliminate overloading of Proc at line 8 in pkg1.ads | |
1988 | ||
1989 | -- Assume the following file contents: | |
1990 | -- gen_pkg.ads | |
1991 | -- 1: generic | |
1992 | -- 2: type T is private; | |
1993 | -- 3: package Gen_Pkg is | |
1994 | -- 4: procedure Proc(N : T); | |
1995 | -- ... ... | |
1996 | -- ... end Gen_Pkg; | |
1997 | -- | |
1998 | -- q.adb | |
1999 | -- 1: with Gen_Pkg; | |
2000 | -- 2: procedure Q is | |
2001 | -- 3: package Inst_Pkg is new Gen_Pkg(Integer); | |
2002 | -- ... -- No calls on Inst_Pkg.Proc | |
2003 | -- ... end Q; | |
2004 | ||
2005 | -- The following pragma eliminates Inst_Pkg.Proc from Q | |
2006 | pragma Eliminate (Q, Proc, | |
2007 | Source_Location => "gen_pkg.ads:4[q.adb:3]"); | |
2008 | ||
2009 | ||
2010 | ||
bf5dffd3 | 2011 | Pragma Enable_Atomic_Synchronization |
2012 | ==================================== | |
2013 | .. index:: Atomic Synchronization | |
2014 | ||
2015 | ||
2016 | Syntax: | |
2017 | ||
2018 | ||
2019 | :: | |
2020 | ||
2021 | pragma Enable_Atomic_Synchronization [(Entity)]; | |
2022 | ||
2023 | ||
2024 | Ada requires that accesses (reads or writes) of an atomic variable be | |
2025 | regarded as synchronization points in the case of multiple tasks. | |
2026 | Particularly in the case of multi-processors this may require special | |
2027 | handling, e.g. the generation of memory barriers. This synchronization | |
2028 | is performed by default, but can be turned off using | |
e94434ba | 2029 | ``pragma Disable_Atomic_Synchronization``. The |
2030 | ``Enable_Atomic_Synchronization`` pragma can be used to turn | |
bf5dffd3 | 2031 | it back on. |
2032 | ||
2033 | The placement and scope rules for this pragma are the same as those | |
e94434ba | 2034 | for ``pragma Unsuppress``. In particular it can be used as a |
bf5dffd3 | 2035 | configuration pragma, or in a declaration sequence where it applies |
e94434ba | 2036 | till the end of the scope. If an ``Entity`` argument is present, |
bf5dffd3 | 2037 | the action applies only to that entity. |
2038 | ||
2039 | Pragma Export_Function | |
2040 | ====================== | |
2041 | .. index:: Argument passing mechanisms | |
2042 | ||
2043 | ||
2044 | Syntax: | |
2045 | ||
2046 | ||
2047 | :: | |
2048 | ||
2049 | pragma Export_Function ( | |
2050 | [Internal =>] LOCAL_NAME | |
2051 | [, [External =>] EXTERNAL_SYMBOL] | |
2052 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
2053 | [, [Result_Type =>] result_SUBTYPE_MARK] | |
2054 | [, [Mechanism =>] MECHANISM] | |
2055 | [, [Result_Mechanism =>] MECHANISM_NAME]); | |
2056 | ||
2057 | EXTERNAL_SYMBOL ::= | |
2058 | IDENTIFIER | |
2059 | | static_string_EXPRESSION | |
2060 | | "" | |
2061 | ||
2062 | PARAMETER_TYPES ::= | |
2063 | null | |
2064 | | TYPE_DESIGNATOR {, TYPE_DESIGNATOR} | |
2065 | ||
2066 | TYPE_DESIGNATOR ::= | |
2067 | subtype_NAME | |
2068 | | subtype_Name ' Access | |
2069 | ||
2070 | MECHANISM ::= | |
2071 | MECHANISM_NAME | |
2072 | | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) | |
2073 | ||
2074 | MECHANISM_ASSOCIATION ::= | |
2075 | [formal_parameter_NAME =>] MECHANISM_NAME | |
2076 | ||
2077 | MECHANISM_NAME ::= Value | Reference | |
2078 | ||
2079 | ||
2080 | Use this pragma to make a function externally callable and optionally | |
2081 | provide information on mechanisms to be used for passing parameter and | |
2082 | result values. We recommend, for the purposes of improving portability, | |
2083 | this pragma always be used in conjunction with a separate pragma | |
e94434ba | 2084 | ``Export``, which must precede the pragma ``Export_Function``. |
2085 | GNAT does not require a separate pragma ``Export``, but if none is | |
2086 | present, ``Convention Ada`` is assumed, which is usually | |
bf5dffd3 | 2087 | not what is wanted, so it is usually appropriate to use this |
e94434ba | 2088 | pragma in conjunction with a ``Export`` or ``Convention`` |
bf5dffd3 | 2089 | pragma that specifies the desired foreign convention. |
e94434ba | 2090 | Pragma ``Export_Function`` |
2091 | (and ``Export``, if present) must appear in the same declarative | |
bf5dffd3 | 2092 | region as the function to which they apply. |
2093 | ||
e94434ba | 2094 | The ``internal_name`` must uniquely designate the function to which the |
bf5dffd3 | 2095 | pragma applies. If more than one function name exists of this name in |
e94434ba | 2096 | the declarative part you must use the ``Parameter_Types`` and |
2097 | ``Result_Type`` parameters to achieve the required | |
2098 | unique designation. The `subtype_mark`\ s in these parameters must | |
bf5dffd3 | 2099 | exactly match the subtypes in the corresponding function specification, |
2100 | using positional notation to match parameters with subtype marks. | |
e94434ba | 2101 | The form with an ``'Access`` attribute can be used to match an |
bf5dffd3 | 2102 | anonymous access parameter. |
2103 | ||
2104 | .. index:: Suppressing external name | |
2105 | ||
2106 | Special treatment is given if the EXTERNAL is an explicit null | |
2107 | string or a static string expressions that evaluates to the null | |
2108 | string. In this case, no external name is generated. This form | |
2109 | still allows the specification of parameter mechanisms. | |
2110 | ||
2111 | Pragma Export_Object | |
2112 | ==================== | |
2113 | ||
2114 | Syntax: | |
2115 | ||
2116 | ||
2117 | :: | |
2118 | ||
2119 | pragma Export_Object | |
2120 | [Internal =>] LOCAL_NAME | |
2121 | [, [External =>] EXTERNAL_SYMBOL] | |
2122 | [, [Size =>] EXTERNAL_SYMBOL] | |
2123 | ||
2124 | EXTERNAL_SYMBOL ::= | |
2125 | IDENTIFIER | |
2126 | | static_string_EXPRESSION | |
2127 | ||
2128 | ||
2129 | This pragma designates an object as exported, and apart from the | |
2130 | extended rules for external symbols, is identical in effect to the use of | |
e94434ba | 2131 | the normal ``Export`` pragma applied to an object. You may use a |
bf5dffd3 | 2132 | separate Export pragma (and you probably should from the point of view |
e94434ba | 2133 | of portability), but it is not required. ``Size`` is syntax checked, |
bf5dffd3 | 2134 | but otherwise ignored by GNAT. |
2135 | ||
2136 | Pragma Export_Procedure | |
2137 | ======================= | |
2138 | ||
2139 | Syntax: | |
2140 | ||
2141 | ||
2142 | :: | |
2143 | ||
2144 | pragma Export_Procedure ( | |
2145 | [Internal =>] LOCAL_NAME | |
2146 | [, [External =>] EXTERNAL_SYMBOL] | |
2147 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
2148 | [, [Mechanism =>] MECHANISM]); | |
2149 | ||
2150 | EXTERNAL_SYMBOL ::= | |
2151 | IDENTIFIER | |
2152 | | static_string_EXPRESSION | |
2153 | | "" | |
2154 | ||
2155 | PARAMETER_TYPES ::= | |
2156 | null | |
2157 | | TYPE_DESIGNATOR {, TYPE_DESIGNATOR} | |
2158 | ||
2159 | TYPE_DESIGNATOR ::= | |
2160 | subtype_NAME | |
2161 | | subtype_Name ' Access | |
2162 | ||
2163 | MECHANISM ::= | |
2164 | MECHANISM_NAME | |
2165 | | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) | |
2166 | ||
2167 | MECHANISM_ASSOCIATION ::= | |
2168 | [formal_parameter_NAME =>] MECHANISM_NAME | |
2169 | ||
2170 | MECHANISM_NAME ::= Value | Reference | |
2171 | ||
2172 | ||
e94434ba | 2173 | This pragma is identical to ``Export_Function`` except that it |
bf5dffd3 | 2174 | applies to a procedure rather than a function and the parameters |
e94434ba | 2175 | ``Result_Type`` and ``Result_Mechanism`` are not permitted. |
2176 | GNAT does not require a separate pragma ``Export``, but if none is | |
2177 | present, ``Convention Ada`` is assumed, which is usually | |
bf5dffd3 | 2178 | not what is wanted, so it is usually appropriate to use this |
e94434ba | 2179 | pragma in conjunction with a ``Export`` or ``Convention`` |
bf5dffd3 | 2180 | pragma that specifies the desired foreign convention. |
2181 | ||
2182 | .. index:: Suppressing external name | |
2183 | ||
2184 | Special treatment is given if the EXTERNAL is an explicit null | |
2185 | string or a static string expressions that evaluates to the null | |
2186 | string. In this case, no external name is generated. This form | |
2187 | still allows the specification of parameter mechanisms. | |
2188 | ||
2189 | Pragma Export_Value | |
2190 | =================== | |
2191 | ||
2192 | Syntax: | |
2193 | ||
2194 | ||
2195 | :: | |
2196 | ||
2197 | pragma Export_Value ( | |
2198 | [Value =>] static_integer_EXPRESSION, | |
2199 | [Link_Name =>] static_string_EXPRESSION); | |
2200 | ||
2201 | ||
2202 | This pragma serves to export a static integer value for external use. | |
2203 | The first argument specifies the value to be exported. The Link_Name | |
2204 | argument specifies the symbolic name to be associated with the integer | |
2205 | value. This pragma is useful for defining a named static value in Ada | |
2206 | that can be referenced in assembly language units to be linked with | |
2207 | the application. This pragma is currently supported only for the | |
2208 | AAMP target and is ignored for other targets. | |
2209 | ||
2210 | Pragma Export_Valued_Procedure | |
2211 | ============================== | |
2212 | ||
2213 | Syntax: | |
2214 | ||
2215 | ||
2216 | :: | |
2217 | ||
2218 | pragma Export_Valued_Procedure ( | |
2219 | [Internal =>] LOCAL_NAME | |
2220 | [, [External =>] EXTERNAL_SYMBOL] | |
2221 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
2222 | [, [Mechanism =>] MECHANISM]); | |
2223 | ||
2224 | EXTERNAL_SYMBOL ::= | |
2225 | IDENTIFIER | |
2226 | | static_string_EXPRESSION | |
2227 | | "" | |
2228 | ||
2229 | PARAMETER_TYPES ::= | |
2230 | null | |
2231 | | TYPE_DESIGNATOR {, TYPE_DESIGNATOR} | |
2232 | ||
2233 | TYPE_DESIGNATOR ::= | |
2234 | subtype_NAME | |
2235 | | subtype_Name ' Access | |
2236 | ||
2237 | MECHANISM ::= | |
2238 | MECHANISM_NAME | |
2239 | | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) | |
2240 | ||
2241 | MECHANISM_ASSOCIATION ::= | |
2242 | [formal_parameter_NAME =>] MECHANISM_NAME | |
2243 | ||
2244 | MECHANISM_NAME ::= Value | Reference | |
2245 | ||
2246 | ||
e94434ba | 2247 | This pragma is identical to ``Export_Procedure`` except that the |
2248 | first parameter of ``LOCAL_NAME``, which must be present, must be of | |
2249 | mode ``out``, and externally the subprogram is treated as a function | |
bf5dffd3 | 2250 | with this parameter as the result of the function. GNAT provides for |
e94434ba | 2251 | this capability to allow the use of ``out`` and ``in out`` |
bf5dffd3 | 2252 | parameters in interfacing to external functions (which are not permitted |
2253 | in Ada functions). | |
e94434ba | 2254 | GNAT does not require a separate pragma ``Export``, but if none is |
2255 | present, ``Convention Ada`` is assumed, which is almost certainly | |
bf5dffd3 | 2256 | not what is wanted since the whole point of this pragma is to interface |
2257 | with foreign language functions, so it is usually appropriate to use this | |
e94434ba | 2258 | pragma in conjunction with a ``Export`` or ``Convention`` |
bf5dffd3 | 2259 | pragma that specifies the desired foreign convention. |
2260 | ||
2261 | .. index:: Suppressing external name | |
2262 | ||
2263 | Special treatment is given if the EXTERNAL is an explicit null | |
2264 | string or a static string expressions that evaluates to the null | |
2265 | string. In this case, no external name is generated. This form | |
2266 | still allows the specification of parameter mechanisms. | |
2267 | ||
2268 | Pragma Extend_System | |
2269 | ==================== | |
2270 | .. index:: System, extending | |
2271 | ||
2272 | .. index:: DEC Ada 83 | |
2273 | ||
2274 | ||
2275 | Syntax: | |
2276 | ||
2277 | ||
2278 | :: | |
2279 | ||
2280 | pragma Extend_System ([Name =>] IDENTIFIER); | |
2281 | ||
2282 | ||
2283 | This pragma is used to provide backwards compatibility with other | |
e94434ba | 2284 | implementations that extend the facilities of package ``System``. In |
2285 | GNAT, ``System`` contains only the definitions that are present in | |
bf5dffd3 | 2286 | the Ada RM. However, other implementations, notably the DEC Ada 83 |
e94434ba | 2287 | implementation, provide many extensions to package ``System``. |
bf5dffd3 | 2288 | |
2289 | For each such implementation accommodated by this pragma, GNAT provides a | |
e94434ba | 2290 | package :samp:`Aux_{xxx}`, e.g., ``Aux_DEC`` for the DEC Ada 83 |
bf5dffd3 | 2291 | implementation, which provides the required additional definitions. You |
e94434ba | 2292 | can use this package in two ways. You can ``with`` it in the normal |
2293 | way and access entities either by selection or using a ``use`` | |
bf5dffd3 | 2294 | clause. In this case no special processing is required. |
2295 | ||
2296 | However, if existing code contains references such as | |
e94434ba | 2297 | :samp:`System.{xxx}` where *xxx* is an entity in the extended |
2298 | definitions provided in package ``System``, you may use this pragma | |
2299 | to extend visibility in ``System`` in a non-standard way that | |
bf5dffd3 | 2300 | provides greater compatibility with the existing code. Pragma |
e94434ba | 2301 | ``Extend_System`` is a configuration pragma whose single argument is |
bf5dffd3 | 2302 | the name of the package containing the extended definition |
e94434ba | 2303 | (e.g., ``Aux_DEC`` for the DEC Ada case). A unit compiled under |
bf5dffd3 | 2304 | control of this pragma will be processed using special visibility |
e94434ba | 2305 | processing that looks in package :samp:`System.Aux_{xxx}` where |
2306 | :samp:`Aux_{xxx}` is the pragma argument for any entity referenced in | |
2307 | package ``System``, but not found in package ``System``. | |
bf5dffd3 | 2308 | |
e94434ba | 2309 | You can use this pragma either to access a predefined ``System`` |
2310 | extension supplied with the compiler, for example ``Aux_DEC`` or | |
bf5dffd3 | 2311 | you can construct your own extension unit following the above |
e94434ba | 2312 | definition. Note that such a package is a child of ``System`` |
bf5dffd3 | 2313 | and thus is considered part of the implementation. |
2314 | To compile it you will have to use the *-gnatg* switch | |
2315 | for compiling System units, as explained in the | |
2316 | GNAT User's Guide. | |
2317 | ||
2318 | Pragma Extensions_Allowed | |
2319 | ========================= | |
2320 | .. index:: Ada Extensions | |
2321 | ||
2322 | .. index:: GNAT Extensions | |
2323 | ||
2324 | ||
2325 | Syntax: | |
2326 | ||
2327 | .. code-block:: ada | |
2328 | ||
2329 | pragma Extensions_Allowed (On | Off); | |
2330 | ||
2331 | ||
2332 | This configuration pragma enables or disables the implementation | |
2333 | extension mode (the use of Off as a parameter cancels the effect | |
2334 | of the *-gnatX* command switch). | |
2335 | ||
2336 | In extension mode, the latest version of the Ada language is | |
2337 | implemented (currently Ada 2012), and in addition a small number | |
2338 | of GNAT specific extensions are recognized as follows: | |
2339 | ||
2340 | ||
2341 | ||
2342 | *Constrained attribute for generic objects* | |
e94434ba | 2343 | The ``Constrained`` attribute is permitted for objects of |
bf5dffd3 | 2344 | generic types. The result indicates if the corresponding actual |
2345 | is constrained. | |
2346 | ||
39adf1e6 | 2347 | .. _Pragma-Extensions_Visible: |
bf5dffd3 | 2348 | |
4a7c3b2f | 2349 | Pragma Extensions_Visible |
2350 | ========================= | |
2351 | ||
d5dcec30 | 2352 | Syntax: |
2353 | ||
2354 | .. code-block:: ada | |
2355 | ||
2356 | pragma Extensions_Visible [ (boolean_EXPRESSION) ]; | |
2357 | ||
e94434ba | 2358 | For the semantics of this pragma, see the entry for aspect ``Extensions_Visible`` |
d5dcec30 | 2359 | in the SPARK 2014 Reference Manual, section 6.1.7. |
4a7c3b2f | 2360 | |
bf5dffd3 | 2361 | Pragma External |
2362 | =============== | |
2363 | ||
2364 | Syntax: | |
2365 | ||
2366 | ||
2367 | :: | |
2368 | ||
2369 | pragma External ( | |
2370 | [ Convention =>] convention_IDENTIFIER, | |
2371 | [ Entity =>] LOCAL_NAME | |
2372 | [, [External_Name =>] static_string_EXPRESSION ] | |
2373 | [, [Link_Name =>] static_string_EXPRESSION ]); | |
2374 | ||
2375 | ||
2376 | This pragma is identical in syntax and semantics to pragma | |
e94434ba | 2377 | ``Export`` as defined in the Ada Reference Manual. It is |
bf5dffd3 | 2378 | provided for compatibility with some Ada 83 compilers that |
2379 | used this pragma for exactly the same purposes as pragma | |
e94434ba | 2380 | ``Export`` before the latter was standardized. |
bf5dffd3 | 2381 | |
2382 | Pragma External_Name_Casing | |
2383 | =========================== | |
2384 | .. index:: Dec Ada 83 casing compatibility | |
2385 | ||
2386 | .. index:: External Names, casing | |
2387 | ||
2388 | .. index:: Casing of External names | |
2389 | ||
2390 | ||
2391 | Syntax: | |
2392 | ||
2393 | ||
2394 | :: | |
2395 | ||
2396 | pragma External_Name_Casing ( | |
2397 | Uppercase | Lowercase | |
2398 | [, Uppercase | Lowercase | As_Is]); | |
2399 | ||
2400 | ||
2401 | This pragma provides control over the casing of external names associated | |
2402 | with Import and Export pragmas. There are two cases to consider: | |
2403 | ||
2404 | ||
2405 | ||
2406 | * Implicit external names | |
2407 | ||
2408 | Implicit external names are derived from identifiers. The most common case | |
2409 | arises when a standard Ada Import or Export pragma is used with only two | |
2410 | arguments, as in: | |
2411 | ||
2412 | .. code-block:: ada | |
2413 | ||
2414 | pragma Import (C, C_Routine); | |
2415 | ||
2416 | Since Ada is a case-insensitive language, the spelling of the identifier in | |
2417 | the Ada source program does not provide any information on the desired | |
2418 | casing of the external name, and so a convention is needed. In GNAT the | |
2419 | default treatment is that such names are converted to all lower case | |
2420 | letters. This corresponds to the normal C style in many environments. | |
e94434ba | 2421 | The first argument of pragma ``External_Name_Casing`` can be used to |
2422 | control this treatment. If ``Uppercase`` is specified, then the name | |
2423 | will be forced to all uppercase letters. If ``Lowercase`` is specified, | |
bf5dffd3 | 2424 | then the normal default of all lower case letters will be used. |
2425 | ||
2426 | This same implicit treatment is also used in the case of extended DEC Ada 83 | |
2427 | compatible Import and Export pragmas where an external name is explicitly | |
2428 | specified using an identifier rather than a string. | |
2429 | ||
2430 | ||
2431 | * Explicit external names | |
2432 | ||
2433 | Explicit external names are given as string literals. The most common case | |
2434 | arises when a standard Ada Import or Export pragma is used with three | |
2435 | arguments, as in: | |
2436 | ||
2437 | .. code-block:: ada | |
2438 | ||
2439 | pragma Import (C, C_Routine, "C_routine"); | |
2440 | ||
2441 | In this case, the string literal normally provides the exact casing required | |
2442 | for the external name. The second argument of pragma | |
e94434ba | 2443 | ``External_Name_Casing`` may be used to modify this behavior. |
2444 | If ``Uppercase`` is specified, then the name | |
2445 | will be forced to all uppercase letters. If ``Lowercase`` is specified, | |
bf5dffd3 | 2446 | then the name will be forced to all lowercase letters. A specification of |
e94434ba | 2447 | ``As_Is`` provides the normal default behavior in which the casing is |
bf5dffd3 | 2448 | taken from the string provided. |
2449 | ||
4475d2f0 | 2450 | This pragma may appear anywhere that a pragma is valid. In particular, it |
bf5dffd3 | 2451 | can be used as a configuration pragma in the :file:`gnat.adc` file, in which |
2452 | case it applies to all subsequent compilations, or it can be used as a program | |
2453 | unit pragma, in which case it only applies to the current unit, or it can | |
2454 | be used more locally to control individual Import/Export pragmas. | |
2455 | ||
2456 | It was primarily intended for use with OpenVMS systems, where many | |
2457 | compilers convert all symbols to upper case by default. For interfacing to | |
2458 | such compilers (e.g., the DEC C compiler), it may be convenient to use | |
2459 | the pragma: | |
2460 | ||
2461 | .. code-block:: ada | |
2462 | ||
2463 | pragma External_Name_Casing (Uppercase, Uppercase); | |
2464 | ||
2465 | ||
2466 | to enforce the upper casing of all external symbols. | |
2467 | ||
2468 | Pragma Fast_Math | |
2469 | ================ | |
2470 | ||
2471 | Syntax: | |
2472 | ||
2473 | ||
2474 | .. code-block:: ada | |
2475 | ||
2476 | pragma Fast_Math; | |
2477 | ||
2478 | ||
2479 | This is a configuration pragma which activates a mode in which speed is | |
2480 | considered more important for floating-point operations than absolutely | |
2481 | accurate adherence to the requirements of the standard. Currently the | |
2482 | following operations are affected: | |
2483 | ||
2484 | ||
2485 | ||
2486 | *Complex Multiplication* | |
2487 | The normal simple formula for complex multiplication can result in intermediate | |
2488 | overflows for numbers near the end of the range. The Ada standard requires that | |
2489 | this situation be detected and corrected by scaling, but in Fast_Math mode such | |
2490 | cases will simply result in overflow. Note that to take advantage of this you | |
e94434ba | 2491 | must instantiate your own version of ``Ada.Numerics.Generic_Complex_Types`` |
bf5dffd3 | 2492 | under control of the pragma, rather than use the preinstantiated versions. |
2493 | ||
39adf1e6 | 2494 | .. _Pragma-Favor_Top_Level: |
2495 | ||
bf5dffd3 | 2496 | Pragma Favor_Top_Level |
2497 | ====================== | |
2498 | ||
2499 | Syntax: | |
2500 | ||
2501 | ||
2502 | .. code-block:: ada | |
2503 | ||
2504 | pragma Favor_Top_Level (type_NAME); | |
2505 | ||
2506 | ||
e94434ba | 2507 | The argument of pragma ``Favor_Top_Level`` must be a named access-to-subprogram |
8f09eafa | 2508 | type. This pragma is an efficiency hint to the compiler, regarding the use of |
e94434ba | 2509 | ``'Access`` or ``'Unrestricted_Access`` on nested (non-library-level) subprograms. |
8f09eafa | 2510 | The pragma means that nested subprograms are not used with this type, or are |
2511 | rare, so that the generated code should be efficient in the top-level case. | |
2512 | When this pragma is used, dynamically generated trampolines may be used on some | |
e94434ba | 2513 | targets for nested subprograms. See restriction ``No_Implicit_Dynamic_Code``. |
bf5dffd3 | 2514 | |
2515 | Pragma Finalize_Storage_Only | |
2516 | ============================ | |
2517 | ||
2518 | Syntax: | |
2519 | ||
2520 | ||
2521 | .. code-block:: ada | |
2522 | ||
2523 | pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME); | |
2524 | ||
2525 | ||
e94434ba | 2526 | The argument of pragma ``Finalize_Storage_Only`` must denote a local type which |
2527 | is derived from ``Ada.Finalization.Controlled`` or ``Limited_Controlled``. The | |
2528 | pragma suppresses the call to ``Finalize`` for declared library-level objects | |
8f09eafa | 2529 | of the argument type. This is mostly useful for types where finalization is |
2530 | only used to deal with storage reclamation since in most environments it is | |
2531 | not necessary to reclaim memory just before terminating execution, hence the | |
2532 | name. Note that this pragma does not suppress Finalize calls for library-level | |
e94434ba | 2533 | heap-allocated objects (see pragma ``No_Heap_Finalization``). |
bf5dffd3 | 2534 | |
2535 | Pragma Float_Representation | |
2536 | =========================== | |
2537 | ||
2538 | Syntax:: | |
2539 | ||
2540 | pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]); | |
2541 | ||
2542 | FLOAT_REP ::= VAX_Float | IEEE_Float | |
2543 | ||
2544 | ||
2545 | In the one argument form, this pragma is a configuration pragma which | |
2546 | allows control over the internal representation chosen for the predefined | |
e94434ba | 2547 | floating point types declared in the packages ``Standard`` and |
2548 | ``System``. This pragma is only provided for compatibility and has no effect. | |
bf5dffd3 | 2549 | |
2550 | The two argument form specifies the representation to be used for | |
2551 | the specified floating-point type. The argument must | |
e94434ba | 2552 | be ``IEEE_Float`` to specify the use of IEEE format, as follows: |
bf5dffd3 | 2553 | |
2554 | * | |
2555 | For a digits value of 6, 32-bit IEEE short format will be used. | |
2556 | * | |
2557 | For a digits value of 15, 64-bit IEEE long format will be used. | |
2558 | * | |
2559 | No other value of digits is permitted. | |
2560 | ||
39adf1e6 | 2561 | .. _Pragma-Ghost: |
2562 | ||
4a7c3b2f | 2563 | Pragma Ghost |
2564 | ============ | |
2565 | ||
d5dcec30 | 2566 | Syntax: |
2567 | ||
2568 | .. code-block:: ada | |
2569 | ||
2570 | pragma Ghost [ (boolean_EXPRESSION) ]; | |
2571 | ||
e94434ba | 2572 | For the semantics of this pragma, see the entry for aspect ``Ghost`` in the SPARK |
d5dcec30 | 2573 | 2014 Reference Manual, section 6.9. |
4a7c3b2f | 2574 | |
39adf1e6 | 2575 | .. _Pragma-Global: |
2576 | ||
bf5dffd3 | 2577 | Pragma Global |
2578 | ============= | |
2579 | ||
d5dcec30 | 2580 | Syntax: |
2581 | ||
2582 | .. code-block:: ada | |
2583 | ||
2584 | pragma Global (GLOBAL_SPECIFICATION); | |
2585 | ||
2586 | GLOBAL_SPECIFICATION ::= | |
2587 | null | |
2588 | | (GLOBAL_LIST) | |
2589 | | (MODED_GLOBAL_LIST {, MODED_GLOBAL_LIST}) | |
2590 | ||
2591 | MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST | |
2592 | ||
2593 | MODE_SELECTOR ::= In_Out | Input | Output | Proof_In | |
2594 | GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM {, GLOBAL_ITEM}) | |
2595 | GLOBAL_ITEM ::= NAME | |
2596 | ||
e94434ba | 2597 | For the semantics of this pragma, see the entry for aspect ``Global`` in the |
d5dcec30 | 2598 | SPARK 2014 Reference Manual, section 6.1.4. |
bf5dffd3 | 2599 | |
2600 | Pragma Ident | |
2601 | ============ | |
2602 | ||
2603 | Syntax: | |
2604 | ||
2605 | ||
2606 | .. code-block:: ada | |
2607 | ||
2608 | pragma Ident (static_string_EXPRESSION); | |
2609 | ||
2610 | ||
e94434ba | 2611 | This pragma is identical in effect to pragma ``Comment``. It is provided |
bf5dffd3 | 2612 | for compatibility with other Ada compilers providing this pragma. |
2613 | ||
9eae7e2d | 2614 | Pragma Ignore_Pragma |
2615 | ==================== | |
2616 | ||
2617 | Syntax: | |
2618 | ||
2619 | ||
2620 | .. code-block:: ada | |
2621 | ||
2622 | pragma Ignore_Pragma (pragma_IDENTIFIER); | |
2623 | ||
2624 | This is a configuration pragma | |
2625 | that takes a single argument that is a simple identifier. Any subsequent | |
2626 | use of a pragma whose pragma identifier matches this argument will be | |
2627 | silently ignored. This may be useful when legacy code or code intended | |
2628 | for compilation with some other compiler contains pragmas that match the | |
e94434ba | 2629 | name, but not the exact implementation, of a GNAT pragma. The use of this |
2630 | pragma allows such pragmas to be ignored, which may be useful in CodePeer | |
9eae7e2d | 2631 | mode, or during porting of legacy code. |
2632 | ||
bf5dffd3 | 2633 | Pragma Implementation_Defined |
2634 | ============================= | |
2635 | ||
2636 | Syntax: | |
2637 | ||
2638 | ||
2639 | .. code-block:: ada | |
2640 | ||
2641 | pragma Implementation_Defined (local_NAME); | |
2642 | ||
2643 | ||
0c01a524 | 2644 | This pragma marks a previously declared entity as implementation-defined. |
bf5dffd3 | 2645 | For an overloaded entity, applies to the most recent homonym. |
2646 | ||
2647 | ||
2648 | .. code-block:: ada | |
2649 | ||
2650 | pragma Implementation_Defined; | |
2651 | ||
2652 | ||
2653 | The form with no arguments appears anywhere within a scope, most | |
2654 | typically a package spec, and indicates that all entities that are | |
2655 | defined within the package spec are Implementation_Defined. | |
2656 | ||
2657 | This pragma is used within the GNAT runtime library to identify | |
2658 | implementation-defined entities introduced in language-defined units, | |
2659 | for the purpose of implementing the No_Implementation_Identifiers | |
2660 | restriction. | |
2661 | ||
2662 | Pragma Implemented | |
2663 | ================== | |
2664 | ||
2665 | Syntax: | |
2666 | ||
2667 | ||
2668 | :: | |
2669 | ||
2670 | pragma Implemented (procedure_LOCAL_NAME, implementation_kind); | |
2671 | ||
2672 | implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any | |
2673 | ||
2674 | ||
2675 | This is an Ada 2012 representation pragma which applies to protected, task | |
2676 | and synchronized interface primitives. The use of pragma Implemented provides | |
2677 | a way to impose a static requirement on the overriding operation by adhering | |
2678 | to one of the three implementation kinds: entry, protected procedure or any of | |
2679 | the above. This pragma is available in all earlier versions of Ada as an | |
2680 | implementation-defined pragma. | |
2681 | ||
2682 | ||
2683 | .. code-block:: ada | |
2684 | ||
2685 | type Synch_Iface is synchronized interface; | |
2686 | procedure Prim_Op (Obj : in out Iface) is abstract; | |
2687 | pragma Implemented (Prim_Op, By_Protected_Procedure); | |
2688 | ||
2689 | protected type Prot_1 is new Synch_Iface with | |
2690 | procedure Prim_Op; -- Legal | |
2691 | end Prot_1; | |
2692 | ||
2693 | protected type Prot_2 is new Synch_Iface with | |
2694 | entry Prim_Op; -- Illegal | |
2695 | end Prot_2; | |
2696 | ||
2697 | task type Task_Typ is new Synch_Iface with | |
2698 | entry Prim_Op; -- Illegal | |
2699 | end Task_Typ; | |
2700 | ||
2701 | ||
2702 | When applied to the procedure_or_entry_NAME of a requeue statement, pragma | |
2703 | Implemented determines the runtime behavior of the requeue. Implementation kind | |
2704 | By_Entry guarantees that the action of requeueing will proceed from an entry to | |
2705 | another entry. Implementation kind By_Protected_Procedure transforms the | |
2706 | requeue into a dispatching call, thus eliminating the chance of blocking. Kind | |
2707 | By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on | |
2708 | the target's overriding subprogram kind. | |
2709 | ||
2710 | Pragma Implicit_Packing | |
2711 | ======================= | |
2712 | .. index:: Rational Profile | |
2713 | ||
2714 | Syntax: | |
2715 | ||
2716 | ||
2717 | .. code-block:: ada | |
2718 | ||
2719 | pragma Implicit_Packing; | |
2720 | ||
2721 | ||
2722 | This is a configuration pragma that requests implicit packing for packed | |
2723 | arrays for which a size clause is given but no explicit pragma Pack or | |
2724 | specification of Component_Size is present. It also applies to records | |
2725 | where no record representation clause is present. Consider this example: | |
2726 | ||
2727 | ||
2728 | .. code-block:: ada | |
2729 | ||
2730 | type R is array (0 .. 7) of Boolean; | |
2731 | for R'Size use 8; | |
2732 | ||
2733 | ||
2734 | In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause | |
2735 | does not change the layout of a composite object. So the Size clause in the | |
2736 | above example is normally rejected, since the default layout of the array uses | |
2737 | 8-bit components, and thus the array requires a minimum of 64 bits. | |
2738 | ||
2739 | If this declaration is compiled in a region of code covered by an occurrence | |
2740 | of the configuration pragma Implicit_Packing, then the Size clause in this | |
2741 | and similar examples will cause implicit packing and thus be accepted. For | |
2742 | this implicit packing to occur, the type in question must be an array of small | |
2743 | components whose size is known at compile time, and the Size clause must | |
2744 | specify the exact size that corresponds to the number of elements in the array | |
2745 | multiplied by the size in bits of the component type (both single and | |
2746 | multi-dimensioned arrays can be controlled with this pragma). | |
2747 | ||
2748 | .. index:: Array packing | |
2749 | ||
2750 | Similarly, the following example shows the use in the record case | |
2751 | ||
2752 | ||
2753 | .. code-block:: ada | |
2754 | ||
2755 | type r is record | |
2756 | a, b, c, d, e, f, g, h : boolean; | |
2757 | chr : character; | |
2758 | end record; | |
2759 | for r'size use 16; | |
2760 | ||
2761 | ||
2762 | Without a pragma Pack, each Boolean field requires 8 bits, so the | |
2763 | minimum size is 72 bits, but with a pragma Pack, 16 bits would be | |
2764 | sufficient. The use of pragma Implicit_Packing allows this record | |
2765 | declaration to compile without an explicit pragma Pack. | |
2766 | ||
2767 | Pragma Import_Function | |
2768 | ====================== | |
2769 | ||
2770 | Syntax: | |
2771 | ||
2772 | ||
2773 | :: | |
2774 | ||
2775 | pragma Import_Function ( | |
2776 | [Internal =>] LOCAL_NAME, | |
2777 | [, [External =>] EXTERNAL_SYMBOL] | |
2778 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
2779 | [, [Result_Type =>] SUBTYPE_MARK] | |
2780 | [, [Mechanism =>] MECHANISM] | |
2781 | [, [Result_Mechanism =>] MECHANISM_NAME]); | |
2782 | ||
2783 | EXTERNAL_SYMBOL ::= | |
2784 | IDENTIFIER | |
2785 | | static_string_EXPRESSION | |
2786 | ||
2787 | PARAMETER_TYPES ::= | |
2788 | null | |
2789 | | TYPE_DESIGNATOR {, TYPE_DESIGNATOR} | |
2790 | ||
2791 | TYPE_DESIGNATOR ::= | |
2792 | subtype_NAME | |
2793 | | subtype_Name ' Access | |
2794 | ||
2795 | MECHANISM ::= | |
2796 | MECHANISM_NAME | |
2797 | | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) | |
2798 | ||
2799 | MECHANISM_ASSOCIATION ::= | |
2800 | [formal_parameter_NAME =>] MECHANISM_NAME | |
2801 | ||
2802 | MECHANISM_NAME ::= | |
2803 | Value | |
2804 | | Reference | |
2805 | ||
2806 | ||
e94434ba | 2807 | This pragma is used in conjunction with a pragma ``Import`` to |
bf5dffd3 | 2808 | specify additional information for an imported function. The pragma |
e94434ba | 2809 | ``Import`` (or equivalent pragma ``Interface``) must precede the |
2810 | ``Import_Function`` pragma and both must appear in the same | |
bf5dffd3 | 2811 | declarative part as the function specification. |
2812 | ||
e94434ba | 2813 | The ``Internal`` argument must uniquely designate |
bf5dffd3 | 2814 | the function to which the |
2815 | pragma applies. If more than one function name exists of this name in | |
e94434ba | 2816 | the declarative part you must use the ``Parameter_Types`` and |
2817 | ``Result_Type`` parameters to achieve the required unique | |
bf5dffd3 | 2818 | designation. Subtype marks in these parameters must exactly match the |
2819 | subtypes in the corresponding function specification, using positional | |
2820 | notation to match parameters with subtype marks. | |
e94434ba | 2821 | The form with an ``'Access`` attribute can be used to match an |
bf5dffd3 | 2822 | anonymous access parameter. |
2823 | ||
e94434ba | 2824 | You may optionally use the ``Mechanism`` and ``Result_Mechanism`` |
bf5dffd3 | 2825 | parameters to specify passing mechanisms for the |
2826 | parameters and result. If you specify a single mechanism name, it | |
2827 | applies to all parameters. Otherwise you may specify a mechanism on a | |
2828 | parameter by parameter basis using either positional or named | |
2829 | notation. If the mechanism is not specified, the default mechanism | |
2830 | is used. | |
2831 | ||
2832 | Pragma Import_Object | |
2833 | ==================== | |
2834 | ||
2835 | Syntax: | |
2836 | ||
2837 | ||
2838 | :: | |
2839 | ||
2840 | pragma Import_Object | |
2841 | [Internal =>] LOCAL_NAME | |
2842 | [, [External =>] EXTERNAL_SYMBOL] | |
2843 | [, [Size =>] EXTERNAL_SYMBOL]); | |
2844 | ||
2845 | EXTERNAL_SYMBOL ::= | |
2846 | IDENTIFIER | |
2847 | | static_string_EXPRESSION | |
2848 | ||
2849 | ||
2850 | This pragma designates an object as imported, and apart from the | |
2851 | extended rules for external symbols, is identical in effect to the use of | |
e94434ba | 2852 | the normal ``Import`` pragma applied to an object. Unlike the |
2853 | subprogram case, you need not use a separate ``Import`` pragma, | |
bf5dffd3 | 2854 | although you may do so (and probably should do so from a portability |
e94434ba | 2855 | point of view). ``size`` is syntax checked, but otherwise ignored by |
bf5dffd3 | 2856 | GNAT. |
2857 | ||
2858 | Pragma Import_Procedure | |
2859 | ======================= | |
2860 | ||
2861 | Syntax: | |
2862 | ||
2863 | ||
2864 | :: | |
2865 | ||
2866 | pragma Import_Procedure ( | |
2867 | [Internal =>] LOCAL_NAME | |
2868 | [, [External =>] EXTERNAL_SYMBOL] | |
2869 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
2870 | [, [Mechanism =>] MECHANISM]); | |
2871 | ||
2872 | EXTERNAL_SYMBOL ::= | |
2873 | IDENTIFIER | |
2874 | | static_string_EXPRESSION | |
2875 | ||
2876 | PARAMETER_TYPES ::= | |
2877 | null | |
2878 | | TYPE_DESIGNATOR {, TYPE_DESIGNATOR} | |
2879 | ||
2880 | TYPE_DESIGNATOR ::= | |
2881 | subtype_NAME | |
2882 | | subtype_Name ' Access | |
2883 | ||
2884 | MECHANISM ::= | |
2885 | MECHANISM_NAME | |
2886 | | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) | |
2887 | ||
2888 | MECHANISM_ASSOCIATION ::= | |
2889 | [formal_parameter_NAME =>] MECHANISM_NAME | |
2890 | ||
2891 | MECHANISM_NAME ::= Value | Reference | |
2892 | ||
2893 | ||
e94434ba | 2894 | This pragma is identical to ``Import_Function`` except that it |
bf5dffd3 | 2895 | applies to a procedure rather than a function and the parameters |
e94434ba | 2896 | ``Result_Type`` and ``Result_Mechanism`` are not permitted. |
bf5dffd3 | 2897 | |
2898 | Pragma Import_Valued_Procedure | |
2899 | ============================== | |
2900 | ||
2901 | Syntax: | |
2902 | ||
2903 | ||
2904 | :: | |
2905 | ||
2906 | pragma Import_Valued_Procedure ( | |
2907 | [Internal =>] LOCAL_NAME | |
2908 | [, [External =>] EXTERNAL_SYMBOL] | |
2909 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
2910 | [, [Mechanism =>] MECHANISM]); | |
2911 | ||
2912 | EXTERNAL_SYMBOL ::= | |
2913 | IDENTIFIER | |
2914 | | static_string_EXPRESSION | |
2915 | ||
2916 | PARAMETER_TYPES ::= | |
2917 | null | |
2918 | | TYPE_DESIGNATOR {, TYPE_DESIGNATOR} | |
2919 | ||
2920 | TYPE_DESIGNATOR ::= | |
2921 | subtype_NAME | |
2922 | | subtype_Name ' Access | |
2923 | ||
2924 | MECHANISM ::= | |
2925 | MECHANISM_NAME | |
2926 | | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) | |
2927 | ||
2928 | MECHANISM_ASSOCIATION ::= | |
2929 | [formal_parameter_NAME =>] MECHANISM_NAME | |
2930 | ||
2931 | MECHANISM_NAME ::= Value | Reference | |
2932 | ||
2933 | ||
e94434ba | 2934 | This pragma is identical to ``Import_Procedure`` except that the |
2935 | first parameter of ``LOCAL_NAME``, which must be present, must be of | |
2936 | mode ``out``, and externally the subprogram is treated as a function | |
bf5dffd3 | 2937 | with this parameter as the result of the function. The purpose of this |
e94434ba | 2938 | capability is to allow the use of ``out`` and ``in out`` |
bf5dffd3 | 2939 | parameters in interfacing to external functions (which are not permitted |
e94434ba | 2940 | in Ada functions). You may optionally use the ``Mechanism`` |
bf5dffd3 | 2941 | parameters to specify passing mechanisms for the parameters. |
2942 | If you specify a single mechanism name, it applies to all parameters. | |
2943 | Otherwise you may specify a mechanism on a parameter by parameter | |
2944 | basis using either positional or named notation. If the mechanism is not | |
2945 | specified, the default mechanism is used. | |
2946 | ||
2947 | Note that it is important to use this pragma in conjunction with a separate | |
2948 | pragma Import that specifies the desired convention, since otherwise the | |
2949 | default convention is Ada, which is almost certainly not what is required. | |
2950 | ||
2951 | Pragma Independent | |
2952 | ================== | |
2953 | ||
2954 | Syntax: | |
2955 | ||
2956 | ||
2957 | .. code-block:: ada | |
2958 | ||
2959 | pragma Independent (Local_NAME); | |
2960 | ||
2961 | ||
2962 | This pragma is standard in Ada 2012 mode (which also provides an aspect | |
2963 | of the same name). It is also available as an implementation-defined | |
2964 | pragma in all earlier versions. It specifies that the | |
2965 | designated object or all objects of the designated type must be | |
2966 | independently addressable. This means that separate tasks can safely | |
2967 | manipulate such objects. For example, if two components of a record are | |
2968 | independent, then two separate tasks may access these two components. | |
2969 | This may place | |
2970 | constraints on the representation of the object (for instance prohibiting | |
2971 | tight packing). | |
2972 | ||
2973 | Pragma Independent_Components | |
2974 | ============================= | |
2975 | ||
2976 | Syntax: | |
2977 | ||
2978 | ||
2979 | .. code-block:: ada | |
2980 | ||
2981 | pragma Independent_Components (Local_NAME); | |
2982 | ||
2983 | ||
2984 | This pragma is standard in Ada 2012 mode (which also provides an aspect | |
2985 | of the same name). It is also available as an implementation-defined | |
2986 | pragma in all earlier versions. It specifies that the components of the | |
2987 | designated object, or the components of each object of the designated | |
2988 | type, must be | |
2989 | independently addressable. This means that separate tasks can safely | |
2990 | manipulate separate components in the composite object. This may place | |
2991 | constraints on the representation of the object (for instance prohibiting | |
2992 | tight packing). | |
2993 | ||
39adf1e6 | 2994 | .. _Pragma-Initial_Condition: |
2995 | ||
bf5dffd3 | 2996 | Pragma Initial_Condition |
2997 | ======================== | |
2998 | ||
d5dcec30 | 2999 | Syntax: |
3000 | ||
3001 | .. code-block:: ada | |
3002 | ||
3003 | pragma Initial_Condition (boolean_EXPRESSION); | |
3004 | ||
e94434ba | 3005 | For the semantics of this pragma, see the entry for aspect ``Initial_Condition`` |
d5dcec30 | 3006 | in the SPARK 2014 Reference Manual, section 7.1.6. |
bf5dffd3 | 3007 | |
3008 | Pragma Initialize_Scalars | |
3009 | ========================= | |
3010 | .. index:: debugging with Initialize_Scalars | |
3011 | ||
3012 | Syntax: | |
3013 | ||
3014 | ||
3015 | .. code-block:: ada | |
3016 | ||
4475d2f0 | 3017 | pragma Initialize_Scalars |
3018 | [ ( TYPE_VALUE_PAIR {, TYPE_VALUE_PAIR} ) ]; | |
bf5dffd3 | 3019 | |
4475d2f0 | 3020 | TYPE_VALUE_PAIR ::= |
3021 | SCALAR_TYPE => static_EXPRESSION | |
bf5dffd3 | 3022 | |
4475d2f0 | 3023 | SCALAR_TYPE := |
3024 | Short_Float | |
3025 | | Float | |
3026 | | Long_Float | |
3027 | | Long_Long_Flat | |
3028 | | Signed_8 | |
3029 | | Signed_16 | |
3030 | | Signed_32 | |
3031 | | Signed_64 | |
3032 | | Unsigned_8 | |
3033 | | Unsigned_16 | |
3034 | | Unsigned_32 | |
3035 | | Unsigned_64 | |
bf5dffd3 | 3036 | |
bf5dffd3 | 3037 | |
4475d2f0 | 3038 | This pragma is similar to ``Normalize_Scalars`` conceptually but has two |
3039 | important differences. | |
bf5dffd3 | 3040 | |
4475d2f0 | 3041 | First, there is no requirement for the pragma to be used uniformly in all units |
3042 | of a partition. In particular, it is fine to use this just for some or all of | |
3043 | the application units of a partition, without needing to recompile the run-time | |
3044 | library. In the case where some units are compiled with the pragma, and some | |
3045 | without, then a declaration of a variable where the type is defined in package | |
3046 | Standard or is locally declared will always be subject to initialization, as | |
3047 | will any declaration of a scalar variable. For composite variables, whether the | |
3048 | variable is initialized may also depend on whether the package in which the | |
3049 | type of the variable is declared is compiled with the pragma. | |
bf5dffd3 | 3050 | |
4475d2f0 | 3051 | The other important difference is that the programmer can control the value |
3052 | used for initializing scalar objects. This effect can be achieved in several | |
3053 | different ways: | |
3054 | ||
3055 | * At compile time, the programmer can specify the invalid value for a | |
3056 | particular family of scalar types using the optional arguments of the pragma. | |
3057 | ||
3058 | The compile-time approach is intended to optimize the generated code for the | |
3059 | pragma, by possibly using fast operations such as ``memset``. | |
3060 | ||
3061 | * At bind time, the programmer has several options: | |
3062 | ||
3063 | * Initialization with invalid values (similar to Normalize_Scalars, though | |
3064 | for Initialize_Scalars it is not always possible to determine the invalid | |
3065 | values in complex cases like signed component fields with nonstandard | |
3066 | sizes). | |
3067 | ||
3068 | * Initialization with high values. | |
3069 | ||
3070 | * Initialization with low values. | |
3071 | ||
3072 | * Initialization with a specific bit pattern. | |
3073 | ||
3074 | See the GNAT User's Guide for binder options for specifying these cases. | |
3075 | ||
3076 | The bind-time approach is intended to provide fast turnaround for testing | |
3077 | with different values, without having to recompile the program. | |
3078 | ||
3079 | * At execution time, the programmer can speify the invalid values using an | |
3080 | environment variable. See the GNAT User's Guide for details. | |
3081 | ||
3082 | The execution-time approach is intended to provide fast turnaround for | |
3083 | testing with different values, without having to recompile and rebind the | |
3084 | program. | |
3085 | ||
3086 | Note that pragma ``Initialize_Scalars`` is particularly useful in conjunction | |
3087 | with the enhanced validity checking that is now provided in GNAT, which checks | |
3088 | for invalid values under more conditions. Using this feature (see description | |
3089 | of the *-gnatV* flag in the GNAT User's Guide) in conjunction with pragma | |
3090 | ``Initialize_Scalars`` provides a powerful new tool to assist in the detection | |
3091 | of problems caused by uninitialized variables. | |
bf5dffd3 | 3092 | |
4475d2f0 | 3093 | Note: the use of ``Initialize_Scalars`` has a fairly extensive effect on the |
3094 | generated code. This may cause your code to be substantially larger. It may | |
3095 | also cause an increase in the amount of stack required, so it is probably a | |
3096 | good idea to turn on stack checking (see description of stack checking in the | |
3097 | GNAT User's Guide) when using this pragma. | |
bf5dffd3 | 3098 | |
39adf1e6 | 3099 | .. _Pragma-Initializes: |
3100 | ||
bf5dffd3 | 3101 | Pragma Initializes |
3102 | ================== | |
3103 | ||
d5dcec30 | 3104 | Syntax: |
3105 | ||
3106 | .. code-block:: ada | |
3107 | ||
3108 | pragma Initializes (INITIALIZATION_LIST); | |
3109 | ||
3110 | INITIALIZATION_LIST ::= | |
3111 | null | |
3112 | | (INITIALIZATION_ITEM {, INITIALIZATION_ITEM}) | |
3113 | ||
3114 | INITIALIZATION_ITEM ::= name [=> INPUT_LIST] | |
3115 | ||
3116 | INPUT_LIST ::= | |
3117 | null | |
3118 | | INPUT | |
3119 | | (INPUT {, INPUT}) | |
3120 | ||
3121 | INPUT ::= name | |
3122 | ||
e94434ba | 3123 | For the semantics of this pragma, see the entry for aspect ``Initializes`` in the |
d5dcec30 | 3124 | SPARK 2014 Reference Manual, section 7.1.5. |
bf5dffd3 | 3125 | |
39adf1e6 | 3126 | .. _Pragma-Inline_Always: |
3127 | ||
bf5dffd3 | 3128 | Pragma Inline_Always |
3129 | ==================== | |
3130 | ||
3131 | Syntax: | |
3132 | ||
3133 | ||
3134 | :: | |
3135 | ||
3136 | pragma Inline_Always (NAME [, NAME]); | |
3137 | ||
3138 | ||
e94434ba | 3139 | Similar to pragma ``Inline`` except that inlining is unconditional. |
8f09eafa | 3140 | Inline_Always instructs the compiler to inline every direct call to the |
3141 | subprogram or else to emit a compilation error, independently of any | |
3142 | option, in particular *-gnatn* or *-gnatN* or the optimization level. | |
e94434ba | 3143 | It is an error to take the address or access of ``NAME``. It is also an error to |
8f09eafa | 3144 | apply this pragma to a primitive operation of a tagged type. Thanks to such |
e94434ba | 3145 | restrictions, the compiler is allowed to remove the out-of-line body of ``NAME``. |
bf5dffd3 | 3146 | |
3147 | Pragma Inline_Generic | |
3148 | ===================== | |
3149 | ||
3150 | Syntax: | |
3151 | ||
3152 | ||
3153 | :: | |
3154 | ||
3155 | pragma Inline_Generic (GNAME {, GNAME}); | |
3156 | ||
3157 | GNAME ::= generic_unit_NAME | generic_instance_NAME | |
3158 | ||
3159 | ||
3160 | This pragma is provided for compatibility with Dec Ada 83. It has | |
e94434ba | 3161 | no effect in GNAT (which always inlines generics), other |
bf5dffd3 | 3162 | than to check that the given names are all names of generic units or |
3163 | generic instances. | |
3164 | ||
3165 | Pragma Interface | |
3166 | ================ | |
3167 | ||
3168 | Syntax: | |
3169 | ||
3170 | ||
3171 | :: | |
3172 | ||
3173 | pragma Interface ( | |
3174 | [Convention =>] convention_identifier, | |
3175 | [Entity =>] local_NAME | |
3176 | [, [External_Name =>] static_string_expression] | |
3177 | [, [Link_Name =>] static_string_expression]); | |
3178 | ||
3179 | ||
3180 | This pragma is identical in syntax and semantics to | |
e94434ba | 3181 | the standard Ada pragma ``Import``. It is provided for compatibility |
bf5dffd3 | 3182 | with Ada 83. The definition is upwards compatible both with pragma |
e94434ba | 3183 | ``Interface`` as defined in the Ada 83 Reference Manual, and also |
bf5dffd3 | 3184 | with some extended implementations of this pragma in certain Ada 83 |
e94434ba | 3185 | implementations. The only difference between pragma ``Interface`` |
3186 | and pragma ``Import`` is that there is special circuitry to allow | |
bf5dffd3 | 3187 | both pragmas to appear for the same subprogram entity (normally it |
e94434ba | 3188 | is illegal to have multiple ``Import`` pragmas. This is useful in |
bf5dffd3 | 3189 | maintaining Ada 83/Ada 95 compatibility and is compatible with other |
3190 | Ada 83 compilers. | |
3191 | ||
3192 | Pragma Interface_Name | |
3193 | ===================== | |
3194 | ||
3195 | Syntax: | |
3196 | ||
3197 | ||
3198 | :: | |
3199 | ||
3200 | pragma Interface_Name ( | |
3201 | [Entity =>] LOCAL_NAME | |
3202 | [, [External_Name =>] static_string_EXPRESSION] | |
3203 | [, [Link_Name =>] static_string_EXPRESSION]); | |
3204 | ||
3205 | ||
3206 | This pragma provides an alternative way of specifying the interface name | |
3207 | for an interfaced subprogram, and is provided for compatibility with Ada | |
3208 | 83 compilers that use the pragma for this purpose. You must provide at | |
e94434ba | 3209 | least one of ``External_Name`` or ``Link_Name``. |
bf5dffd3 | 3210 | |
3211 | Pragma Interrupt_Handler | |
3212 | ======================== | |
3213 | ||
3214 | Syntax: | |
3215 | ||
3216 | ||
3217 | .. code-block:: ada | |
3218 | ||
3219 | pragma Interrupt_Handler (procedure_LOCAL_NAME); | |
3220 | ||
3221 | ||
3222 | This program unit pragma is supported for parameterless protected procedures | |
3223 | as described in Annex C of the Ada Reference Manual. On the AAMP target | |
3224 | the pragma can also be specified for nonprotected parameterless procedures | |
3225 | that are declared at the library level (which includes procedures | |
3226 | declared at the top level of a library package). In the case of AAMP, | |
3227 | when this pragma is applied to a nonprotected procedure, the instruction | |
e94434ba | 3228 | ``IERET`` is generated for returns from the procedure, enabling |
bf5dffd3 | 3229 | maskable interrupts, in place of the normal return instruction. |
3230 | ||
3231 | Pragma Interrupt_State | |
3232 | ====================== | |
3233 | ||
3234 | Syntax: | |
3235 | ||
3236 | ||
3237 | :: | |
3238 | ||
3239 | pragma Interrupt_State | |
3240 | ([Name =>] value, | |
3241 | [State =>] SYSTEM | RUNTIME | USER); | |
3242 | ||
3243 | ||
3244 | Normally certain interrupts are reserved to the implementation. Any attempt | |
3245 | to attach an interrupt causes Program_Error to be raised, as described in | |
e94434ba | 3246 | RM C.3.2(22). A typical example is the ``SIGINT`` interrupt used in |
bf5dffd3 | 3247 | many systems for an :kbd:`Ctrl-C` interrupt. Normally this interrupt is |
3248 | reserved to the implementation, so that :kbd:`Ctrl-C` can be used to | |
e94434ba | 3249 | interrupt execution. Additionally, signals such as ``SIGSEGV``, |
3250 | ``SIGABRT``, ``SIGFPE`` and ``SIGILL`` are often mapped to specific | |
bf5dffd3 | 3251 | Ada exceptions, or used to implement run-time functions such as the |
e94434ba | 3252 | ``abort`` statement and stack overflow checking. |
bf5dffd3 | 3253 | |
e94434ba | 3254 | Pragma ``Interrupt_State`` provides a general mechanism for overriding |
bf5dffd3 | 3255 | such uses of interrupts. It subsumes the functionality of pragma |
e94434ba | 3256 | ``Unreserve_All_Interrupts``. Pragma ``Interrupt_State`` is not |
bf5dffd3 | 3257 | available on Windows or VMS. On all other platforms than VxWorks, |
3258 | it applies to signals; on VxWorks, it applies to vectored hardware interrupts | |
3259 | and may be used to mark interrupts required by the board support package | |
3260 | as reserved. | |
3261 | ||
3262 | Interrupts can be in one of three states: | |
3263 | ||
3264 | * System | |
3265 | ||
3266 | The interrupt is reserved (no Ada handler can be installed), and the | |
3267 | Ada run-time may not install a handler. As a result you are guaranteed | |
8f09eafa | 3268 | standard system default action if this interrupt is raised. This also allows |
3269 | installing a low level handler via C APIs such as sigaction(), outside | |
3270 | of Ada control. | |
bf5dffd3 | 3271 | |
3272 | * Runtime | |
3273 | ||
3274 | The interrupt is reserved (no Ada handler can be installed). The run time | |
3275 | is allowed to install a handler for internal control purposes, but is | |
3276 | not required to do so. | |
3277 | ||
3278 | * User | |
3279 | ||
8f09eafa | 3280 | The interrupt is unreserved. The user may install an Ada handler via |
3281 | Ada.Interrupts and pragma Interrupt_Handler or Attach_Handler to provide | |
bf5dffd3 | 3282 | some other action. |
3283 | ||
e94434ba | 3284 | These states are the allowed values of the ``State`` parameter of the |
3285 | pragma. The ``Name`` parameter is a value of the type | |
3286 | ``Ada.Interrupts.Interrupt_ID``. Typically, it is a name declared in | |
3287 | ``Ada.Interrupts.Names``. | |
bf5dffd3 | 3288 | |
3289 | This is a configuration pragma, and the binder will check that there | |
3290 | are no inconsistencies between different units in a partition in how a | |
3291 | given interrupt is specified. It may appear anywhere a pragma is legal. | |
3292 | ||
3293 | The effect is to move the interrupt to the specified state. | |
3294 | ||
3295 | By declaring interrupts to be SYSTEM, you guarantee the standard system | |
3296 | action, such as a core dump. | |
3297 | ||
3298 | By declaring interrupts to be USER, you guarantee that you can install | |
3299 | a handler. | |
3300 | ||
3301 | Note that certain signals on many operating systems cannot be caught and | |
3302 | handled by applications. In such cases, the pragma is ignored. See the | |
e94434ba | 3303 | operating system documentation, or the value of the array ``Reserved`` |
3304 | declared in the spec of package ``System.OS_Interface``. | |
bf5dffd3 | 3305 | |
3306 | Overriding the default state of signals used by the Ada runtime may interfere | |
3307 | with an application's runtime behavior in the cases of the synchronous signals, | |
e94434ba | 3308 | and in the case of the signal used to implement the ``abort`` statement. |
bf5dffd3 | 3309 | |
39adf1e6 | 3310 | .. _Pragma-Invariant: |
3311 | ||
bf5dffd3 | 3312 | Pragma Invariant |
3313 | ================ | |
3314 | ||
3315 | Syntax: | |
3316 | ||
3317 | ||
3318 | :: | |
3319 | ||
3320 | pragma Invariant | |
3321 | ([Entity =>] private_type_LOCAL_NAME, | |
3322 | [Check =>] EXPRESSION | |
3323 | [,[Message =>] String_Expression]); | |
3324 | ||
3325 | ||
3326 | This pragma provides exactly the same capabilities as the Type_Invariant aspect | |
3327 | defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The | |
3328 | Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it | |
3329 | requires the use of the aspect syntax, which is not available except in 2012 | |
3330 | mode, it is not possible to use the Type_Invariant aspect in earlier versions | |
3331 | of Ada. However the Invariant pragma may be used in any version of Ada. Also | |
3332 | note that the aspect Invariant is a synonym in GNAT for the aspect | |
3333 | Type_Invariant, but there is no pragma Type_Invariant. | |
3334 | ||
3335 | The pragma must appear within the visible part of the package specification, | |
3336 | after the type to which its Entity argument appears. As with the Invariant | |
3337 | aspect, the Check expression is not analyzed until the end of the visible | |
3338 | part of the package, so it may contain forward references. The Message | |
3339 | argument, if present, provides the exception message used if the invariant | |
3340 | is violated. If no Message parameter is provided, a default message that | |
3341 | identifies the line on which the pragma appears is used. | |
3342 | ||
3343 | It is permissible to have multiple Invariants for the same type entity, in | |
3344 | which case they are and'ed together. It is permissible to use this pragma | |
3345 | in Ada 2012 mode, but you cannot have both an invariant aspect and an | |
3346 | invariant pragma for the same entity. | |
3347 | ||
3348 | For further details on the use of this pragma, see the Ada 2012 documentation | |
3349 | of the Type_Invariant aspect. | |
3350 | ||
bf5dffd3 | 3351 | Pragma Keep_Names |
3352 | ================= | |
3353 | ||
3354 | Syntax: | |
3355 | ||
3356 | ||
3357 | :: | |
3358 | ||
3359 | pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME); | |
3360 | ||
3361 | ||
e94434ba | 3362 | The ``LOCAL_NAME`` argument |
bf5dffd3 | 3363 | must refer to an enumeration first subtype |
3364 | in the current declarative part. The effect is to retain the enumeration | |
e94434ba | 3365 | literal names for use by ``Image`` and ``Value`` even if a global |
3366 | ``Discard_Names`` pragma applies. This is useful when you want to | |
bf5dffd3 | 3367 | generally suppress enumeration literal names and for example you therefore |
e94434ba | 3368 | use a ``Discard_Names`` pragma in the :file:`gnat.adc` file, but you |
bf5dffd3 | 3369 | want to retain the names for specific enumeration types. |
3370 | ||
3371 | Pragma License | |
3372 | ============== | |
3373 | .. index:: License checking | |
3374 | ||
3375 | Syntax: | |
3376 | ||
3377 | ||
3378 | .. code-block:: ada | |
3379 | ||
3380 | pragma License (Unrestricted | GPL | Modified_GPL | Restricted); | |
3381 | ||
3382 | ||
3383 | This pragma is provided to allow automated checking for appropriate license | |
3384 | conditions with respect to the standard and modified GPL. A pragma | |
e94434ba | 3385 | ``License``, which is a configuration pragma that typically appears at |
bf5dffd3 | 3386 | the start of a source file or in a separate :file:`gnat.adc` file, specifies |
3387 | the licensing conditions of a unit as follows: | |
3388 | ||
3389 | * Unrestricted | |
3390 | This is used for a unit that can be freely used with no license restrictions. | |
3391 | Examples of such units are public domain units, and units from the Ada | |
3392 | Reference Manual. | |
3393 | ||
3394 | * GPL | |
3395 | This is used for a unit that is licensed under the unmodified GPL, and which | |
e94434ba | 3396 | therefore cannot be ``with``\ ed by a restricted unit. |
bf5dffd3 | 3397 | |
3398 | * Modified_GPL | |
3399 | This is used for a unit licensed under the GNAT modified GPL that includes | |
3400 | a special exception paragraph that specifically permits the inclusion of | |
3401 | the unit in programs without requiring the entire program to be released | |
3402 | under the GPL. | |
3403 | ||
3404 | * Restricted | |
3405 | This is used for a unit that is restricted in that it is not permitted to | |
3406 | depend on units that are licensed under the GPL. Typical examples are | |
3407 | proprietary code that is to be released under more restrictive license | |
e94434ba | 3408 | conditions. Note that restricted units are permitted to ``with`` units |
bf5dffd3 | 3409 | which are licensed under the modified GPL (this is the whole point of the |
3410 | modified GPL). | |
3411 | ||
3412 | ||
e94434ba | 3413 | Normally a unit with no ``License`` pragma is considered to have an |
bf5dffd3 | 3414 | unknown license, and no checking is done. However, standard GNAT headers |
3415 | are recognized, and license information is derived from them as follows. | |
3416 | ||
3417 | A GNAT license header starts with a line containing 78 hyphens. The following | |
3418 | comment text is searched for the appearance of any of the following strings. | |
3419 | ||
3420 | If the string 'GNU General Public License' is found, then the unit is assumed | |
3421 | to have GPL license, unless the string 'As a special exception' follows, in | |
3422 | which case the license is assumed to be modified GPL. | |
3423 | ||
3424 | If one of the strings | |
3425 | 'This specification is adapted from the Ada Semantic Interface' or | |
3426 | 'This specification is derived from the Ada Reference Manual' is found | |
3427 | then the unit is assumed to be unrestricted. | |
3428 | ||
3429 | These default actions means that a program with a restricted license pragma | |
3430 | will automatically get warnings if a GPL unit is inappropriately | |
e94434ba | 3431 | ``with``\ ed. For example, the program: |
bf5dffd3 | 3432 | |
3433 | .. code-block:: ada | |
3434 | ||
3435 | with Sem_Ch3; | |
3436 | with GNAT.Sockets; | |
3437 | procedure Secret_Stuff is | |
3438 | ... | |
3439 | end Secret_Stuff | |
3440 | ||
3441 | ||
e94434ba | 3442 | if compiled with pragma ``License`` (``Restricted``) in a |
bf5dffd3 | 3443 | :file:`gnat.adc` file will generate the warning:: |
3444 | ||
3445 | 1. with Sem_Ch3; | |
3446 | | | |
3447 | >>> license of withed unit "Sem_Ch3" is incompatible | |
3448 | ||
3449 | 2. with GNAT.Sockets; | |
3450 | 3. procedure Secret_Stuff is | |
3451 | ||
3452 | ||
e94434ba | 3453 | Here we get a warning on ``Sem_Ch3`` since it is part of the GNAT |
bf5dffd3 | 3454 | compiler and is licensed under the |
e94434ba | 3455 | GPL, but no warning for ``GNAT.Sockets`` which is part of the GNAT |
bf5dffd3 | 3456 | run time, and is therefore licensed under the modified GPL. |
3457 | ||
3458 | Pragma Link_With | |
3459 | ================ | |
3460 | ||
3461 | Syntax: | |
3462 | ||
3463 | ||
3464 | :: | |
3465 | ||
3466 | pragma Link_With (static_string_EXPRESSION {,static_string_EXPRESSION}); | |
3467 | ||
3468 | ||
3469 | This pragma is provided for compatibility with certain Ada 83 compilers. | |
e94434ba | 3470 | It has exactly the same effect as pragma ``Linker_Options`` except |
bf5dffd3 | 3471 | that spaces occurring within one of the string expressions are treated |
3472 | as separators. For example, in the following case: | |
3473 | ||
3474 | .. code-block:: ada | |
3475 | ||
3476 | pragma Link_With ("-labc -ldef"); | |
3477 | ||
3478 | ||
e94434ba | 3479 | results in passing the strings ``-labc`` and ``-ldef`` as two |
bf5dffd3 | 3480 | separate arguments to the linker. In addition pragma Link_With allows |
3481 | multiple arguments, with the same effect as successive pragmas. | |
3482 | ||
3483 | Pragma Linker_Alias | |
3484 | =================== | |
3485 | ||
3486 | Syntax: | |
3487 | ||
3488 | ||
3489 | :: | |
3490 | ||
3491 | pragma Linker_Alias ( | |
3492 | [Entity =>] LOCAL_NAME, | |
3493 | [Target =>] static_string_EXPRESSION); | |
3494 | ||
3495 | ||
e94434ba | 3496 | ``LOCAL_NAME`` must refer to an object that is declared at the library |
bf5dffd3 | 3497 | level. This pragma establishes the given entity as a linker alias for the |
e94434ba | 3498 | given target. It is equivalent to ``__attribute__((alias))`` in GNU C |
3499 | and causes ``LOCAL_NAME`` to be emitted as an alias for the symbol | |
3500 | ``static_string_EXPRESSION`` in the object file, that is to say no space | |
3501 | is reserved for ``LOCAL_NAME`` by the assembler and it will be resolved | |
3502 | to the same address as ``static_string_EXPRESSION`` by the linker. | |
bf5dffd3 | 3503 | |
3504 | The actual linker name for the target must be used (e.g., the fully | |
3505 | encoded name with qualification in Ada, or the mangled name in C++), | |
e94434ba | 3506 | or it must be declared using the C convention with ``pragma Import`` |
3507 | or ``pragma Export``. | |
bf5dffd3 | 3508 | |
3509 | Not all target machines support this pragma. On some of them it is accepted | |
e94434ba | 3510 | only if ``pragma Weak_External`` has been applied to ``LOCAL_NAME``. |
bf5dffd3 | 3511 | |
3512 | ||
3513 | .. code-block:: ada | |
3514 | ||
3515 | -- Example of the use of pragma Linker_Alias | |
3516 | ||
3517 | package p is | |
3518 | i : Integer := 1; | |
3519 | pragma Export (C, i); | |
3520 | ||
3521 | new_name_for_i : Integer; | |
3522 | pragma Linker_Alias (new_name_for_i, "i"); | |
3523 | end p; | |
3524 | ||
3525 | ||
3526 | Pragma Linker_Constructor | |
3527 | ========================= | |
3528 | ||
3529 | Syntax: | |
3530 | ||
3531 | ||
3532 | .. code-block:: ada | |
3533 | ||
3534 | pragma Linker_Constructor (procedure_LOCAL_NAME); | |
3535 | ||
3536 | ||
e94434ba | 3537 | ``procedure_LOCAL_NAME`` must refer to a parameterless procedure that |
bf5dffd3 | 3538 | is declared at the library level. A procedure to which this pragma is |
3539 | applied will be treated as an initialization routine by the linker. | |
e94434ba | 3540 | It is equivalent to ``__attribute__((constructor))`` in GNU C and |
3541 | causes ``procedure_LOCAL_NAME`` to be invoked before the entry point | |
bf5dffd3 | 3542 | of the executable is called (or immediately after the shared library is |
3543 | loaded if the procedure is linked in a shared library), in particular | |
3544 | before the Ada run-time environment is set up. | |
3545 | ||
3546 | Because of these specific contexts, the set of operations such a procedure | |
3547 | can perform is very limited and the type of objects it can manipulate is | |
3548 | essentially restricted to the elementary types. In particular, it must only | |
3549 | contain code to which pragma Restrictions (No_Elaboration_Code) applies. | |
3550 | ||
3551 | This pragma is used by GNAT to implement auto-initialization of shared Stand | |
3552 | Alone Libraries, which provides a related capability without the restrictions | |
3553 | listed above. Where possible, the use of Stand Alone Libraries is preferable | |
3554 | to the use of this pragma. | |
3555 | ||
3556 | Pragma Linker_Destructor | |
3557 | ======================== | |
3558 | ||
3559 | Syntax: | |
3560 | ||
3561 | ||
3562 | .. code-block:: ada | |
3563 | ||
3564 | pragma Linker_Destructor (procedure_LOCAL_NAME); | |
3565 | ||
3566 | ||
e94434ba | 3567 | ``procedure_LOCAL_NAME`` must refer to a parameterless procedure that |
bf5dffd3 | 3568 | is declared at the library level. A procedure to which this pragma is |
3569 | applied will be treated as a finalization routine by the linker. | |
e94434ba | 3570 | It is equivalent to ``__attribute__((destructor))`` in GNU C and |
3571 | causes ``procedure_LOCAL_NAME`` to be invoked after the entry point | |
bf5dffd3 | 3572 | of the executable has exited (or immediately before the shared library |
3573 | is unloaded if the procedure is linked in a shared library), in particular | |
3574 | after the Ada run-time environment is shut down. | |
3575 | ||
e94434ba | 3576 | See ``pragma Linker_Constructor`` for the set of restrictions that apply |
bf5dffd3 | 3577 | because of these specific contexts. |
3578 | ||
39adf1e6 | 3579 | .. _Pragma-Linker_Section: |
3580 | ||
bf5dffd3 | 3581 | Pragma Linker_Section |
3582 | ===================== | |
3583 | ||
3584 | Syntax: | |
3585 | ||
3586 | ||
3587 | :: | |
3588 | ||
3589 | pragma Linker_Section ( | |
3590 | [Entity =>] LOCAL_NAME, | |
3591 | [Section =>] static_string_EXPRESSION); | |
3592 | ||
3593 | ||
e94434ba | 3594 | ``LOCAL_NAME`` must refer to an object, type, or subprogram that is |
bf5dffd3 | 3595 | declared at the library level. This pragma specifies the name of the |
3596 | linker section for the given entity. It is equivalent to | |
e94434ba | 3597 | ``__attribute__((section))`` in GNU C and causes ``LOCAL_NAME`` to |
3598 | be placed in the ``static_string_EXPRESSION`` section of the | |
bf5dffd3 | 3599 | executable (assuming the linker doesn't rename the section). |
3600 | GNAT also provides an implementation defined aspect of the same name. | |
3601 | ||
3602 | In the case of specifying this aspect for a type, the effect is to | |
e94434ba | 3603 | specify the corresponding section for all library-level objects of |
3604 | the type that do not have an explicit linker section set. Note that | |
3605 | this only applies to whole objects, not to components of composite objects. | |
bf5dffd3 | 3606 | |
3607 | In the case of a subprogram, the linker section applies to all previously | |
3608 | declared matching overloaded subprograms in the current declarative part | |
3609 | which do not already have a linker section assigned. The linker section | |
3610 | aspect is useful in this case for specifying different linker sections | |
3611 | for different elements of such an overloaded set. | |
3612 | ||
3613 | Note that an empty string specifies that no linker section is specified. | |
3614 | This is not quite the same as omitting the pragma or aspect, since it | |
3615 | can be used to specify that one element of an overloaded set of subprograms | |
3616 | has the default linker section, or that one object of a type for which a | |
3617 | linker section is specified should has the default linker section. | |
3618 | ||
3619 | The compiler normally places library-level entities in standard sections | |
3620 | depending on the class: procedures and functions generally go in the | |
e94434ba | 3621 | ``.text`` section, initialized variables in the ``.data`` section |
3622 | and uninitialized variables in the ``.bss`` section. | |
bf5dffd3 | 3623 | |
3624 | Other, special sections may exist on given target machines to map special | |
3625 | hardware, for example I/O ports or flash memory. This pragma is a means to | |
3626 | defer the final layout of the executable to the linker, thus fully working | |
3627 | at the symbolic level with the compiler. | |
3628 | ||
3629 | Some file formats do not support arbitrary sections so not all target | |
3630 | machines support this pragma. The use of this pragma may cause a program | |
3631 | execution to be erroneous if it is used to place an entity into an | |
e94434ba | 3632 | inappropriate section (e.g., a modified variable into the ``.text`` |
3633 | section). See also ``pragma Persistent_BSS``. | |
bf5dffd3 | 3634 | |
3635 | ||
3636 | .. code-block:: ada | |
3637 | ||
3638 | -- Example of the use of pragma Linker_Section | |
3639 | ||
3640 | package IO_Card is | |
3641 | Port_A : Integer; | |
3642 | pragma Volatile (Port_A); | |
3643 | pragma Linker_Section (Port_A, ".bss.port_a"); | |
3644 | ||
3645 | Port_B : Integer; | |
3646 | pragma Volatile (Port_B); | |
3647 | pragma Linker_Section (Port_B, ".bss.port_b"); | |
3648 | ||
3649 | type Port_Type is new Integer with Linker_Section => ".bss"; | |
3650 | PA : Port_Type with Linker_Section => ".bss.PA"; | |
3651 | PB : Port_Type; -- ends up in linker section ".bss" | |
3652 | ||
3653 | procedure Q with Linker_Section => "Qsection"; | |
3654 | end IO_Card; | |
3655 | ||
39adf1e6 | 3656 | .. _Pragma-Lock_Free: |
bf5dffd3 | 3657 | |
3658 | Pragma Lock_Free | |
3659 | ================ | |
3660 | ||
3661 | Syntax: | |
3662 | This pragma may be specified for protected types or objects. It specifies that | |
3663 | the implementation of protected operations must be implemented without locks. | |
3664 | Compilation fails if the compiler cannot generate lock-free code for the | |
3665 | operations. | |
3666 | ||
c8c25b3d | 3667 | The current conditions required to support this pragma are: |
3668 | ||
3669 | * Protected type declarations may not contain entries | |
3670 | * Protected subprogram declarations may not have nonelementary parameters | |
3671 | ||
3672 | In addition, each protected subprogram body must satisfy: | |
3673 | ||
3674 | * May reference only one protected component | |
3675 | * May not reference nonconstant entities outside the protected subprogram | |
3676 | scope. | |
3677 | * May not contain address representation items, allocators, or quantified | |
3678 | expressions. | |
3679 | * May not contain delay, goto, loop, or procedure-call statements. | |
3680 | * May not contain exported and imported entities | |
3681 | * May not dereferenced access values | |
3682 | * Function calls and attribute references must be static | |
3683 | ||
3684 | ||
bf5dffd3 | 3685 | Pragma Loop_Invariant |
3686 | ===================== | |
3687 | ||
3688 | Syntax: | |
3689 | ||
3690 | ||
3691 | .. code-block:: ada | |
3692 | ||
3693 | pragma Loop_Invariant ( boolean_EXPRESSION ); | |
3694 | ||
3695 | ||
e94434ba | 3696 | The effect of this pragma is similar to that of pragma ``Assert``, |
3697 | except that in an ``Assertion_Policy`` pragma, the identifier | |
3698 | ``Loop_Invariant`` is used to control whether it is ignored or checked | |
bf5dffd3 | 3699 | (or disabled). |
3700 | ||
e94434ba | 3701 | ``Loop_Invariant`` can only appear as one of the items in the sequence |
bf5dffd3 | 3702 | of statements of a loop body, or nested inside block statements that |
3703 | appear in the sequence of statements of a loop body. | |
3704 | The intention is that it be used to | |
3705 | represent a "loop invariant" assertion, i.e. something that is true each | |
3706 | time through the loop, and which can be used to show that the loop is | |
3707 | achieving its purpose. | |
3708 | ||
e94434ba | 3709 | Multiple ``Loop_Invariant`` and ``Loop_Variant`` pragmas that |
bf5dffd3 | 3710 | apply to the same loop should be grouped in the same sequence of |
3711 | statements. | |
3712 | ||
e94434ba | 3713 | To aid in writing such invariants, the special attribute ``Loop_Entry`` |
bf5dffd3 | 3714 | may be used to refer to the value of an expression on entry to the loop. This |
e94434ba | 3715 | attribute can only be used within the expression of a ``Loop_Invariant`` |
3716 | pragma. For full details, see documentation of attribute ``Loop_Entry``. | |
bf5dffd3 | 3717 | |
3718 | Pragma Loop_Optimize | |
3719 | ==================== | |
3720 | ||
3721 | Syntax: | |
3722 | ||
3723 | ||
3724 | :: | |
3725 | ||
3726 | pragma Loop_Optimize (OPTIMIZATION_HINT {, OPTIMIZATION_HINT}); | |
3727 | ||
3728 | OPTIMIZATION_HINT ::= Ivdep | No_Unroll | Unroll | No_Vector | Vector | |
3729 | ||
3730 | ||
3731 | This pragma must appear immediately within a loop statement. It allows the | |
3732 | programmer to specify optimization hints for the enclosing loop. The hints | |
3733 | are not mutually exclusive and can be freely mixed, but not all combinations | |
3734 | will yield a sensible outcome. | |
3735 | ||
3736 | There are five supported optimization hints for a loop: | |
3737 | ||
3738 | * Ivdep | |
3739 | ||
3740 | The programmer asserts that there are no loop-carried dependencies | |
3741 | which would prevent consecutive iterations of the loop from being | |
3742 | executed simultaneously. | |
3743 | ||
3744 | * No_Unroll | |
3745 | ||
3746 | The loop must not be unrolled. This is a strong hint: the compiler will not | |
3747 | unroll a loop marked with this hint. | |
3748 | ||
3749 | * Unroll | |
3750 | ||
3751 | The loop should be unrolled. This is a weak hint: the compiler will try to | |
3752 | apply unrolling to this loop preferably to other optimizations, notably | |
3753 | vectorization, but there is no guarantee that the loop will be unrolled. | |
3754 | ||
3755 | * No_Vector | |
3756 | ||
3757 | The loop must not be vectorized. This is a strong hint: the compiler will not | |
3758 | vectorize a loop marked with this hint. | |
3759 | ||
3760 | * Vector | |
3761 | ||
3762 | The loop should be vectorized. This is a weak hint: the compiler will try to | |
3763 | apply vectorization to this loop preferably to other optimizations, notably | |
3764 | unrolling, but there is no guarantee that the loop will be vectorized. | |
3765 | ||
3766 | ||
3767 | These hints do not remove the need to pass the appropriate switches to the | |
3768 | compiler in order to enable the relevant optimizations, that is to say | |
3769 | *-funroll-loops* for unrolling and *-ftree-vectorize* for | |
3770 | vectorization. | |
3771 | ||
3772 | Pragma Loop_Variant | |
3773 | =================== | |
3774 | ||
3775 | Syntax: | |
3776 | ||
3777 | ||
3778 | :: | |
3779 | ||
3780 | pragma Loop_Variant ( LOOP_VARIANT_ITEM {, LOOP_VARIANT_ITEM } ); | |
3781 | LOOP_VARIANT_ITEM ::= CHANGE_DIRECTION => discrete_EXPRESSION | |
3782 | CHANGE_DIRECTION ::= Increases | Decreases | |
3783 | ||
3784 | ||
e94434ba | 3785 | ``Loop_Variant`` can only appear as one of the items in the sequence |
bf5dffd3 | 3786 | of statements of a loop body, or nested inside block statements that |
3787 | appear in the sequence of statements of a loop body. | |
3788 | It allows the specification of quantities which must always | |
3789 | decrease or increase in successive iterations of the loop. In its simplest | |
3790 | form, just one expression is specified, whose value must increase or decrease | |
3791 | on each iteration of the loop. | |
3792 | ||
3793 | In a more complex form, multiple arguments can be given which are intepreted | |
3794 | in a nesting lexicographic manner. For example: | |
3795 | ||
3796 | .. code-block:: ada | |
3797 | ||
3798 | pragma Loop_Variant (Increases => X, Decreases => Y); | |
3799 | ||
3800 | ||
3801 | specifies that each time through the loop either X increases, or X stays | |
e94434ba | 3802 | the same and Y decreases. A ``Loop_Variant`` pragma ensures that the |
bf5dffd3 | 3803 | loop is making progress. It can be useful in helping to show informally |
3804 | or prove formally that the loop always terminates. | |
3805 | ||
e94434ba | 3806 | ``Loop_Variant`` is an assertion whose effect can be controlled using |
3807 | an ``Assertion_Policy`` with a check name of ``Loop_Variant``. The | |
3808 | policy can be ``Check`` to enable the loop variant check, ``Ignore`` | |
bf5dffd3 | 3809 | to ignore the check (in which case the pragma has no effect on the program), |
e94434ba | 3810 | or ``Disable`` in which case the pragma is not even checked for correct |
bf5dffd3 | 3811 | syntax. |
3812 | ||
e94434ba | 3813 | Multiple ``Loop_Invariant`` and ``Loop_Variant`` pragmas that |
bf5dffd3 | 3814 | apply to the same loop should be grouped in the same sequence of |
3815 | statements. | |
3816 | ||
e94434ba | 3817 | The ``Loop_Entry`` attribute may be used within the expressions of the |
3818 | ``Loop_Variant`` pragma to refer to values on entry to the loop. | |
bf5dffd3 | 3819 | |
3820 | Pragma Machine_Attribute | |
3821 | ======================== | |
3822 | ||
3823 | Syntax: | |
3824 | ||
3825 | ||
3826 | :: | |
3827 | ||
3828 | pragma Machine_Attribute ( | |
3829 | [Entity =>] LOCAL_NAME, | |
3830 | [Attribute_Name =>] static_string_EXPRESSION | |
c8956236 | 3831 | [, [Info =>] static_EXPRESSION {, static_EXPRESSION}] ); |
bf5dffd3 | 3832 | |
3833 | ||
3834 | Machine-dependent attributes can be specified for types and/or | |
3835 | declarations. This pragma is semantically equivalent to | |
e94434ba | 3836 | :samp:`__attribute__(({attribute_name}))` (if ``info`` is not |
3837 | specified) or :samp:`__attribute__(({attribute_name(info})))` | |
c8956236 | 3838 | or :samp:`__attribute__(({attribute_name(info,...})))` in GNU C, |
3839 | where *attribute_name* is recognized by the compiler middle-end | |
3840 | or the ``TARGET_ATTRIBUTE_TABLE`` machine specific macro. Note | |
3841 | that a string literal for the optional parameter ``info`` or the | |
3842 | following ones is transformed by default into an identifier, | |
3843 | which may make this pragma unusable for some attributes. | |
bf5dffd3 | 3844 | For further information see :title:`GNU Compiler Collection (GCC) Internals`. |
3845 | ||
3846 | Pragma Main | |
3847 | =========== | |
3848 | ||
3849 | Syntax:: | |
3850 | ||
3851 | pragma Main | |
3852 | (MAIN_OPTION [, MAIN_OPTION]); | |
3853 | ||
3854 | MAIN_OPTION ::= | |
3855 | [Stack_Size =>] static_integer_EXPRESSION | |
3856 | | [Task_Stack_Size_Default =>] static_integer_EXPRESSION | |
3857 | | [Time_Slicing_Enabled =>] static_boolean_EXPRESSION | |
3858 | ||
3859 | ||
3860 | This pragma is provided for compatibility with OpenVMS VAX Systems. It has | |
3861 | no effect in GNAT, other than being syntax checked. | |
3862 | ||
3863 | Pragma Main_Storage | |
3864 | =================== | |
3865 | ||
3866 | Syntax:: | |
3867 | ||
3868 | pragma Main_Storage | |
3869 | (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); | |
3870 | ||
3871 | MAIN_STORAGE_OPTION ::= | |
3872 | [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION | |
3873 | | [TOP_GUARD =>] static_SIMPLE_EXPRESSION | |
3874 | ||
3875 | ||
3876 | This pragma is provided for compatibility with OpenVMS VAX Systems. It has | |
3877 | no effect in GNAT, other than being syntax checked. | |
3878 | ||
e94434ba | 3879 | .. _Pragma-Max_Queue_Length: |
3880 | ||
0c01a524 | 3881 | Pragma Max_Queue_Length |
3882 | ======================= | |
3883 | ||
3884 | Syntax:: | |
3885 | ||
3886 | pragma Max_Entry_Queue (static_integer_EXPRESSION); | |
3887 | ||
3888 | ||
3889 | This pragma is used to specify the maximum callers per entry queue for | |
3890 | individual protected entries and entry families. It accepts a single | |
3891 | positive integer as a parameter and must appear after the declaration | |
3892 | of an entry. | |
3893 | ||
bf5dffd3 | 3894 | Pragma No_Body |
3895 | ============== | |
3896 | ||
3897 | Syntax: | |
3898 | ||
3899 | ||
3900 | .. code-block:: ada | |
3901 | ||
3902 | pragma No_Body; | |
3903 | ||
3904 | ||
3905 | There are a number of cases in which a package spec does not require a body, | |
3906 | and in fact a body is not permitted. GNAT will not permit the spec to be | |
3907 | compiled if there is a body around. The pragma No_Body allows you to provide | |
3908 | a body file, even in a case where no body is allowed. The body file must | |
3909 | contain only comments and a single No_Body pragma. This is recognized by | |
3910 | the compiler as indicating that no body is logically present. | |
3911 | ||
3912 | This is particularly useful during maintenance when a package is modified in | |
3913 | such a way that a body needed before is no longer needed. The provision of a | |
3914 | dummy body with a No_Body pragma ensures that there is no interference from | |
3915 | earlier versions of the package body. | |
3916 | ||
adb8ac81 | 3917 | .. _Pragma-No_Caching: |
3918 | ||
3919 | Pragma No_Caching | |
3920 | ================= | |
3921 | ||
3922 | Syntax: | |
3923 | ||
3924 | .. code-block:: ada | |
3925 | ||
3926 | pragma No_Caching [ (boolean_EXPRESSION) ]; | |
3927 | ||
3928 | For the semantics of this pragma, see the entry for aspect ``No_Caching`` in | |
3929 | the SPARK 2014 Reference Manual, section 7.1.2. | |
3930 | ||
e94434ba | 3931 | Pragma No_Component_Reordering |
3932 | ============================== | |
3933 | ||
3934 | Syntax: | |
3935 | ||
3936 | ||
3937 | :: | |
3938 | ||
3939 | pragma No_Component_Reordering [([Entity =>] type_LOCAL_NAME)]; | |
3940 | ||
3941 | ||
3942 | ``type_LOCAL_NAME`` must refer to a record type declaration in the current | |
3943 | declarative part. The effect is to preclude any reordering of components | |
3944 | for the layout of the record, i.e. the record is laid out by the compiler | |
3945 | in the order in which the components are declared textually. The form with | |
3946 | no argument is a configuration pragma which applies to all record types | |
3947 | declared in units to which the pragma applies and there is a requirement | |
3948 | that this pragma be used consistently within a partition. | |
3949 | ||
39adf1e6 | 3950 | .. _Pragma-No_Elaboration_Code_All: |
3951 | ||
bf5dffd3 | 3952 | Pragma No_Elaboration_Code_All |
3953 | ============================== | |
3954 | ||
3955 | Syntax: | |
3956 | ||
3957 | ||
3958 | :: | |
3959 | ||
3960 | pragma No_Elaboration_Code_All [(program_unit_NAME)]; | |
3961 | ||
3962 | ||
3963 | This is a program unit pragma (there is also an equivalent aspect of the | |
e94434ba | 3964 | same name) that establishes the restriction ``No_Elaboration_Code`` for |
8f09eafa | 3965 | the current unit and any extended main source units (body and subunits). |
3966 | It also has the effect of enforcing a transitive application of this | |
3967 | aspect, so that if any unit is implicitly or explicitly with'ed by the | |
bf5dffd3 | 3968 | current unit, it must also have the No_Elaboration_Code_All aspect set. |
3969 | It may be applied to package or subprogram specs or their generic versions. | |
3970 | ||
8f09eafa | 3971 | Pragma No_Heap_Finalization |
3972 | =========================== | |
3973 | ||
3974 | Syntax: | |
3975 | ||
3976 | ||
3977 | :: | |
3978 | ||
3979 | pragma No_Heap_Finalization [ (first_subtype_LOCAL_NAME) ]; | |
3980 | ||
3981 | ||
e94434ba | 3982 | Pragma ``No_Heap_Finalization`` may be used as a configuration pragma or as a |
8f09eafa | 3983 | type-specific pragma. |
3984 | ||
3985 | In its configuration form, the pragma must appear within a configuration file | |
3986 | such as gnat.adc, without an argument. The pragma suppresses the call to | |
e94434ba | 3987 | ``Finalize`` for heap-allocated objects created through library-level named |
8f09eafa | 3988 | access-to-object types in cases where the designated type requires finalization |
3989 | actions. | |
3990 | ||
3991 | In its type-specific form, the argument of the pragma must denote a | |
3992 | library-level named access-to-object type. The pragma suppresses the call to | |
e94434ba | 3993 | ``Finalize`` for heap-allocated objects created through the specific access type |
8f09eafa | 3994 | in cases where the designated type requires finalization actions. |
3995 | ||
3996 | It is still possible to finalize such heap-allocated objects by explicitly | |
3997 | deallocating them. | |
3998 | ||
3999 | A library-level named access-to-object type declared within a generic unit will | |
e94434ba | 4000 | lose its ``No_Heap_Finalization`` pragma when the corresponding instance does not |
8f09eafa | 4001 | appear at the library level. |
4002 | ||
e94434ba | 4003 | .. _Pragma-No_Inline: |
4004 | ||
bf5dffd3 | 4005 | Pragma No_Inline |
4006 | ================ | |
4007 | ||
4008 | Syntax: | |
4009 | ||
4010 | ||
4011 | :: | |
4012 | ||
4013 | pragma No_Inline (NAME {, NAME}); | |
4014 | ||
4015 | ||
4016 | This pragma suppresses inlining for the callable entity or the instances of | |
e94434ba | 4017 | the generic subprogram designated by ``NAME``, including inlining that |
4018 | results from the use of pragma ``Inline``. This pragma is always active, | |
bf5dffd3 | 4019 | in particular it is not subject to the use of option *-gnatn* or |
e94434ba | 4020 | *-gnatN*. It is illegal to specify both pragma ``No_Inline`` and |
4021 | pragma ``Inline_Always`` for the same ``NAME``. | |
bf5dffd3 | 4022 | |
4023 | Pragma No_Return | |
4024 | ================ | |
4025 | ||
4026 | Syntax: | |
4027 | ||
4028 | ||
4029 | :: | |
4030 | ||
4031 | pragma No_Return (procedure_LOCAL_NAME {, procedure_LOCAL_NAME}); | |
4032 | ||
4033 | ||
e94434ba | 4034 | Each ``procedure_LOCAL_NAME`` argument must refer to one or more procedure |
bf5dffd3 | 4035 | declarations in the current declarative part. A procedure to which this |
e94434ba | 4036 | pragma is applied may not contain any explicit ``return`` statements. |
bf5dffd3 | 4037 | In addition, if the procedure contains any implicit returns from falling |
4038 | off the end of a statement sequence, then execution of that implicit | |
4039 | return will cause Program_Error to be raised. | |
4040 | ||
4041 | One use of this pragma is to identify procedures whose only purpose is to raise | |
4042 | an exception. Another use of this pragma is to suppress incorrect warnings | |
4043 | about missing returns in functions, where the last statement of a function | |
4044 | statement sequence is a call to such a procedure. | |
4045 | ||
4046 | Note that in Ada 2005 mode, this pragma is part of the language. It is | |
4047 | available in all earlier versions of Ada as an implementation-defined | |
4048 | pragma. | |
4049 | ||
4050 | Pragma No_Run_Time | |
4051 | ================== | |
4052 | ||
4053 | Syntax: | |
4054 | ||
4055 | ||
4056 | .. code-block:: ada | |
4057 | ||
4058 | pragma No_Run_Time; | |
4059 | ||
4060 | ||
4061 | This is an obsolete configuration pragma that historically was used to | |
4062 | set up a runtime library with no object code. It is now used only for | |
4063 | internal testing. The pragma has been superseded by the reconfigurable | |
e94434ba | 4064 | runtime capability of GNAT. |
bf5dffd3 | 4065 | |
4066 | Pragma No_Strict_Aliasing | |
4067 | ========================= | |
4068 | ||
4069 | Syntax: | |
4070 | ||
4071 | ||
4072 | :: | |
4073 | ||
4074 | pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)]; | |
4075 | ||
4076 | ||
e94434ba | 4077 | ``type_LOCAL_NAME`` must refer to an access type |
bf5dffd3 | 4078 | declaration in the current declarative part. The effect is to inhibit |
4079 | strict aliasing optimization for the given type. The form with no | |
4080 | arguments is a configuration pragma which applies to all access types | |
4081 | declared in units to which the pragma applies. For a detailed | |
4082 | description of the strict aliasing optimization, and the situations | |
4083 | in which it must be suppressed, see the section on Optimization and Strict Aliasing | |
4084 | in the :title:`GNAT User's Guide`. | |
4085 | ||
4086 | This pragma currently has no effects on access to unconstrained array types. | |
4087 | ||
39adf1e6 | 4088 | .. _Pragma-No_Tagged_Streams: |
4089 | ||
bf5dffd3 | 4090 | Pragma No_Tagged_Streams |
4091 | ======================== | |
4092 | ||
4093 | Syntax: | |
4094 | ||
4095 | ||
4096 | :: | |
4097 | ||
bf5dffd3 | 4098 | pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)]; |
4099 | ||
4100 | ||
4101 | Normally when a tagged type is introduced using a full type declaration, | |
4102 | part of the processing includes generating stream access routines to be | |
4103 | used by stream attributes referencing the type (or one of its subtypes | |
4104 | or derived types). This can involve the generation of significant amounts | |
4105 | of code which is wasted space if stream routines are not needed for the | |
4106 | type in question. | |
4107 | ||
e94434ba | 4108 | The ``No_Tagged_Streams`` pragma causes the generation of these stream |
bf5dffd3 | 4109 | routines to be skipped, and any attempt to use stream operations on |
4110 | types subject to this pragma will be statically rejected as illegal. | |
4111 | ||
4112 | There are two forms of the pragma. The form with no arguments must appear | |
4113 | in a declarative sequence or in the declarations of a package spec. This | |
4114 | pragma affects all subsequent root tagged types declared in the declaration | |
4115 | sequence, and specifies that no stream routines be generated. The form with | |
4116 | an argument (for which there is also a corresponding aspect) specifies a | |
4117 | single root tagged type for which stream routines are not to be generated. | |
4118 | ||
4119 | Once the pragma has been given for a particular root tagged type, all subtypes | |
4120 | and derived types of this type inherit the pragma automatically, so the effect | |
4121 | applies to a complete hierarchy (this is necessary to deal with the class-wide | |
4122 | dispatching versions of the stream routines). | |
4123 | ||
cb0deab3 | 4124 | When pragmas ``Discard_Names`` and ``No_Tagged_Streams`` are simultaneously |
4125 | applied to a tagged type its Expanded_Name and External_Tag are initialized | |
4126 | with empty strings. This is useful to avoid exposing entity names at binary | |
4127 | level but has a negative impact on the debuggability of tagged types. | |
4128 | ||
bf5dffd3 | 4129 | Pragma Normalize_Scalars |
4130 | ======================== | |
4131 | ||
4132 | Syntax: | |
4133 | ||
4134 | ||
4135 | .. code-block:: ada | |
4136 | ||
4137 | pragma Normalize_Scalars; | |
4138 | ||
4139 | ||
4140 | This is a language defined pragma which is fully implemented in GNAT. The | |
4141 | effect is to cause all scalar objects that are not otherwise initialized | |
4142 | to be initialized. The initial values are implementation dependent and | |
4143 | are as follows: | |
4144 | ||
4145 | ||
4146 | ||
4147 | *Standard.Character* | |
4148 | Objects whose root type is Standard.Character are initialized to | |
4149 | Character'Last unless the subtype range excludes NUL (in which case | |
4150 | NUL is used). This choice will always generate an invalid value if | |
4151 | one exists. | |
4152 | ||
4153 | ||
4154 | *Standard.Wide_Character* | |
4155 | Objects whose root type is Standard.Wide_Character are initialized to | |
4156 | Wide_Character'Last unless the subtype range excludes NUL (in which case | |
4157 | NUL is used). This choice will always generate an invalid value if | |
4158 | one exists. | |
4159 | ||
4160 | ||
4161 | *Standard.Wide_Wide_Character* | |
4162 | Objects whose root type is Standard.Wide_Wide_Character are initialized to | |
4163 | the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in | |
4164 | which case NUL is used). This choice will always generate an invalid value if | |
4165 | one exists. | |
4166 | ||
4167 | ||
4168 | *Integer types* | |
4169 | Objects of an integer type are treated differently depending on whether | |
4170 | negative values are present in the subtype. If no negative values are | |
4171 | present, then all one bits is used as the initial value except in the | |
4172 | special case where zero is excluded from the subtype, in which case | |
4173 | all zero bits are used. This choice will always generate an invalid | |
4174 | value if one exists. | |
4175 | ||
4176 | For subtypes with negative values present, the largest negative number | |
4177 | is used, except in the unusual case where this largest negative number | |
4178 | is in the subtype, and the largest positive number is not, in which case | |
4179 | the largest positive value is used. This choice will always generate | |
4180 | an invalid value if one exists. | |
4181 | ||
4182 | ||
4183 | *Floating-Point Types* | |
4184 | Objects of all floating-point types are initialized to all 1-bits. For | |
4185 | standard IEEE format, this corresponds to a NaN (not a number) which is | |
4186 | indeed an invalid value. | |
4187 | ||
4188 | ||
4189 | *Fixed-Point Types* | |
4190 | Objects of all fixed-point types are treated as described above for integers, | |
4191 | with the rules applying to the underlying integer value used to represent | |
4192 | the fixed-point value. | |
4193 | ||
4194 | ||
4195 | *Modular types* | |
4196 | Objects of a modular type are initialized to all one bits, except in | |
4197 | the special case where zero is excluded from the subtype, in which | |
4198 | case all zero bits are used. This choice will always generate an | |
4199 | invalid value if one exists. | |
4200 | ||
4201 | ||
4202 | *Enumeration types* | |
4203 | Objects of an enumeration type are initialized to all one-bits, i.e., to | |
e94434ba | 4204 | the value ``2 ** typ'Size - 1`` unless the subtype excludes the literal |
bf5dffd3 | 4205 | whose Pos value is zero, in which case a code of zero is used. This choice |
4206 | will always generate an invalid value if one exists. | |
4207 | ||
4208 | .. _Pragma_Obsolescent: | |
4209 | ||
4210 | Pragma Obsolescent | |
4211 | ================== | |
4212 | ||
4213 | Syntax: | |
4214 | ||
4215 | ||
4216 | :: | |
4217 | ||
4218 | pragma Obsolescent; | |
4219 | ||
4220 | pragma Obsolescent ( | |
4221 | [Message =>] static_string_EXPRESSION | |
4222 | [,[Version =>] Ada_05]]); | |
4223 | ||
4224 | pragma Obsolescent ( | |
4225 | [Entity =>] NAME | |
4226 | [,[Message =>] static_string_EXPRESSION | |
4227 | [,[Version =>] Ada_05]] ); | |
4228 | ||
4229 | ||
4230 | This pragma can occur immediately following a declaration of an entity, | |
4231 | including the case of a record component. If no Entity argument is present, | |
4232 | then this declaration is the one to which the pragma applies. If an Entity | |
4233 | parameter is present, it must either match the name of the entity in this | |
4234 | declaration, or alternatively, the pragma can immediately follow an enumeration | |
4235 | type declaration, where the Entity argument names one of the enumeration | |
4236 | literals. | |
4237 | ||
4238 | This pragma is used to indicate that the named entity | |
4239 | is considered obsolescent and should not be used. Typically this is | |
4240 | used when an API must be modified by eventually removing or modifying | |
4241 | existing subprograms or other entities. The pragma can be used at an | |
4242 | intermediate stage when the entity is still present, but will be | |
4243 | removed later. | |
4244 | ||
4245 | The effect of this pragma is to output a warning message on a reference to | |
4246 | an entity thus marked that the subprogram is obsolescent if the appropriate | |
e94434ba | 4247 | warning option in the compiler is activated. If the ``Message`` parameter is |
bf5dffd3 | 4248 | present, then a second warning message is given containing this text. In |
4249 | addition, a reference to the entity is considered to be a violation of pragma | |
e94434ba | 4250 | ``Restrictions (No_Obsolescent_Features)``. |
bf5dffd3 | 4251 | |
4252 | This pragma can also be used as a program unit pragma for a package, | |
4253 | in which case the entity name is the name of the package, and the | |
4254 | pragma indicates that the entire package is considered | |
e94434ba | 4255 | obsolescent. In this case a client ``with``\ ing such a package |
4256 | violates the restriction, and the ``with`` clause is | |
bf5dffd3 | 4257 | flagged with warnings if the warning option is set. |
4258 | ||
e94434ba | 4259 | If the ``Version`` parameter is present (which must be exactly |
4260 | the identifier ``Ada_05``, no other argument is allowed), then the | |
bf5dffd3 | 4261 | indication of obsolescence applies only when compiling in Ada 2005 |
4262 | mode. This is primarily intended for dealing with the situations | |
4263 | in the predefined library where subprograms or packages | |
4264 | have become defined as obsolescent in Ada 2005 | |
e94434ba | 4265 | (e.g., in ``Ada.Characters.Handling``), but may be used anywhere. |
bf5dffd3 | 4266 | |
4267 | The following examples show typical uses of this pragma: | |
4268 | ||
4269 | ||
4270 | .. code-block:: ada | |
4271 | ||
4272 | package p is | |
4273 | pragma Obsolescent (p, Message => "use pp instead of p"); | |
4274 | end p; | |
4275 | ||
4276 | package q is | |
4277 | procedure q2; | |
4278 | pragma Obsolescent ("use q2new instead"); | |
4279 | ||
4280 | type R is new integer; | |
4281 | pragma Obsolescent | |
4282 | (Entity => R, | |
4283 | Message => "use RR in Ada 2005", | |
4284 | Version => Ada_05); | |
4285 | ||
4286 | type M is record | |
4287 | F1 : Integer; | |
4288 | F2 : Integer; | |
4289 | pragma Obsolescent; | |
4290 | F3 : Integer; | |
4291 | end record; | |
4292 | ||
4293 | type E is (a, bc, 'd', quack); | |
4294 | pragma Obsolescent (Entity => bc) | |
4295 | pragma Obsolescent (Entity => 'd') | |
4296 | ||
4297 | function "+" | |
4298 | (a, b : character) return character; | |
4299 | pragma Obsolescent (Entity => "+"); | |
4300 | end; | |
4301 | ||
4302 | ||
4303 | Note that, as for all pragmas, if you use a pragma argument identifier, | |
4304 | then all subsequent parameters must also use a pragma argument identifier. | |
e94434ba | 4305 | So if you specify ``Entity =>`` for the ``Entity`` argument, and a ``Message`` |
4306 | argument is present, it must be preceded by ``Message =>``. | |
bf5dffd3 | 4307 | |
4308 | Pragma Optimize_Alignment | |
4309 | ========================= | |
4310 | .. index:: Alignment, default settings | |
4311 | ||
4312 | Syntax: | |
4313 | ||
4314 | ||
4315 | .. code-block:: ada | |
4316 | ||
4317 | pragma Optimize_Alignment (TIME | SPACE | OFF); | |
4318 | ||
4319 | ||
4320 | This is a configuration pragma which affects the choice of default alignments | |
4321 | for types and objects where no alignment is explicitly specified. There is a | |
4322 | time/space trade-off in the selection of these values. Large alignments result | |
4323 | in more efficient code, at the expense of larger data space, since sizes have | |
4324 | to be increased to match these alignments. Smaller alignments save space, but | |
4325 | the access code is slower. The normal choice of default alignments for types | |
4326 | and individual alignment promotions for objects (which is what you get if you | |
4327 | do not use this pragma, or if you use an argument of OFF), tries to balance | |
4328 | these two requirements. | |
4329 | ||
4330 | Specifying SPACE causes smaller default alignments to be chosen in two cases. | |
4331 | First any packed record is given an alignment of 1. Second, if a size is given | |
4332 | for the type, then the alignment is chosen to avoid increasing this size. For | |
4333 | example, consider: | |
4334 | ||
4335 | ||
4336 | .. code-block:: ada | |
4337 | ||
4338 | type R is record | |
4339 | X : Integer; | |
4340 | Y : Character; | |
4341 | end record; | |
4342 | ||
4343 | for R'Size use 5*8; | |
4344 | ||
4345 | ||
4346 | In the default mode, this type gets an alignment of 4, so that access to the | |
4347 | Integer field X are efficient. But this means that objects of the type end up | |
4348 | with a size of 8 bytes. This is a valid choice, since sizes of objects are | |
4349 | allowed to be bigger than the size of the type, but it can waste space if for | |
4350 | example fields of type R appear in an enclosing record. If the above type is | |
e94434ba | 4351 | compiled in ``Optimize_Alignment (Space)`` mode, the alignment is set to 1. |
bf5dffd3 | 4352 | |
4353 | However, there is one case in which SPACE is ignored. If a variable length | |
4354 | record (that is a discriminated record with a component which is an array | |
4355 | whose length depends on a discriminant), has a pragma Pack, then it is not | |
4356 | in general possible to set the alignment of such a record to one, so the | |
4357 | pragma is ignored in this case (with a warning). | |
4358 | ||
4359 | Specifying SPACE also disables alignment promotions for standalone objects, | |
4360 | which occur when the compiler increases the alignment of a specific object | |
4361 | without changing the alignment of its type. | |
4362 | ||
2ac7a5c9 | 4363 | Specifying SPACE also disables component reordering in unpacked record types, |
4364 | which can result in larger sizes in order to meet alignment requirements. | |
4365 | ||
bf5dffd3 | 4366 | Specifying TIME causes larger default alignments to be chosen in the case of |
4367 | small types with sizes that are not a power of 2. For example, consider: | |
4368 | ||
4369 | ||
4370 | .. code-block:: ada | |
4371 | ||
4372 | type R is record | |
4373 | A : Character; | |
4374 | B : Character; | |
4375 | C : Boolean; | |
4376 | end record; | |
4377 | ||
4378 | pragma Pack (R); | |
4379 | for R'Size use 17; | |
4380 | ||
4381 | ||
4382 | The default alignment for this record is normally 1, but if this type is | |
e94434ba | 4383 | compiled in ``Optimize_Alignment (Time)`` mode, then the alignment is set |
bf5dffd3 | 4384 | to 4, which wastes space for objects of the type, since they are now 4 bytes |
4385 | long, but results in more efficient access when the whole record is referenced. | |
4386 | ||
4387 | As noted above, this is a configuration pragma, and there is a requirement | |
4388 | that all units in a partition be compiled with a consistent setting of the | |
4389 | optimization setting. This would normally be achieved by use of a configuration | |
4390 | pragma file containing the appropriate setting. The exception to this rule is | |
4391 | that units with an explicit configuration pragma in the same file as the source | |
4392 | unit are excluded from the consistency check, as are all predefined units. The | |
4393 | latter are compiled by default in pragma Optimize_Alignment (Off) mode if no | |
4394 | pragma appears at the start of the file. | |
4395 | ||
4396 | Pragma Ordered | |
4397 | ============== | |
4398 | ||
4399 | Syntax: | |
4400 | ||
4401 | ||
4402 | .. code-block:: ada | |
4403 | ||
4404 | pragma Ordered (enumeration_first_subtype_LOCAL_NAME); | |
4405 | ||
4406 | ||
4407 | Most enumeration types are from a conceptual point of view unordered. | |
4408 | For example, consider: | |
4409 | ||
4410 | ||
4411 | .. code-block:: ada | |
4412 | ||
4413 | type Color is (Red, Blue, Green, Yellow); | |
4414 | ||
4415 | ||
e94434ba | 4416 | By Ada semantics ``Blue > Red`` and ``Green > Blue``, |
bf5dffd3 | 4417 | but really these relations make no sense; the enumeration type merely |
4418 | specifies a set of possible colors, and the order is unimportant. | |
4419 | ||
4420 | For unordered enumeration types, it is generally a good idea if | |
4421 | clients avoid comparisons (other than equality or inequality) and | |
4422 | explicit ranges. (A *client* is a unit where the type is referenced, | |
4423 | other than the unit where the type is declared, its body, and its subunits.) | |
4424 | For example, if code buried in some client says: | |
4425 | ||
4426 | ||
4427 | .. code-block:: ada | |
4428 | ||
4429 | if Current_Color < Yellow then ... | |
4430 | if Current_Color in Blue .. Green then ... | |
4431 | ||
4432 | ||
4433 | then the client code is relying on the order, which is undesirable. | |
4434 | It makes the code hard to read and creates maintenance difficulties if | |
4435 | entries have to be added to the enumeration type. Instead, | |
4436 | the code in the client should list the possibilities, or an | |
4437 | appropriate subtype should be declared in the unit that declares | |
4438 | the original enumeration type. E.g., the following subtype could | |
e94434ba | 4439 | be declared along with the type ``Color``: |
bf5dffd3 | 4440 | |
4441 | ||
4442 | .. code-block:: ada | |
4443 | ||
4444 | subtype RBG is Color range Red .. Green; | |
4445 | ||
4446 | ||
4447 | and then the client could write: | |
4448 | ||
4449 | ||
4450 | .. code-block:: ada | |
4451 | ||
4452 | if Current_Color in RBG then ... | |
4453 | if Current_Color = Blue or Current_Color = Green then ... | |
4454 | ||
4455 | ||
4456 | However, some enumeration types are legitimately ordered from a conceptual | |
4457 | point of view. For example, if you declare: | |
4458 | ||
4459 | ||
4460 | .. code-block:: ada | |
4461 | ||
4462 | type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun); | |
4463 | ||
4464 | ||
4465 | then the ordering imposed by the language is reasonable, and | |
4466 | clients can depend on it, writing for example: | |
4467 | ||
4468 | ||
4469 | .. code-block:: ada | |
4470 | ||
4471 | if D in Mon .. Fri then ... | |
4472 | if D < Wed then ... | |
4473 | ||
4474 | ||
4475 | The pragma *Ordered* is provided to mark enumeration types that | |
4476 | are conceptually ordered, alerting the reader that clients may depend | |
4477 | on the ordering. GNAT provides a pragma to mark enumerations as ordered | |
4478 | rather than one to mark them as unordered, since in our experience, | |
4479 | the great majority of enumeration types are conceptually unordered. | |
4480 | ||
e94434ba | 4481 | The types ``Boolean``, ``Character``, ``Wide_Character``, |
4482 | and ``Wide_Wide_Character`` | |
bf5dffd3 | 4483 | are considered to be ordered types, so each is declared with a |
e94434ba | 4484 | pragma ``Ordered`` in package ``Standard``. |
bf5dffd3 | 4485 | |
e94434ba | 4486 | Normally pragma ``Ordered`` serves only as documentation and a guide for |
bf5dffd3 | 4487 | coding standards, but GNAT provides a warning switch *-gnatw.u* that |
4488 | requests warnings for inappropriate uses (comparisons and explicit | |
4489 | subranges) for unordered types. If this switch is used, then any | |
e94434ba | 4490 | enumeration type not marked with pragma ``Ordered`` will be considered |
bf5dffd3 | 4491 | as unordered, and will generate warnings for inappropriate uses. |
4492 | ||
4493 | Note that generic types are not considered ordered or unordered (since the | |
4494 | template can be instantiated for both cases), so we never generate warnings | |
4495 | for the case of generic enumerated types. | |
4496 | ||
4497 | For additional information please refer to the description of the | |
4498 | *-gnatw.u* switch in the GNAT User's Guide. | |
4499 | ||
4500 | Pragma Overflow_Mode | |
4501 | ==================== | |
4502 | ||
4503 | Syntax: | |
4504 | ||
4505 | ||
4506 | :: | |
4507 | ||
4508 | pragma Overflow_Mode | |
4509 | ( [General =>] MODE | |
4510 | [,[Assertions =>] MODE]); | |
4511 | ||
4512 | MODE ::= STRICT | MINIMIZED | ELIMINATED | |
4513 | ||
4514 | ||
4515 | This pragma sets the current overflow mode to the given setting. For details | |
4516 | of the meaning of these modes, please refer to the | |
4517 | 'Overflow Check Handling in GNAT' appendix in the | |
e94434ba | 4518 | GNAT User's Guide. If only the ``General`` parameter is present, |
bf5dffd3 | 4519 | the given mode applies to all expressions. If both parameters are present, |
e94434ba | 4520 | the ``General`` mode applies to expressions outside assertions, and |
4521 | the ``Eliminated`` mode applies to expressions within assertions. | |
bf5dffd3 | 4522 | |
e94434ba | 4523 | The case of the ``MODE`` parameter is ignored, |
4524 | so ``MINIMIZED``, ``Minimized`` and | |
4525 | ``minimized`` all have the same effect. | |
bf5dffd3 | 4526 | |
e94434ba | 4527 | The ``Overflow_Mode`` pragma has the same scoping and placement |
4528 | rules as pragma ``Suppress``, so it can occur either as a | |
bf5dffd3 | 4529 | configuration pragma, specifying a default for the whole |
4530 | program, or in a declarative scope, where it applies to the | |
4531 | remaining declarations and statements in that scope. | |
4532 | ||
e94434ba | 4533 | The pragma ``Suppress (Overflow_Check)`` suppresses |
bf5dffd3 | 4534 | overflow checking, but does not affect the overflow mode. |
4535 | ||
e94434ba | 4536 | The pragma ``Unsuppress (Overflow_Check)`` unsuppresses (enables) |
bf5dffd3 | 4537 | overflow checking, but does not affect the overflow mode. |
4538 | ||
4539 | Pragma Overriding_Renamings | |
4540 | =========================== | |
4541 | .. index:: Rational profile | |
4542 | ||
4543 | .. index:: Rational compatibility | |
4544 | ||
4545 | Syntax: | |
4546 | ||
4547 | ||
4548 | .. code-block:: ada | |
4549 | ||
4550 | pragma Overriding_Renamings; | |
4551 | ||
4552 | ||
4553 | This is a GNAT configuration pragma to simplify porting | |
4554 | legacy code accepted by the Rational | |
4555 | Ada compiler. In the presence of this pragma, a renaming declaration that | |
4556 | renames an inherited operation declared in the same scope is legal if selected | |
4557 | notation is used as in: | |
4558 | ||
4559 | ||
4560 | .. code-block:: ada | |
4561 | ||
4562 | pragma Overriding_Renamings; | |
4563 | ... | |
4564 | package R is | |
4565 | function F (..); | |
4566 | ... | |
4567 | function F (..) renames R.F; | |
4568 | end R; | |
4569 | ||
4570 | ||
4571 | even though | |
4572 | RM 8.3 (15) stipulates that an overridden operation is not visible within the | |
4573 | declaration of the overriding operation. | |
4574 | ||
4575 | Pragma Partition_Elaboration_Policy | |
4576 | =================================== | |
4577 | ||
4578 | Syntax: | |
4579 | ||
4580 | ||
4581 | :: | |
4582 | ||
4583 | pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER); | |
4584 | ||
4585 | POLICY_IDENTIFIER ::= Concurrent | Sequential | |
4586 | ||
4587 | ||
4588 | This pragma is standard in Ada 2005, but is available in all earlier | |
4589 | versions of Ada as an implementation-defined pragma. | |
4590 | See Ada 2012 Reference Manual for details. | |
4591 | ||
39adf1e6 | 4592 | .. _Pragma-Part_Of: |
4593 | ||
bf5dffd3 | 4594 | Pragma Part_Of |
4595 | ============== | |
4596 | ||
d5dcec30 | 4597 | Syntax: |
4598 | ||
4599 | .. code-block:: ada | |
4600 | ||
4601 | pragma Part_Of (ABSTRACT_STATE); | |
4602 | ||
4603 | ABSTRACT_STATE ::= NAME | |
4604 | ||
e94434ba | 4605 | For the semantics of this pragma, see the entry for aspect ``Part_Of`` in the |
d5dcec30 | 4606 | SPARK 2014 Reference Manual, section 7.2.6. |
bf5dffd3 | 4607 | |
4608 | Pragma Passive | |
4609 | ============== | |
4610 | ||
4611 | Syntax: | |
4612 | ||
4613 | ||
4614 | :: | |
4615 | ||
4616 | pragma Passive [(Semaphore | No)]; | |
4617 | ||
4618 | ||
4619 | Syntax checked, but otherwise ignored by GNAT. This is recognized for | |
4620 | compatibility with DEC Ada 83 implementations, where it is used within a | |
4621 | task definition to request that a task be made passive. If the argument | |
e94434ba | 4622 | ``Semaphore`` is present, or the argument is omitted, then DEC Ada 83 |
bf5dffd3 | 4623 | treats the pragma as an assertion that the containing task is passive |
4624 | and that optimization of context switch with this task is permitted and | |
e94434ba | 4625 | desired. If the argument ``No`` is present, the task must not be |
bf5dffd3 | 4626 | optimized. GNAT does not attempt to optimize any tasks in this manner |
4627 | (since protected objects are available in place of passive tasks). | |
4628 | ||
4629 | For more information on the subject of passive tasks, see the section | |
4630 | 'Passive Task Optimization' in the GNAT Users Guide. | |
4631 | ||
39adf1e6 | 4632 | .. _Pragma-Persistent_BSS: |
4633 | ||
bf5dffd3 | 4634 | Pragma Persistent_BSS |
4635 | ===================== | |
4636 | ||
4637 | Syntax: | |
4638 | ||
4639 | ||
4640 | :: | |
4641 | ||
4642 | pragma Persistent_BSS [(LOCAL_NAME)] | |
4643 | ||
4644 | ||
e94434ba | 4645 | This pragma allows selected objects to be placed in the ``.persistent_bss`` |
bf5dffd3 | 4646 | section. On some targets the linker and loader provide for special |
4647 | treatment of this section, allowing a program to be reloaded without | |
4648 | affecting the contents of this data (hence the name persistent). | |
4649 | ||
4650 | There are two forms of usage. If an argument is given, it must be the | |
e94434ba | 4651 | local name of a library-level object, with no explicit initialization |
bf5dffd3 | 4652 | and whose type is potentially persistent. If no argument is given, then |
e94434ba | 4653 | the pragma is a configuration pragma, and applies to all library-level |
bf5dffd3 | 4654 | objects with no explicit initialization of potentially persistent types. |
4655 | ||
4656 | A potentially persistent type is a scalar type, or an untagged, | |
4657 | non-discriminated record, all of whose components have no explicit | |
4658 | initialization and are themselves of a potentially persistent type, | |
4659 | or an array, all of whose constraints are static, and whose component | |
4660 | type is potentially persistent. | |
4661 | ||
4662 | If this pragma is used on a target where this feature is not supported, | |
e94434ba | 4663 | then the pragma will be ignored. See also ``pragma Linker_Section``. |
bf5dffd3 | 4664 | |
4665 | Pragma Polling | |
4666 | ============== | |
4667 | ||
4668 | Syntax: | |
4669 | ||
4670 | ||
4671 | .. code-block:: ada | |
4672 | ||
4673 | pragma Polling (ON | OFF); | |
4674 | ||
4675 | ||
4676 | This pragma controls the generation of polling code. This is normally off. | |
e94434ba | 4677 | If ``pragma Polling (ON)`` is used then periodic calls are generated to |
4678 | the routine ``Ada.Exceptions.Poll``. This routine is a separate unit in the | |
bf5dffd3 | 4679 | runtime library, and can be found in file :file:`a-excpol.adb`. |
4680 | ||
e94434ba | 4681 | Pragma ``Polling`` can appear as a configuration pragma (for example it |
bf5dffd3 | 4682 | can be placed in the :file:`gnat.adc` file) to enable polling globally, or it |
4683 | can be used in the statement or declaration sequence to control polling | |
4684 | more locally. | |
4685 | ||
4686 | A call to the polling routine is generated at the start of every loop and | |
e94434ba | 4687 | at the start of every subprogram call. This guarantees that the ``Poll`` |
bf5dffd3 | 4688 | routine is called frequently, and places an upper bound (determined by |
e94434ba | 4689 | the complexity of the code) on the period between two ``Poll`` calls. |
bf5dffd3 | 4690 | |
4691 | The primary purpose of the polling interface is to enable asynchronous | |
4692 | aborts on targets that cannot otherwise support it (for example Windows | |
4693 | NT), but it may be used for any other purpose requiring periodic polling. | |
4694 | The standard version is null, and can be replaced by a user program. This | |
e94434ba | 4695 | will require re-compilation of the ``Ada.Exceptions`` package that can |
bf5dffd3 | 4696 | be found in files :file:`a-except.ads` and :file:`a-except.adb`. |
4697 | ||
4698 | A standard alternative unit (in file :file:`4wexcpol.adb` in the standard GNAT | |
4699 | distribution) is used to enable the asynchronous abort capability on | |
4700 | targets that do not normally support the capability. The version of | |
e94434ba | 4701 | ``Poll`` in this file makes a call to the appropriate runtime routine |
bf5dffd3 | 4702 | to test for an abort condition. |
4703 | ||
4704 | Note that polling can also be enabled by use of the *-gnatP* switch. | |
4705 | See the section on switches for gcc in the :title:`GNAT User's Guide`. | |
4706 | ||
4707 | Pragma Post | |
4708 | =========== | |
4709 | .. index:: Post | |
4710 | ||
4711 | .. index:: Checks, postconditions | |
4712 | ||
4713 | ||
4714 | Syntax: | |
4715 | ||
4716 | ||
4717 | .. code-block:: ada | |
4718 | ||
4719 | pragma Post (Boolean_Expression); | |
4720 | ||
4721 | ||
e94434ba | 4722 | The ``Post`` pragma is intended to be an exact replacement for |
bf5dffd3 | 4723 | the language-defined |
e94434ba | 4724 | ``Post`` aspect, and shares its restrictions and semantics. |
bf5dffd3 | 4725 | It must appear either immediately following the corresponding |
4726 | subprogram declaration (only other pragmas may intervene), or | |
4727 | if there is no separate subprogram declaration, then it can | |
4728 | appear at the start of the declarations in a subprogram body | |
4729 | (preceded only by other pragmas). | |
4730 | ||
4731 | Pragma Postcondition | |
4732 | ==================== | |
4733 | .. index:: Postcondition | |
4734 | ||
4735 | .. index:: Checks, postconditions | |
4736 | ||
4737 | ||
4738 | Syntax: | |
4739 | ||
4740 | ||
4741 | :: | |
4742 | ||
4743 | pragma Postcondition ( | |
4744 | [Check =>] Boolean_Expression | |
4745 | [,[Message =>] String_Expression]); | |
4746 | ||
4747 | ||
e94434ba | 4748 | The ``Postcondition`` pragma allows specification of automatic |
bf5dffd3 | 4749 | postcondition checks for subprograms. These checks are similar to |
4750 | assertions, but are automatically inserted just prior to the return | |
4751 | statements of the subprogram with which they are associated (including | |
4752 | implicit returns at the end of procedure bodies and associated | |
4753 | exception handlers). | |
4754 | ||
4755 | In addition, the boolean expression which is the condition which | |
4756 | must be true may contain references to function'Result in the case | |
4757 | of a function to refer to the returned value. | |
4758 | ||
e94434ba | 4759 | ``Postcondition`` pragmas may appear either immediately following the |
bf5dffd3 | 4760 | (separate) declaration of a subprogram, or at the start of the |
4761 | declarations of a subprogram body. Only other pragmas may intervene | |
4762 | (that is appear between the subprogram declaration and its | |
4763 | postconditions, or appear before the postcondition in the | |
4764 | declaration sequence in a subprogram body). In the case of a | |
4765 | postcondition appearing after a subprogram declaration, the | |
4766 | formal arguments of the subprogram are visible, and can be | |
4767 | referenced in the postcondition expressions. | |
4768 | ||
4769 | The postconditions are collected and automatically tested just | |
4770 | before any return (implicit or explicit) in the subprogram body. | |
4771 | A postcondition is only recognized if postconditions are active | |
4772 | at the time the pragma is encountered. The compiler switch *gnata* | |
e94434ba | 4773 | turns on all postconditions by default, and pragma ``Check_Policy`` |
4774 | with an identifier of ``Postcondition`` can also be used to | |
bf5dffd3 | 4775 | control whether postconditions are active. |
4776 | ||
4777 | The general approach is that postconditions are placed in the spec | |
4778 | if they represent functional aspects which make sense to the client. | |
4779 | For example we might have: | |
4780 | ||
4781 | ||
4782 | .. code-block:: ada | |
4783 | ||
4784 | function Direction return Integer; | |
4785 | pragma Postcondition | |
4786 | (Direction'Result = +1 | |
4787 | or else | |
4788 | Direction'Result = -1); | |
4789 | ||
4790 | ||
4791 | which serves to document that the result must be +1 or -1, and | |
4792 | will test that this is the case at run time if postcondition | |
4793 | checking is active. | |
4794 | ||
4795 | Postconditions within the subprogram body can be used to | |
4796 | check that some internal aspect of the implementation, | |
4797 | not visible to the client, is operating as expected. | |
4798 | For instance if a square root routine keeps an internal | |
4799 | counter of the number of times it is called, then we | |
4800 | might have the following postcondition: | |
4801 | ||
4802 | ||
4803 | .. code-block:: ada | |
4804 | ||
4805 | Sqrt_Calls : Natural := 0; | |
4806 | ||
4807 | function Sqrt (Arg : Float) return Float is | |
4808 | pragma Postcondition | |
4809 | (Sqrt_Calls = Sqrt_Calls'Old + 1); | |
4810 | ... | |
4811 | end Sqrt | |
4812 | ||
4813 | ||
e94434ba | 4814 | As this example, shows, the use of the ``Old`` attribute |
bf5dffd3 | 4815 | is often useful in postconditions to refer to the state on |
4816 | entry to the subprogram. | |
4817 | ||
4818 | Note that postconditions are only checked on normal returns | |
4819 | from the subprogram. If an abnormal return results from | |
4820 | raising an exception, then the postconditions are not checked. | |
4821 | ||
4822 | If a postcondition fails, then the exception | |
e94434ba | 4823 | ``System.Assertions.Assert_Failure`` is raised. If |
bf5dffd3 | 4824 | a message argument was supplied, then the given string |
4825 | will be used as the exception message. If no message | |
4826 | argument was supplied, then the default message has | |
4827 | the form "Postcondition failed at file_name:line". The | |
4828 | exception is raised in the context of the subprogram | |
4829 | body, so it is possible to catch postcondition failures | |
4830 | within the subprogram body itself. | |
4831 | ||
4832 | Within a package spec, normal visibility rules | |
4833 | in Ada would prevent forward references within a | |
4834 | postcondition pragma to functions defined later in | |
4835 | the same package. This would introduce undesirable | |
4836 | ordering constraints. To avoid this problem, all | |
4837 | postcondition pragmas are analyzed at the end of | |
4838 | the package spec, allowing forward references. | |
4839 | ||
4840 | The following example shows that this even allows | |
4841 | mutually recursive postconditions as in: | |
4842 | ||
4843 | ||
4844 | .. code-block:: ada | |
4845 | ||
4846 | package Parity_Functions is | |
4847 | function Odd (X : Natural) return Boolean; | |
4848 | pragma Postcondition | |
4849 | (Odd'Result = | |
4850 | (x = 1 | |
4851 | or else | |
4852 | (x /= 0 and then Even (X - 1)))); | |
4853 | ||
4854 | function Even (X : Natural) return Boolean; | |
4855 | pragma Postcondition | |
4856 | (Even'Result = | |
4857 | (x = 0 | |
4858 | or else | |
4859 | (x /= 1 and then Odd (X - 1)))); | |
4860 | ||
4861 | end Parity_Functions; | |
4862 | ||
4863 | ||
4864 | There are no restrictions on the complexity or form of | |
e94434ba | 4865 | conditions used within ``Postcondition`` pragmas. |
bf5dffd3 | 4866 | The following example shows that it is even possible |
4867 | to verify performance behavior. | |
4868 | ||
4869 | ||
4870 | .. code-block:: ada | |
4871 | ||
4872 | package Sort is | |
4873 | ||
4874 | Performance : constant Float; | |
4875 | -- Performance constant set by implementation | |
4876 | -- to match target architecture behavior. | |
4877 | ||
4878 | procedure Treesort (Arg : String); | |
4879 | -- Sorts characters of argument using N*logN sort | |
4880 | pragma Postcondition | |
4881 | (Float (Clock - Clock'Old) <= | |
4882 | Float (Arg'Length) * | |
4883 | log (Float (Arg'Length)) * | |
4884 | Performance); | |
4885 | end Sort; | |
4886 | ||
4887 | ||
4888 | Note: postcondition pragmas associated with subprograms that are | |
4889 | marked as Inline_Always, or those marked as Inline with front-end | |
4890 | inlining (-gnatN option set) are accepted and legality-checked | |
4891 | by the compiler, but are ignored at run-time even if postcondition | |
4892 | checking is enabled. | |
4893 | ||
e94434ba | 4894 | Note that pragma ``Postcondition`` differs from the language-defined |
4895 | ``Post`` aspect (and corresponding ``Post`` pragma) in allowing | |
bf5dffd3 | 4896 | multiple occurrences, allowing occurences in the body even if there |
4897 | is a separate spec, and allowing a second string parameter, and the | |
e94434ba | 4898 | use of the pragma identifier ``Check``. Historically, pragma |
4899 | ``Postcondition`` was implemented prior to the development of | |
bf5dffd3 | 4900 | Ada 2012, and has been retained in its original form for |
4901 | compatibility purposes. | |
4902 | ||
4903 | Pragma Post_Class | |
4904 | ================= | |
4905 | .. index:: Post | |
4906 | ||
4907 | .. index:: Checks, postconditions | |
4908 | ||
4909 | ||
4910 | Syntax: | |
4911 | ||
4912 | ||
4913 | .. code-block:: ada | |
4914 | ||
4915 | pragma Post_Class (Boolean_Expression); | |
4916 | ||
4917 | ||
e94434ba | 4918 | The ``Post_Class`` pragma is intended to be an exact replacement for |
bf5dffd3 | 4919 | the language-defined |
e94434ba | 4920 | ``Post'Class`` aspect, and shares its restrictions and semantics. |
bf5dffd3 | 4921 | It must appear either immediately following the corresponding |
4922 | subprogram declaration (only other pragmas may intervene), or | |
4923 | if there is no separate subprogram declaration, then it can | |
4924 | appear at the start of the declarations in a subprogram body | |
4925 | (preceded only by other pragmas). | |
4926 | ||
e94434ba | 4927 | Note: This pragma is called ``Post_Class`` rather than |
4928 | ``Post'Class`` because the latter would not be strictly | |
bf5dffd3 | 4929 | conforming to the allowed syntax for pragmas. The motivation |
4930 | for provinding pragmas equivalent to the aspects is to allow a program | |
4931 | to be written using the pragmas, and then compiled if necessary | |
4932 | using an Ada compiler that does not recognize the pragmas or | |
4933 | aspects, but is prepared to ignore the pragmas. The assertion | |
e94434ba | 4934 | policy that controls this pragma is ``Post'Class``, not |
4935 | ``Post_Class``. | |
bf5dffd3 | 4936 | |
0c01a524 | 4937 | Pragma Rename_Pragma |
4938 | ============================ | |
4939 | .. index:: Pragmas, synonyms | |
4940 | ||
4941 | Syntax: | |
4942 | ||
4943 | ||
4944 | :: | |
4945 | ||
4946 | pragma Rename_Pragma ( | |
4947 | [New_Name =>] IDENTIFIER, | |
4948 | [Renamed =>] pragma_IDENTIFIER); | |
4949 | ||
4950 | This pragma provides a mechanism for supplying new names for existing | |
e94434ba | 4951 | pragmas. The ``New_Name`` identifier can subsequently be used as a synonym for |
0c01a524 | 4952 | the Renamed pragma. For example, suppose you have code that was originally |
4953 | developed on a compiler that supports Inline_Only as an implementation defined | |
4954 | pragma. And suppose the semantics of pragma Inline_Only are identical to (or at | |
4955 | least very similar to) the GNAT implementation defined pragma | |
4956 | Inline_Always. You could globally replace Inline_Only with Inline_Always. | |
4957 | ||
4958 | However, to avoid that source modification, you could instead add a | |
4959 | configuration pragma: | |
4960 | ||
4961 | .. code-block:: ada | |
4962 | ||
4963 | pragma Rename_Pragma ( | |
4964 | New_Name => Inline_Only, | |
4965 | Renamed => Inline_Always); | |
4966 | ||
4967 | ||
4968 | Then GNAT will treat "pragma Inline_Only ..." as if you had written | |
4969 | "pragma Inline_Always ...". | |
4970 | ||
4971 | Pragma Inline_Only will not necessarily mean the same thing as the other Ada | |
4972 | compiler; it's up to you to make sure the semantics are close enough. | |
4973 | ||
bf5dffd3 | 4974 | Pragma Pre |
4975 | ========== | |
4976 | .. index:: Pre | |
4977 | ||
4978 | .. index:: Checks, preconditions | |
4979 | ||
4980 | ||
4981 | Syntax: | |
4982 | ||
4983 | ||
4984 | .. code-block:: ada | |
4985 | ||
4986 | pragma Pre (Boolean_Expression); | |
4987 | ||
4988 | ||
e94434ba | 4989 | The ``Pre`` pragma is intended to be an exact replacement for |
bf5dffd3 | 4990 | the language-defined |
e94434ba | 4991 | ``Pre`` aspect, and shares its restrictions and semantics. |
bf5dffd3 | 4992 | It must appear either immediately following the corresponding |
4993 | subprogram declaration (only other pragmas may intervene), or | |
4994 | if there is no separate subprogram declaration, then it can | |
4995 | appear at the start of the declarations in a subprogram body | |
4996 | (preceded only by other pragmas). | |
4997 | ||
4998 | Pragma Precondition | |
4999 | =================== | |
5000 | .. index:: Preconditions | |
5001 | ||
5002 | .. index:: Checks, preconditions | |
5003 | ||
5004 | ||
5005 | Syntax: | |
5006 | ||
5007 | ||
5008 | :: | |
5009 | ||
5010 | pragma Precondition ( | |
5011 | [Check =>] Boolean_Expression | |
5012 | [,[Message =>] String_Expression]); | |
5013 | ||
5014 | ||
e94434ba | 5015 | The ``Precondition`` pragma is similar to ``Postcondition`` |
bf5dffd3 | 5016 | except that the corresponding checks take place immediately upon |
5017 | entry to the subprogram, and if a precondition fails, the exception | |
5018 | is raised in the context of the caller, and the attribute 'Result | |
5019 | cannot be used within the precondition expression. | |
5020 | ||
5021 | Otherwise, the placement and visibility rules are identical to those | |
5022 | described for postconditions. The following is an example of use | |
5023 | within a package spec: | |
5024 | ||
5025 | ||
5026 | .. code-block:: ada | |
5027 | ||
5028 | package Math_Functions is | |
5029 | ... | |
5030 | function Sqrt (Arg : Float) return Float; | |
5031 | pragma Precondition (Arg >= 0.0) | |
5032 | ... | |
5033 | end Math_Functions; | |
5034 | ||
5035 | ||
e94434ba | 5036 | ``Precondition`` pragmas may appear either immediately following the |
bf5dffd3 | 5037 | (separate) declaration of a subprogram, or at the start of the |
5038 | declarations of a subprogram body. Only other pragmas may intervene | |
5039 | (that is appear between the subprogram declaration and its | |
5040 | postconditions, or appear before the postcondition in the | |
5041 | declaration sequence in a subprogram body). | |
5042 | ||
5043 | Note: precondition pragmas associated with subprograms that are | |
5044 | marked as Inline_Always, or those marked as Inline with front-end | |
5045 | inlining (-gnatN option set) are accepted and legality-checked | |
5046 | by the compiler, but are ignored at run-time even if precondition | |
5047 | checking is enabled. | |
5048 | ||
e94434ba | 5049 | Note that pragma ``Precondition`` differs from the language-defined |
5050 | ``Pre`` aspect (and corresponding ``Pre`` pragma) in allowing | |
bf5dffd3 | 5051 | multiple occurrences, allowing occurences in the body even if there |
5052 | is a separate spec, and allowing a second string parameter, and the | |
e94434ba | 5053 | use of the pragma identifier ``Check``. Historically, pragma |
5054 | ``Precondition`` was implemented prior to the development of | |
bf5dffd3 | 5055 | Ada 2012, and has been retained in its original form for |
5056 | compatibility purposes. | |
5057 | ||
39adf1e6 | 5058 | .. _Pragma-Predicate: |
5059 | ||
bf5dffd3 | 5060 | Pragma Predicate |
5061 | ================ | |
5062 | ||
5063 | Syntax: | |
5064 | ||
5065 | ||
5066 | :: | |
5067 | ||
5068 | pragma Predicate | |
5069 | ([Entity =>] type_LOCAL_NAME, | |
5070 | [Check =>] EXPRESSION); | |
5071 | ||
5072 | ||
5073 | This pragma (available in all versions of Ada in GNAT) encompasses both | |
e94434ba | 5074 | the ``Static_Predicate`` and ``Dynamic_Predicate`` aspects in |
bf5dffd3 | 5075 | Ada 2012. A predicate is regarded as static if it has an allowed form |
e94434ba | 5076 | for ``Static_Predicate`` and is otherwise treated as a |
5077 | ``Dynamic_Predicate``. Otherwise, predicates specified by this | |
bf5dffd3 | 5078 | pragma behave exactly as described in the Ada 2012 reference manual. |
5079 | For example, if we have | |
5080 | ||
5081 | ||
5082 | .. code-block:: ada | |
5083 | ||
5084 | type R is range 1 .. 10; | |
5085 | subtype S is R; | |
5086 | pragma Predicate (Entity => S, Check => S not in 4 .. 6); | |
5087 | subtype Q is R | |
5088 | pragma Predicate (Entity => Q, Check => F(Q) or G(Q)); | |
5089 | ||
5090 | ||
5091 | the effect is identical to the following Ada 2012 code: | |
5092 | ||
5093 | ||
5094 | .. code-block:: ada | |
5095 | ||
5096 | type R is range 1 .. 10; | |
5097 | subtype S is R with | |
5098 | Static_Predicate => S not in 4 .. 6; | |
5099 | subtype Q is R with | |
5100 | Dynamic_Predicate => F(Q) or G(Q); | |
5101 | ||
5102 | ||
e94434ba | 5103 | Note that there are no pragmas ``Dynamic_Predicate`` |
5104 | or ``Static_Predicate``. That is | |
bf5dffd3 | 5105 | because these pragmas would affect legality and semantics of |
5106 | the program and thus do not have a neutral effect if ignored. | |
5107 | The motivation behind providing pragmas equivalent to | |
5108 | corresponding aspects is to allow a program to be written | |
5109 | using the pragmas, and then compiled with a compiler that | |
5110 | will ignore the pragmas. That doesn't work in the case of | |
5111 | static and dynamic predicates, since if the corresponding | |
5112 | pragmas are ignored, then the behavior of the program is | |
5113 | fundamentally changed (for example a membership test | |
e94434ba | 5114 | ``A in B`` would not take into account a predicate |
bf5dffd3 | 5115 | defined for subtype B). When following this approach, the |
5116 | use of predicates should be avoided. | |
5117 | ||
627dfdb4 | 5118 | Pragma Predicate_Failure |
5119 | ======================== | |
5120 | ||
5121 | Syntax: | |
5122 | ||
5123 | ||
5124 | :: | |
5125 | ||
5126 | pragma Predicate_Failure | |
5127 | ([Entity =>] type_LOCAL_NAME, | |
5128 | [Message =>] String_Expression); | |
5129 | ||
5130 | ||
e94434ba | 5131 | The ``Predicate_Failure`` pragma is intended to be an exact replacement for |
627dfdb4 | 5132 | the language-defined |
e94434ba | 5133 | ``Predicate_Failure`` aspect, and shares its restrictions and semantics. |
627dfdb4 | 5134 | |
bf5dffd3 | 5135 | Pragma Preelaborable_Initialization |
5136 | =================================== | |
5137 | ||
5138 | Syntax: | |
5139 | ||
5140 | ||
5141 | .. code-block:: ada | |
5142 | ||
5143 | pragma Preelaborable_Initialization (DIRECT_NAME); | |
5144 | ||
5145 | ||
5146 | This pragma is standard in Ada 2005, but is available in all earlier | |
5147 | versions of Ada as an implementation-defined pragma. | |
5148 | See Ada 2012 Reference Manual for details. | |
5149 | ||
5150 | Pragma Prefix_Exception_Messages | |
5151 | ================================ | |
5152 | .. index:: Prefix_Exception_Messages | |
5153 | ||
5154 | .. index:: exception | |
5155 | ||
5156 | .. index:: Exception_Message | |
5157 | ||
5158 | ||
5159 | Syntax: | |
5160 | ||
5161 | ||
5162 | .. code-block:: ada | |
5163 | ||
5164 | pragma Prefix_Exception_Messages; | |
5165 | ||
5166 | ||
5167 | This is an implementation-defined configuration pragma that affects the | |
5168 | behavior of raise statements with a message given as a static string | |
5169 | constant (typically a string literal). In such cases, the string will | |
5170 | be automatically prefixed by the name of the enclosing entity (giving | |
5171 | the package and subprogram containing the raise statement). This helps | |
5172 | to identify where messages are coming from, and this mode is automatic | |
5173 | for the run-time library. | |
5174 | ||
5175 | The pragma has no effect if the message is computed with an expression other | |
5176 | than a static string constant, since the assumption in this case is that | |
5177 | the program computes exactly the string it wants. If you still want the | |
5178 | prefixing in this case, you can always call | |
e94434ba | 5179 | ``GNAT.Source_Info.Enclosing_Entity`` and prepend the string manually. |
bf5dffd3 | 5180 | |
5181 | Pragma Pre_Class | |
5182 | ================ | |
5183 | .. index:: Pre_Class | |
5184 | ||
5185 | .. index:: Checks, preconditions | |
5186 | ||
5187 | ||
5188 | Syntax: | |
5189 | ||
5190 | ||
5191 | .. code-block:: ada | |
5192 | ||
5193 | pragma Pre_Class (Boolean_Expression); | |
5194 | ||
5195 | ||
e94434ba | 5196 | The ``Pre_Class`` pragma is intended to be an exact replacement for |
bf5dffd3 | 5197 | the language-defined |
e94434ba | 5198 | ``Pre'Class`` aspect, and shares its restrictions and semantics. |
bf5dffd3 | 5199 | It must appear either immediately following the corresponding |
5200 | subprogram declaration (only other pragmas may intervene), or | |
5201 | if there is no separate subprogram declaration, then it can | |
5202 | appear at the start of the declarations in a subprogram body | |
5203 | (preceded only by other pragmas). | |
5204 | ||
e94434ba | 5205 | Note: This pragma is called ``Pre_Class`` rather than |
5206 | ``Pre'Class`` because the latter would not be strictly | |
bf5dffd3 | 5207 | conforming to the allowed syntax for pragmas. The motivation |
5208 | for providing pragmas equivalent to the aspects is to allow a program | |
5209 | to be written using the pragmas, and then compiled if necessary | |
5210 | using an Ada compiler that does not recognize the pragmas or | |
5211 | aspects, but is prepared to ignore the pragmas. The assertion | |
e94434ba | 5212 | policy that controls this pragma is ``Pre'Class``, not |
5213 | ``Pre_Class``. | |
bf5dffd3 | 5214 | |
5215 | Pragma Priority_Specific_Dispatching | |
5216 | ==================================== | |
5217 | ||
5218 | Syntax: | |
5219 | ||
5220 | ||
5221 | :: | |
5222 | ||
5223 | pragma Priority_Specific_Dispatching ( | |
5224 | POLICY_IDENTIFIER, | |
5225 | first_priority_EXPRESSION, | |
5226 | last_priority_EXPRESSION) | |
5227 | ||
5228 | POLICY_IDENTIFIER ::= | |
5229 | EDF_Across_Priorities | | |
5230 | FIFO_Within_Priorities | | |
5231 | Non_Preemptive_Within_Priorities | | |
5232 | Round_Robin_Within_Priorities | |
5233 | ||
5234 | ||
5235 | This pragma is standard in Ada 2005, but is available in all earlier | |
5236 | versions of Ada as an implementation-defined pragma. | |
5237 | See Ada 2012 Reference Manual for details. | |
5238 | ||
5239 | Pragma Profile | |
5240 | ============== | |
5241 | ||
5242 | Syntax: | |
5243 | ||
5244 | ||
5245 | .. code-block:: ada | |
5246 | ||
8f09eafa | 5247 | pragma Profile (Ravenscar | Restricted | Rational | |
5248 | GNAT_Extended_Ravenscar | GNAT_Ravenscar_EDF ); | |
bf5dffd3 | 5249 | |
5250 | ||
5251 | This pragma is standard in Ada 2005, but is available in all earlier | |
5252 | versions of Ada as an implementation-defined pragma. This is a | |
5253 | configuration pragma that establishes a set of configuration pragmas | |
e94434ba | 5254 | that depend on the argument. ``Ravenscar`` is standard in Ada 2005. |
5255 | The other possibilities (``Restricted``, ``Rational``, | |
5256 | ``GNAT_Extended_Ravenscar``, ``GNAT_Ravenscar_EDF``) | |
bf5dffd3 | 5257 | are implementation-defined. The set of configuration pragmas |
5258 | is defined in the following sections. | |
5259 | ||
5260 | ||
5261 | * Pragma Profile (Ravenscar) | |
5262 | ||
e94434ba | 5263 | The ``Ravenscar`` profile is standard in Ada 2005, |
bf5dffd3 | 5264 | but is available in all earlier |
5265 | versions of Ada as an implementation-defined pragma. This profile | |
5266 | establishes the following set of configuration pragmas: | |
5267 | ||
5268 | * ``Task_Dispatching_Policy (FIFO_Within_Priorities)`` | |
5269 | ||
5270 | [RM D.2.2] Tasks are dispatched following a preemptive | |
5271 | priority-ordered scheduling policy. | |
5272 | ||
5273 | ||
5274 | * ``Locking_Policy (Ceiling_Locking)`` | |
5275 | ||
5276 | [RM D.3] While tasks and interrupts execute a protected action, they inherit | |
5277 | the ceiling priority of the corresponding protected object. | |
5278 | ||
5279 | ||
5280 | * ``Detect_Blocking`` | |
5281 | ||
5282 | This pragma forces the detection of potentially blocking operations within a | |
5283 | protected operation, and to raise Program_Error if that happens. | |
5284 | ||
5285 | plus the following set of restrictions: | |
5286 | ||
5287 | * ``Max_Entry_Queue_Length => 1`` | |
5288 | ||
5289 | No task can be queued on a protected entry. | |
5290 | ||
5291 | * ``Max_Protected_Entries => 1`` | |
5292 | ||
5293 | * ``Max_Task_Entries => 0`` | |
5294 | ||
5295 | No rendezvous statements are allowed. | |
5296 | ||
5297 | * ``No_Abort_Statements`` | |
5298 | ||
5299 | * ``No_Dynamic_Attachment`` | |
5300 | ||
5301 | * ``No_Dynamic_Priorities`` | |
5302 | ||
5303 | * ``No_Implicit_Heap_Allocations`` | |
5304 | ||
5305 | * ``No_Local_Protected_Objects`` | |
5306 | ||
5307 | * ``No_Local_Timing_Events`` | |
5308 | ||
5309 | * ``No_Protected_Type_Allocators`` | |
5310 | ||
5311 | * ``No_Relative_Delay`` | |
5312 | ||
5313 | * ``No_Requeue_Statements`` | |
5314 | ||
5315 | * ``No_Select_Statements`` | |
5316 | ||
5317 | * ``No_Specific_Termination_Handlers`` | |
5318 | ||
5319 | * ``No_Task_Allocators`` | |
5320 | ||
5321 | * ``No_Task_Hierarchy`` | |
5322 | ||
5323 | * ``No_Task_Termination`` | |
5324 | ||
5325 | * ``Simple_Barriers`` | |
5326 | ||
5327 | The Ravenscar profile also includes the following restrictions that specify | |
5328 | that there are no semantic dependences on the corresponding predefined | |
5329 | packages: | |
5330 | ||
5331 | * ``No_Dependence => Ada.Asynchronous_Task_Control`` | |
5332 | ||
5333 | * ``No_Dependence => Ada.Calendar`` | |
5334 | ||
5335 | * ``No_Dependence => Ada.Execution_Time.Group_Budget`` | |
5336 | ||
5337 | * ``No_Dependence => Ada.Execution_Time.Timers`` | |
5338 | ||
5339 | * ``No_Dependence => Ada.Task_Attributes`` | |
5340 | ||
5341 | * ``No_Dependence => System.Multiprocessors.Dispatching_Domains`` | |
5342 | ||
5343 | This set of configuration pragmas and restrictions correspond to the | |
5344 | definition of the 'Ravenscar Profile' for limited tasking, devised and | |
5345 | published by the :title:`International Real-Time Ada Workshop, 1997`. | |
5346 | A description is also available at | |
5347 | `http://www-users.cs.york.ac.uk/~burns/ravenscar.ps <http://www-users.cs.york.ac.uk/~burns/ravenscar.ps>`_. | |
5348 | ||
5349 | The original definition of the profile was revised at subsequent IRTAW | |
5350 | meetings. It has been included in the ISO | |
5351 | :title:`Guide for the Use of the Ada Programming Language in High Integrity Systems`, | |
5352 | and was made part of the Ada 2005 standard. | |
5353 | The formal definition given by | |
5354 | the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and | |
5355 | AI-305) available at | |
5356 | `http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt <http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt>`_ and | |
5357 | `http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt <http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt>`_. | |
5358 | ||
5359 | The above set is a superset of the restrictions provided by pragma | |
5360 | ``Profile (Restricted)``, it includes six additional restrictions | |
5361 | (``Simple_Barriers``, ``No_Select_Statements``, | |
5362 | ``No_Calendar``, ``No_Implicit_Heap_Allocations``, | |
5363 | ``No_Relative_Delay`` and ``No_Task_Termination``). This means | |
5364 | that pragma ``Profile (Ravenscar)``, like the pragma | |
5365 | ``Profile (Restricted)``, | |
5366 | automatically causes the use of a simplified, | |
5367 | more efficient version of the tasking run-time library. | |
5368 | ||
77a7ad42 | 5369 | * Pragma Profile (GNAT_Extended_Ravenscar) |
5370 | ||
5371 | This profile corresponds to a GNAT specific extension of the | |
5372 | Ravenscar profile. The profile may change in the future although | |
5373 | only in a compatible way: some restrictions may be removed or | |
5374 | relaxed. It is defined as a variation of the Ravenscar profile. | |
5375 | ||
5376 | The ``No_Implicit_Heap_Allocations`` restriction has been replaced | |
5377 | by ``No_Implicit_Task_Allocations`` and | |
5378 | ``No_Implicit_Protected_Object_Allocations``. | |
5379 | ||
5380 | The ``Simple_Barriers`` restriction has been replaced by | |
5381 | ``Pure_Barriers``. | |
5382 | ||
0c01a524 | 5383 | The ``Max_Protected_Entries``, ``Max_Entry_Queue_Length``, and |
5384 | ``No_Relative_Delay`` restrictions have been removed. | |
5385 | ||
8f09eafa | 5386 | * Pragma Profile (GNAT_Ravenscar_EDF) |
5387 | ||
5388 | This profile corresponds to the Ravenscar profile but using | |
5389 | EDF_Across_Priority as the Task_Scheduling_Policy. | |
5390 | ||
bf5dffd3 | 5391 | * Pragma Profile (Restricted) |
5392 | ||
5393 | This profile corresponds to the GNAT restricted run time. It | |
5394 | establishes the following set of restrictions: | |
5395 | ||
5396 | * ``No_Abort_Statements`` | |
5397 | * ``No_Entry_Queue`` | |
5398 | * ``No_Task_Hierarchy`` | |
5399 | * ``No_Task_Allocators`` | |
5400 | * ``No_Dynamic_Priorities`` | |
5401 | * ``No_Terminate_Alternatives`` | |
5402 | * ``No_Dynamic_Attachment`` | |
5403 | * ``No_Protected_Type_Allocators`` | |
5404 | * ``No_Local_Protected_Objects`` | |
5405 | * ``No_Requeue_Statements`` | |
5406 | * ``No_Task_Attributes_Package`` | |
5407 | * ``Max_Asynchronous_Select_Nesting = 0`` | |
5408 | * ``Max_Task_Entries = 0`` | |
5409 | * ``Max_Protected_Entries = 1`` | |
5410 | * ``Max_Select_Alternatives = 0`` | |
5411 | ||
5412 | This set of restrictions causes the automatic selection of a simplified | |
5413 | version of the run time that provides improved performance for the | |
5414 | limited set of tasking functionality permitted by this set of restrictions. | |
5415 | ||
5416 | * Pragma Profile (Rational) | |
5417 | ||
5418 | The Rational profile is intended to facilitate porting legacy code that | |
5419 | compiles with the Rational APEX compiler, even when the code includes non- | |
5420 | conforming Ada constructs. The profile enables the following three pragmas: | |
5421 | ||
5422 | * ``pragma Implicit_Packing`` | |
5423 | * ``pragma Overriding_Renamings`` | |
5424 | * ``pragma Use_VADS_Size`` | |
5425 | ||
5426 | ||
5427 | Pragma Profile_Warnings | |
5428 | ======================= | |
5429 | ||
5430 | Syntax: | |
5431 | ||
5432 | ||
5433 | .. code-block:: ada | |
5434 | ||
5435 | pragma Profile_Warnings (Ravenscar | Restricted | Rational); | |
5436 | ||
5437 | ||
5438 | This is an implementation-defined pragma that is similar in | |
e94434ba | 5439 | effect to ``pragma Profile`` except that instead of |
5440 | generating ``Restrictions`` pragmas, it generates | |
5441 | ``Restriction_Warnings`` pragmas. The result is that | |
bf5dffd3 | 5442 | violations of the profile generate warning messages instead |
5443 | of error messages. | |
5444 | ||
5445 | Pragma Propagate_Exceptions | |
5446 | =========================== | |
5447 | .. index:: Interfacing to C++ | |
5448 | ||
5449 | ||
5450 | Syntax: | |
5451 | ||
5452 | ||
5453 | .. code-block:: ada | |
5454 | ||
5455 | pragma Propagate_Exceptions; | |
5456 | ||
5457 | ||
5458 | This pragma is now obsolete and, other than generating a warning if warnings | |
5459 | on obsolescent features are enabled, is ignored. | |
5460 | It is retained for compatibility | |
5461 | purposes. It used to be used in connection with optimization of | |
5462 | a now-obsolete mechanism for implementation of exceptions. | |
5463 | ||
5464 | Pragma Provide_Shift_Operators | |
5465 | ============================== | |
5466 | .. index:: Shift operators | |
5467 | ||
5468 | ||
5469 | Syntax: | |
5470 | ||
5471 | ||
5472 | .. code-block:: ada | |
5473 | ||
5474 | pragma Provide_Shift_Operators (integer_first_subtype_LOCAL_NAME); | |
5475 | ||
5476 | ||
5477 | This pragma can be applied to a first subtype local name that specifies | |
5478 | either an unsigned or signed type. It has the effect of providing the | |
5479 | five shift operators (Shift_Left, Shift_Right, Shift_Right_Arithmetic, | |
5480 | Rotate_Left and Rotate_Right) for the given type. It is similar to | |
5481 | including the function declarations for these five operators, together | |
5482 | with the pragma Import (Intrinsic, ...) statements. | |
5483 | ||
5484 | Pragma Psect_Object | |
5485 | =================== | |
5486 | ||
5487 | Syntax: | |
5488 | ||
5489 | ||
5490 | :: | |
5491 | ||
5492 | pragma Psect_Object ( | |
5493 | [Internal =>] LOCAL_NAME, | |
5494 | [, [External =>] EXTERNAL_SYMBOL] | |
5495 | [, [Size =>] EXTERNAL_SYMBOL]); | |
5496 | ||
5497 | EXTERNAL_SYMBOL ::= | |
5498 | IDENTIFIER | |
5499 | | static_string_EXPRESSION | |
5500 | ||
5501 | ||
e94434ba | 5502 | This pragma is identical in effect to pragma ``Common_Object``. |
bf5dffd3 | 5503 | |
39adf1e6 | 5504 | .. _Pragma-Pure_Function: |
5505 | ||
bf5dffd3 | 5506 | Pragma Pure_Function |
5507 | ==================== | |
5508 | ||
5509 | Syntax: | |
5510 | ||
5511 | ||
5512 | :: | |
5513 | ||
5514 | pragma Pure_Function ([Entity =>] function_LOCAL_NAME); | |
5515 | ||
5516 | ||
5517 | This pragma appears in the same declarative part as a function | |
5518 | declaration (or a set of function declarations if more than one | |
5519 | overloaded declaration exists, in which case the pragma applies | |
e94434ba | 5520 | to all entities). It specifies that the function ``Entity`` is |
bf5dffd3 | 5521 | to be considered pure for the purposes of code generation. This means |
5522 | that the compiler can assume that there are no side effects, and | |
5523 | in particular that two calls with identical arguments produce the | |
5524 | same result. It also means that the function can be used in an | |
5525 | address clause. | |
5526 | ||
5527 | Note that, quite deliberately, there are no static checks to try | |
e94434ba | 5528 | to ensure that this promise is met, so ``Pure_Function`` can be used |
bf5dffd3 | 5529 | with functions that are conceptually pure, even if they do modify |
5530 | global variables. For example, a square root function that is | |
5531 | instrumented to count the number of times it is called is still | |
5532 | conceptually pure, and can still be optimized, even though it | |
5533 | modifies a global variable (the count). Memo functions are another | |
5534 | example (where a table of previous calls is kept and consulted to | |
5535 | avoid re-computation). | |
5536 | ||
5537 | Note also that the normal rules excluding optimization of subprograms | |
5538 | in pure units (when parameter types are descended from System.Address, | |
5539 | or when the full view of a parameter type is limited), do not apply | |
5540 | for the Pure_Function case. If you explicitly specify Pure_Function, | |
5541 | the compiler may optimize away calls with identical arguments, and | |
5542 | if that results in unexpected behavior, the proper action is not to | |
5543 | use the pragma for subprograms that are not (conceptually) pure. | |
5544 | ||
e94434ba | 5545 | Note: Most functions in a ``Pure`` package are automatically pure, and |
5546 | there is no need to use pragma ``Pure_Function`` for such functions. One | |
bf5dffd3 | 5547 | exception is any function that has at least one formal of type |
e94434ba | 5548 | ``System.Address`` or a type derived from it. Such functions are not |
bf5dffd3 | 5549 | considered pure by default, since the compiler assumes that the |
e94434ba | 5550 | ``Address`` parameter may be functioning as a pointer and that the |
bf5dffd3 | 5551 | referenced data may change even if the address value does not. |
5552 | Similarly, imported functions are not considered to be pure by default, | |
5553 | since there is no way of checking that they are in fact pure. The use | |
e94434ba | 5554 | of pragma ``Pure_Function`` for such a function will override these default |
bf5dffd3 | 5555 | assumption, and cause the compiler to treat a designated subprogram as pure |
5556 | in these cases. | |
5557 | ||
e94434ba | 5558 | Note: If pragma ``Pure_Function`` is applied to a renamed function, it |
bf5dffd3 | 5559 | applies to the underlying renamed function. This can be used to |
5560 | disambiguate cases of overloading where some but not all functions | |
5561 | in a set of overloaded functions are to be designated as pure. | |
5562 | ||
e94434ba | 5563 | If pragma ``Pure_Function`` is applied to a library-level function, the |
bf5dffd3 | 5564 | function is also considered pure from an optimization point of view, but the |
5565 | unit is not a Pure unit in the categorization sense. So for example, a function | |
e94434ba | 5566 | thus marked is free to ``with`` non-pure units. |
bf5dffd3 | 5567 | |
5568 | Pragma Rational | |
5569 | =============== | |
5570 | ||
5571 | Syntax: | |
5572 | ||
5573 | ||
5574 | .. code-block:: ada | |
5575 | ||
5576 | pragma Rational; | |
5577 | ||
5578 | ||
5579 | This pragma is considered obsolescent, but is retained for | |
5580 | compatibility purposes. It is equivalent to: | |
5581 | ||
5582 | ||
5583 | .. code-block:: ada | |
5584 | ||
5585 | pragma Profile (Rational); | |
5586 | ||
5587 | ||
5588 | Pragma Ravenscar | |
5589 | ================ | |
5590 | ||
5591 | Syntax: | |
5592 | ||
5593 | ||
5594 | .. code-block:: ada | |
5595 | ||
5596 | pragma Ravenscar; | |
5597 | ||
5598 | ||
5599 | This pragma is considered obsolescent, but is retained for | |
5600 | compatibility purposes. It is equivalent to: | |
5601 | ||
5602 | ||
5603 | .. code-block:: ada | |
5604 | ||
5605 | pragma Profile (Ravenscar); | |
5606 | ||
5607 | ||
e94434ba | 5608 | which is the preferred method of setting the ``Ravenscar`` profile. |
bf5dffd3 | 5609 | |
39adf1e6 | 5610 | .. _Pragma-Refined_Depends: |
5611 | ||
bf5dffd3 | 5612 | Pragma Refined_Depends |
5613 | ====================== | |
5614 | ||
d5dcec30 | 5615 | Syntax: |
5616 | ||
5617 | .. code-block:: ada | |
5618 | ||
5619 | pragma Refined_Depends (DEPENDENCY_RELATION); | |
5620 | ||
5621 | DEPENDENCY_RELATION ::= | |
5622 | null | |
5623 | | (DEPENDENCY_CLAUSE {, DEPENDENCY_CLAUSE}) | |
5624 | ||
5625 | DEPENDENCY_CLAUSE ::= | |
5626 | OUTPUT_LIST =>[+] INPUT_LIST | |
5627 | | NULL_DEPENDENCY_CLAUSE | |
5628 | ||
5629 | NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST | |
5630 | ||
5631 | OUTPUT_LIST ::= OUTPUT | (OUTPUT {, OUTPUT}) | |
5632 | ||
5633 | INPUT_LIST ::= null | INPUT | (INPUT {, INPUT}) | |
5634 | ||
5635 | OUTPUT ::= NAME | FUNCTION_RESULT | |
5636 | INPUT ::= NAME | |
5637 | ||
5638 | where FUNCTION_RESULT is a function Result attribute_reference | |
5639 | ||
e94434ba | 5640 | For the semantics of this pragma, see the entry for aspect ``Refined_Depends`` in |
d5dcec30 | 5641 | the SPARK 2014 Reference Manual, section 6.1.5. |
bf5dffd3 | 5642 | |
39adf1e6 | 5643 | .. _Pragma-Refined_Global: |
5644 | ||
bf5dffd3 | 5645 | Pragma Refined_Global |
5646 | ===================== | |
5647 | ||
d5dcec30 | 5648 | Syntax: |
5649 | ||
5650 | .. code-block:: ada | |
5651 | ||
5652 | pragma Refined_Global (GLOBAL_SPECIFICATION); | |
5653 | ||
5654 | GLOBAL_SPECIFICATION ::= | |
5655 | null | |
5656 | | (GLOBAL_LIST) | |
5657 | | (MODED_GLOBAL_LIST {, MODED_GLOBAL_LIST}) | |
5658 | ||
5659 | MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST | |
5660 | ||
5661 | MODE_SELECTOR ::= In_Out | Input | Output | Proof_In | |
5662 | GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM {, GLOBAL_ITEM}) | |
5663 | GLOBAL_ITEM ::= NAME | |
5664 | ||
e94434ba | 5665 | For the semantics of this pragma, see the entry for aspect ``Refined_Global`` in |
d5dcec30 | 5666 | the SPARK 2014 Reference Manual, section 6.1.4. |
bf5dffd3 | 5667 | |
39adf1e6 | 5668 | .. _Pragma-Refined_Post: |
5669 | ||
bf5dffd3 | 5670 | Pragma Refined_Post |
5671 | =================== | |
5672 | ||
d5dcec30 | 5673 | Syntax: |
5674 | ||
5675 | .. code-block:: ada | |
5676 | ||
5677 | pragma Refined_Post (boolean_EXPRESSION); | |
5678 | ||
e94434ba | 5679 | For the semantics of this pragma, see the entry for aspect ``Refined_Post`` in |
d5dcec30 | 5680 | the SPARK 2014 Reference Manual, section 7.2.7. |
bf5dffd3 | 5681 | |
39adf1e6 | 5682 | .. _Pragma-Refined_State: |
5683 | ||
bf5dffd3 | 5684 | Pragma Refined_State |
5685 | ==================== | |
5686 | ||
d5dcec30 | 5687 | Syntax: |
5688 | ||
5689 | .. code-block:: ada | |
5690 | ||
5691 | pragma Refined_State (REFINEMENT_LIST); | |
5692 | ||
5693 | REFINEMENT_LIST ::= | |
5694 | (REFINEMENT_CLAUSE {, REFINEMENT_CLAUSE}) | |
5695 | ||
5696 | REFINEMENT_CLAUSE ::= state_NAME => CONSTITUENT_LIST | |
5697 | ||
5698 | CONSTITUENT_LIST ::= | |
5699 | null | |
5700 | | CONSTITUENT | |
5701 | | (CONSTITUENT {, CONSTITUENT}) | |
5702 | ||
5703 | CONSTITUENT ::= object_NAME | state_NAME | |
5704 | ||
e94434ba | 5705 | For the semantics of this pragma, see the entry for aspect ``Refined_State`` in |
d5dcec30 | 5706 | the SPARK 2014 Reference Manual, section 7.2.2. |
bf5dffd3 | 5707 | |
5708 | Pragma Relative_Deadline | |
5709 | ======================== | |
5710 | ||
5711 | Syntax: | |
5712 | ||
5713 | ||
5714 | .. code-block:: ada | |
5715 | ||
5716 | pragma Relative_Deadline (time_span_EXPRESSION); | |
5717 | ||
5718 | ||
5719 | This pragma is standard in Ada 2005, but is available in all earlier | |
5720 | versions of Ada as an implementation-defined pragma. | |
5721 | See Ada 2012 Reference Manual for details. | |
5722 | ||
39adf1e6 | 5723 | .. _Pragma-Remote_Access_Type: |
5724 | ||
bf5dffd3 | 5725 | Pragma Remote_Access_Type |
5726 | ========================= | |
5727 | ||
5728 | Syntax: | |
5729 | ||
5730 | ||
5731 | :: | |
5732 | ||
5733 | pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME); | |
5734 | ||
5735 | ||
5736 | This pragma appears in the formal part of a generic declaration. | |
5737 | It specifies an exception to the RM rule from E.2.2(17/2), which forbids | |
5738 | the use of a remote access to class-wide type as actual for a formal | |
5739 | access type. | |
5740 | ||
e94434ba | 5741 | When this pragma applies to a formal access type ``Entity``, that |
bf5dffd3 | 5742 | type is treated as a remote access to class-wide type in the generic. |
5743 | It must be a formal general access type, and its designated type must | |
5744 | be the class-wide type of a formal tagged limited private type from the | |
5745 | same generic declaration. | |
5746 | ||
5747 | In the generic unit, the formal type is subject to all restrictions | |
5748 | pertaining to remote access to class-wide types. At instantiation, the | |
5749 | actual type must be a remote access to class-wide type. | |
5750 | ||
5751 | Pragma Restricted_Run_Time | |
5752 | ========================== | |
5753 | ||
5754 | Syntax: | |
5755 | ||
5756 | ||
5757 | .. code-block:: ada | |
5758 | ||
5759 | pragma Restricted_Run_Time; | |
5760 | ||
5761 | ||
5762 | This pragma is considered obsolescent, but is retained for | |
5763 | compatibility purposes. It is equivalent to: | |
5764 | ||
5765 | ||
5766 | .. code-block:: ada | |
5767 | ||
5768 | pragma Profile (Restricted); | |
5769 | ||
5770 | ||
5771 | which is the preferred method of setting the restricted run time | |
5772 | profile. | |
5773 | ||
5774 | Pragma Restriction_Warnings | |
5775 | =========================== | |
5776 | ||
5777 | Syntax: | |
5778 | ||
5779 | ||
5780 | :: | |
5781 | ||
5782 | pragma Restriction_Warnings | |
5783 | (restriction_IDENTIFIER {, restriction_IDENTIFIER}); | |
5784 | ||
5785 | ||
5786 | This pragma allows a series of restriction identifiers to be | |
5787 | specified (the list of allowed identifiers is the same as for | |
e94434ba | 5788 | pragma ``Restrictions``). For each of these identifiers |
bf5dffd3 | 5789 | the compiler checks for violations of the restriction, but |
5790 | generates a warning message rather than an error message | |
5791 | if the restriction is violated. | |
5792 | ||
5793 | One use of this is in situations where you want to know | |
5794 | about violations of a restriction, but you want to ignore some of | |
5795 | these violations. Consider this example, where you want to set | |
5796 | Ada_95 mode and enable style checks, but you want to know about | |
5797 | any other use of implementation pragmas: | |
5798 | ||
5799 | ||
5800 | .. code-block:: ada | |
5801 | ||
5802 | pragma Restriction_Warnings (No_Implementation_Pragmas); | |
5803 | pragma Warnings (Off, "violation of No_Implementation_Pragmas"); | |
5804 | pragma Ada_95; | |
5805 | pragma Style_Checks ("2bfhkM160"); | |
5806 | pragma Warnings (On, "violation of No_Implementation_Pragmas"); | |
5807 | ||
5808 | ||
5809 | By including the above lines in a configuration pragmas file, | |
5810 | the Ada_95 and Style_Checks pragmas are accepted without | |
5811 | generating a warning, but any other use of implementation | |
5812 | defined pragmas will cause a warning to be generated. | |
5813 | ||
5814 | Pragma Reviewable | |
5815 | ================= | |
5816 | ||
5817 | Syntax: | |
5818 | ||
5819 | ||
5820 | .. code-block:: ada | |
5821 | ||
5822 | pragma Reviewable; | |
5823 | ||
5824 | ||
5825 | This pragma is an RM-defined standard pragma, but has no effect on the | |
5826 | program being compiled, or on the code generated for the program. | |
5827 | ||
5828 | To obtain the required output specified in RM H.3.1, the compiler must be | |
5829 | run with various special switches as follows: | |
5830 | ||
5831 | * *Where compiler-generated run-time checks remain* | |
5832 | ||
5833 | The switch *-gnatGL* | |
5834 | may be used to list the expanded code in pseudo-Ada form. | |
5835 | Runtime checks show up in the listing either as explicit | |
5836 | checks or operators marked with {} to indicate a check is present. | |
5837 | ||
5838 | ||
5839 | * *An identification of known exceptions at compile time* | |
5840 | ||
5841 | If the program is compiled with *-gnatwa*, | |
5842 | the compiler warning messages will indicate all cases where the compiler | |
5843 | detects that an exception is certain to occur at run time. | |
5844 | ||
5845 | ||
5846 | * *Possible reads of uninitialized variables* | |
5847 | ||
5848 | The compiler warns of many such cases, but its output is incomplete. | |
5849 | ||
5850 | .. only:: PRO or GPL | |
5851 | ||
5852 | The CodePeer analysis tool | |
5853 | may be used to obtain a comprehensive list of all | |
5854 | possible points at which uninitialized data may be read. | |
5855 | ||
5856 | .. only:: FSF | |
5857 | ||
5858 | A supplemental static analysis tool | |
5859 | may be used to obtain a comprehensive list of all | |
5860 | possible points at which uninitialized data may be read. | |
5861 | ||
5862 | ||
5863 | * *Where run-time support routines are implicitly invoked* | |
5864 | ||
5865 | In the output from *-gnatGL*, | |
5866 | run-time calls are explicitly listed as calls to the relevant | |
5867 | run-time routine. | |
5868 | ||
5869 | ||
5870 | * *Object code listing* | |
5871 | ||
5872 | This may be obtained either by using the *-S* switch, | |
5873 | or the objdump utility. | |
5874 | ||
5875 | ||
5876 | * *Constructs known to be erroneous at compile time* | |
5877 | ||
5878 | These are identified by warnings issued by the compiler (use *-gnatwa*). | |
5879 | ||
5880 | ||
5881 | * *Stack usage information* | |
5882 | ||
5883 | Static stack usage data (maximum per-subprogram) can be obtained via the | |
5884 | *-fstack-usage* switch to the compiler. | |
5885 | Dynamic stack usage data (per task) can be obtained via the *-u* switch | |
5886 | to gnatbind | |
5887 | ||
5888 | .. only:: PRO or GPL | |
5889 | ||
5890 | The gnatstack utility | |
5891 | can be used to provide additional information on stack usage. | |
5892 | ||
5893 | ||
5894 | * *Object code listing of entire partition* | |
5895 | ||
5896 | This can be obtained by compiling the partition with *-S*, | |
5897 | or by applying objdump | |
5898 | to all the object files that are part of the partition. | |
5899 | ||
5900 | ||
5901 | * *A description of the run-time model* | |
5902 | ||
5903 | The full sources of the run-time are available, and the documentation of | |
5904 | these routines describes how these run-time routines interface to the | |
5905 | underlying operating system facilities. | |
5906 | ||
5907 | ||
5908 | * *Control and data-flow information* | |
5909 | ||
5910 | .. only:: PRO or GPL | |
5911 | ||
5912 | The CodePeer tool | |
5913 | may be used to obtain complete control and data-flow information, as well as | |
5914 | comprehensive messages identifying possible problems based on this | |
5915 | information. | |
5916 | ||
5917 | .. only:: FSF | |
5918 | ||
5919 | A supplemental static analysis tool | |
5920 | may be used to obtain complete control and data-flow information, as well as | |
5921 | comprehensive messages identifying possible problems based on this | |
5922 | information. | |
5923 | ||
0c01a524 | 5924 | .. _Pragma-Secondary_Stack_Size: |
5925 | ||
5926 | Pragma Secondary_Stack_Size | |
5927 | =========================== | |
5928 | ||
5929 | Syntax: | |
5930 | ||
5931 | .. code-block:: ada | |
5932 | ||
5933 | pragma Secondary_Stack_Size (integer_EXPRESSION); | |
5934 | ||
8f09eafa | 5935 | This pragma appears within the task definition of a single task declaration |
e94434ba | 5936 | or a task type declaration (like pragma ``Storage_Size``) and applies to all |
8f09eafa | 5937 | task objects of that type. The argument specifies the size of the secondary |
0c01a524 | 5938 | stack to be used by these task objects, and must be of an integer type. The |
8f09eafa | 5939 | secondary stack is used to handle functions that return a variable-sized |
0c01a524 | 5940 | result, for example a function returning an unconstrained String. |
5941 | ||
5942 | Note this pragma only applies to targets using fixed secondary stacks, like | |
8f09eafa | 5943 | VxWorks 653 and bare board targets, where a fixed block for the |
0c01a524 | 5944 | secondary stack is allocated from the primary stack of the task. By default, |
5945 | these targets assign a percentage of the primary stack for the secondary stack, | |
e94434ba | 5946 | as defined by ``System.Parameter.Sec_Stack_Percentage``. With this pragma, |
5947 | an ``integer_EXPRESSION`` of bytes is assigned from the primary stack instead. | |
0c01a524 | 5948 | |
8f09eafa | 5949 | For most targets, the pragma does not apply as the secondary stack grows on |
5950 | demand: allocated as a chain of blocks in the heap. The default size of these | |
e94434ba | 5951 | blocks can be modified via the :switch:`-D` binder option as described in |
0c01a524 | 5952 | :title:`GNAT User's Guide`. |
5953 | ||
8f09eafa | 5954 | Note that no check is made to see if the secondary stack can fit inside the |
0c01a524 | 5955 | primary stack. |
5956 | ||
e94434ba | 5957 | Note the pragma cannot appear when the restriction ``No_Secondary_Stack`` |
0c01a524 | 5958 | is in effect. |
bf5dffd3 | 5959 | |
5960 | Pragma Share_Generic | |
5961 | ==================== | |
5962 | ||
5963 | Syntax: | |
5964 | ||
5965 | ||
5966 | :: | |
5967 | ||
5968 | pragma Share_Generic (GNAME {, GNAME}); | |
5969 | ||
5970 | GNAME ::= generic_unit_NAME | generic_instance_NAME | |
5971 | ||
5972 | ||
5973 | This pragma is provided for compatibility with Dec Ada 83. It has | |
e94434ba | 5974 | no effect in GNAT (which does not implement shared generics), other |
bf5dffd3 | 5975 | than to check that the given names are all names of generic units or |
5976 | generic instances. | |
5977 | ||
39adf1e6 | 5978 | .. _Pragma-Shared: |
5979 | ||
bf5dffd3 | 5980 | Pragma Shared |
5981 | ============= | |
5982 | ||
5983 | This pragma is provided for compatibility with Ada 83. The syntax and | |
5984 | semantics are identical to pragma Atomic. | |
5985 | ||
5986 | Pragma Short_Circuit_And_Or | |
5987 | =========================== | |
5988 | ||
5989 | Syntax: | |
5990 | ||
5991 | ||
5992 | .. code-block:: ada | |
5993 | ||
5994 | pragma Short_Circuit_And_Or; | |
5995 | ||
5996 | ||
5997 | This configuration pragma causes any occurrence of the AND operator applied to | |
5998 | operands of type Standard.Boolean to be short-circuited (i.e. the AND operator | |
5999 | is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This | |
6000 | may be useful in the context of certification protocols requiring the use of | |
6001 | short-circuited logical operators. If this configuration pragma occurs locally | |
6002 | within the file being compiled, it applies only to the file being compiled. | |
6003 | There is no requirement that all units in a partition use this option. | |
6004 | ||
6005 | Pragma Short_Descriptors | |
6006 | ======================== | |
6007 | ||
6008 | Syntax: | |
6009 | ||
6010 | ||
6011 | .. code-block:: ada | |
6012 | ||
6013 | pragma Short_Descriptors | |
6014 | ||
6015 | ||
6016 | This pragma is provided for compatibility with other Ada implementations. It | |
6017 | is recognized but ignored by all current versions of GNAT. | |
6018 | ||
39adf1e6 | 6019 | .. _Pragma-Simple_Storage_Pool_Type: |
6020 | ||
bf5dffd3 | 6021 | Pragma Simple_Storage_Pool_Type |
6022 | =============================== | |
6023 | .. index:: Storage pool, simple | |
6024 | ||
6025 | .. index:: Simple storage pool | |
6026 | ||
6027 | Syntax: | |
6028 | ||
6029 | ||
6030 | .. code-block:: ada | |
6031 | ||
6032 | pragma Simple_Storage_Pool_Type (type_LOCAL_NAME); | |
6033 | ||
6034 | ||
6035 | A type can be established as a 'simple storage pool type' by applying | |
e94434ba | 6036 | the representation pragma ``Simple_Storage_Pool_Type`` to the type. |
bf5dffd3 | 6037 | A type named in the pragma must be a library-level immutably limited record |
6038 | type or limited tagged type declared immediately within a package declaration. | |
6039 | The type can also be a limited private type whose full type is allowed as | |
6040 | a simple storage pool type. | |
6041 | ||
e94434ba | 6042 | For a simple storage pool type ``SSP``, nonabstract primitive subprograms |
6043 | ``Allocate``, ``Deallocate``, and ``Storage_Size`` can be declared that | |
bf5dffd3 | 6044 | are subtype conformant with the following subprogram declarations: |
6045 | ||
6046 | ||
6047 | .. code-block:: ada | |
6048 | ||
6049 | procedure Allocate | |
6050 | (Pool : in out SSP; | |
6051 | Storage_Address : out System.Address; | |
6052 | Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; | |
6053 | Alignment : System.Storage_Elements.Storage_Count); | |
6054 | ||
6055 | procedure Deallocate | |
6056 | (Pool : in out SSP; | |
6057 | Storage_Address : System.Address; | |
6058 | Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; | |
6059 | Alignment : System.Storage_Elements.Storage_Count); | |
6060 | ||
6061 | function Storage_Size (Pool : SSP) | |
6062 | return System.Storage_Elements.Storage_Count; | |
6063 | ||
6064 | ||
e94434ba | 6065 | Procedure ``Allocate`` must be declared, whereas ``Deallocate`` and |
6066 | ``Storage_Size`` are optional. If ``Deallocate`` is not declared, then | |
bf5dffd3 | 6067 | applying an unchecked deallocation has no effect other than to set its actual |
e94434ba | 6068 | parameter to null. If ``Storage_Size`` is not declared, then the |
6069 | ``Storage_Size`` attribute applied to an access type associated with | |
bf5dffd3 | 6070 | a pool object of type SSP returns zero. Additional operations can be declared |
6071 | for a simple storage pool type (such as for supporting a mark/release | |
6072 | storage-management discipline). | |
6073 | ||
6074 | An object of a simple storage pool type can be associated with an access | |
6075 | type by specifying the attribute | |
6076 | :ref:`Simple_Storage_Pool <Attribute_Simple_Storage_Pool>`. For example: | |
6077 | ||
6078 | ||
6079 | .. code-block:: ada | |
6080 | ||
6081 | My_Pool : My_Simple_Storage_Pool_Type; | |
6082 | ||
6083 | type Acc is access My_Data_Type; | |
6084 | ||
6085 | for Acc'Simple_Storage_Pool use My_Pool; | |
6086 | ||
6087 | ||
6088 | ||
6089 | See attribute :ref:`Simple_Storage_Pool <Attribute_Simple_Storage_Pool>` | |
6090 | for further details. | |
6091 | ||
6092 | .. _Pragma_Source_File_Name: | |
6093 | ||
6094 | Pragma Source_File_Name | |
6095 | ======================= | |
6096 | ||
6097 | Syntax: | |
6098 | ||
6099 | ||
6100 | :: | |
6101 | ||
6102 | pragma Source_File_Name ( | |
6103 | [Unit_Name =>] unit_NAME, | |
6104 | Spec_File_Name => STRING_LITERAL, | |
6105 | [Index => INTEGER_LITERAL]); | |
6106 | ||
6107 | pragma Source_File_Name ( | |
6108 | [Unit_Name =>] unit_NAME, | |
6109 | Body_File_Name => STRING_LITERAL, | |
6110 | [Index => INTEGER_LITERAL]); | |
6111 | ||
6112 | ||
6113 | Use this to override the normal naming convention. It is a configuration | |
6114 | pragma, and so has the usual applicability of configuration pragmas | |
6115 | (i.e., it applies to either an entire partition, or to all units in a | |
6116 | compilation, or to a single unit, depending on how it is used. | |
e94434ba | 6117 | ``unit_name`` is mapped to ``file_name_literal``. The identifier for |
bf5dffd3 | 6118 | the second argument is required, and indicates whether this is the file |
6119 | name for the spec or for the body. | |
6120 | ||
6121 | The optional Index argument should be used when a file contains multiple | |
e94434ba | 6122 | units, and when you do not want to use ``gnatchop`` to separate then |
bf5dffd3 | 6123 | into multiple files (which is the recommended procedure to limit the |
6124 | number of recompilations that are needed when some sources change). | |
6125 | For instance, if the source file :file:`source.ada` contains | |
6126 | ||
6127 | ||
6128 | .. code-block:: ada | |
6129 | ||
6130 | package B is | |
6131 | ... | |
6132 | end B; | |
6133 | ||
6134 | with B; | |
6135 | procedure A is | |
6136 | begin | |
6137 | .. | |
6138 | end A; | |
6139 | ||
6140 | ||
6141 | you could use the following configuration pragmas: | |
6142 | ||
6143 | ||
6144 | .. code-block:: ada | |
6145 | ||
6146 | pragma Source_File_Name | |
6147 | (B, Spec_File_Name => "source.ada", Index => 1); | |
6148 | pragma Source_File_Name | |
6149 | (A, Body_File_Name => "source.ada", Index => 2); | |
6150 | ||
6151 | ||
e94434ba | 6152 | Note that the ``gnatname`` utility can also be used to generate those |
bf5dffd3 | 6153 | configuration pragmas. |
6154 | ||
e94434ba | 6155 | Another form of the ``Source_File_Name`` pragma allows |
bf5dffd3 | 6156 | the specification of patterns defining alternative file naming schemes |
6157 | to apply to all files. | |
6158 | ||
6159 | ||
6160 | :: | |
6161 | ||
6162 | pragma Source_File_Name | |
6163 | ( [Spec_File_Name =>] STRING_LITERAL | |
6164 | [,[Casing =>] CASING_SPEC] | |
6165 | [,[Dot_Replacement =>] STRING_LITERAL]); | |
6166 | ||
6167 | pragma Source_File_Name | |
6168 | ( [Body_File_Name =>] STRING_LITERAL | |
6169 | [,[Casing =>] CASING_SPEC] | |
6170 | [,[Dot_Replacement =>] STRING_LITERAL]); | |
6171 | ||
6172 | pragma Source_File_Name | |
6173 | ( [Subunit_File_Name =>] STRING_LITERAL | |
6174 | [,[Casing =>] CASING_SPEC] | |
6175 | [,[Dot_Replacement =>] STRING_LITERAL]); | |
6176 | ||
6177 | CASING_SPEC ::= Lowercase | Uppercase | Mixedcase | |
6178 | ||
6179 | ||
6180 | The first argument is a pattern that contains a single asterisk indicating | |
6181 | the point at which the unit name is to be inserted in the pattern string | |
6182 | to form the file name. The second argument is optional. If present it | |
6183 | specifies the casing of the unit name in the resulting file name string. | |
6184 | The default is lower case. Finally the third argument allows for systematic | |
6185 | replacement of any dots in the unit name by the specified string literal. | |
6186 | ||
6187 | Note that Source_File_Name pragmas should not be used if you are using | |
6188 | project files. The reason for this rule is that the project manager is not | |
6189 | aware of these pragmas, and so other tools that use the projet file would not | |
6190 | be aware of the intended naming conventions. If you are using project files, | |
6191 | file naming is controlled by Source_File_Name_Project pragmas, which are | |
6192 | usually supplied automatically by the project manager. A pragma | |
6193 | Source_File_Name cannot appear after a :ref:`Pragma_Source_File_Name_Project`. | |
6194 | ||
e94434ba | 6195 | For more details on the use of the ``Source_File_Name`` pragma, see the |
6196 | sections on ``Using Other File Names`` and `Alternative File Naming Schemes' | |
bf5dffd3 | 6197 | in the :title:`GNAT User's Guide`. |
6198 | ||
6199 | .. _Pragma_Source_File_Name_Project: | |
6200 | ||
6201 | Pragma Source_File_Name_Project | |
6202 | =============================== | |
6203 | ||
6204 | This pragma has the same syntax and semantics as pragma Source_File_Name. | |
4a7c3b2f | 6205 | It is only allowed as a stand-alone configuration pragma. |
bf5dffd3 | 6206 | It cannot appear after a :ref:`Pragma_Source_File_Name`, and |
6207 | most importantly, once pragma Source_File_Name_Project appears, | |
6208 | no further Source_File_Name pragmas are allowed. | |
6209 | ||
6210 | The intention is that Source_File_Name_Project pragmas are always | |
6211 | generated by the Project Manager in a manner consistent with the naming | |
6212 | specified in a project file, and when naming is controlled in this manner, | |
6213 | it is not permissible to attempt to modify this naming scheme using | |
6214 | Source_File_Name or Source_File_Name_Project pragmas (which would not be | |
6215 | known to the project manager). | |
6216 | ||
6217 | Pragma Source_Reference | |
6218 | ======================= | |
6219 | ||
6220 | Syntax: | |
6221 | ||
6222 | ||
6223 | .. code-block:: ada | |
6224 | ||
6225 | pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL); | |
6226 | ||
6227 | ||
6228 | This pragma must appear as the first line of a source file. | |
e94434ba | 6229 | ``integer_literal`` is the logical line number of the line following |
bf5dffd3 | 6230 | the pragma line (for use in error messages and debugging |
e94434ba | 6231 | information). ``string_literal`` is a static string constant that |
bf5dffd3 | 6232 | specifies the file name to be used in error messages and debugging |
e94434ba | 6233 | information. This is most notably used for the output of ``gnatchop`` |
bf5dffd3 | 6234 | with the *-r* switch, to make sure that the original unchopped |
6235 | source file is the one referred to. | |
6236 | ||
6237 | The second argument must be a string literal, it cannot be a static | |
6238 | string expression other than a string literal. This is because its value | |
6239 | is needed for error messages issued by all phases of the compiler. | |
6240 | ||
39adf1e6 | 6241 | .. _Pragma-SPARK_Mode: |
6242 | ||
bf5dffd3 | 6243 | Pragma SPARK_Mode |
6244 | ================= | |
6245 | ||
6246 | Syntax: | |
6247 | ||
6248 | ||
6249 | :: | |
6250 | ||
6251 | pragma SPARK_Mode [(On | Off)] ; | |
6252 | ||
6253 | ||
6254 | In general a program can have some parts that are in SPARK 2014 (and | |
6255 | follow all the rules in the SPARK Reference Manual), and some parts | |
6256 | that are full Ada 2012. | |
6257 | ||
6258 | The SPARK_Mode pragma is used to identify which parts are in SPARK | |
6259 | 2014 (by default programs are in full Ada). The SPARK_Mode pragma can | |
6260 | be used in the following places: | |
6261 | ||
6262 | ||
6263 | * | |
6264 | As a configuration pragma, in which case it sets the default mode for | |
6265 | all units compiled with this pragma. | |
6266 | ||
6267 | * | |
6268 | Immediately following a library-level subprogram spec | |
6269 | ||
6270 | * | |
6271 | Immediately within a library-level package body | |
6272 | ||
6273 | * | |
e94434ba | 6274 | Immediately following the ``private`` keyword of a library-level |
bf5dffd3 | 6275 | package spec |
6276 | ||
6277 | * | |
e94434ba | 6278 | Immediately following the ``begin`` keyword of a library-level |
bf5dffd3 | 6279 | package body |
6280 | ||
6281 | * | |
6282 | Immediately within a library-level subprogram body | |
6283 | ||
6284 | ||
6285 | Normally a subprogram or package spec/body inherits the current mode | |
6286 | that is active at the point it is declared. But this can be overridden | |
6287 | by pragma within the spec or body as above. | |
6288 | ||
6289 | The basic consistency rule is that you can't turn SPARK_Mode back | |
e94434ba | 6290 | ``On``, once you have explicitly (with a pragma) turned if |
6291 | ``Off``. So the following rules apply: | |
bf5dffd3 | 6292 | |
e94434ba | 6293 | If a subprogram spec has SPARK_Mode ``Off``, then the body must |
6294 | also have SPARK_Mode ``Off``. | |
bf5dffd3 | 6295 | |
6296 | For a package, we have four parts: | |
6297 | ||
6298 | * | |
6299 | the package public declarations | |
6300 | * | |
6301 | the package private part | |
6302 | * | |
6303 | the body of the package | |
6304 | * | |
e94434ba | 6305 | the elaboration code after ``begin`` |
bf5dffd3 | 6306 | |
6307 | For a package, the rule is that if you explicitly turn SPARK_Mode | |
e94434ba | 6308 | ``Off`` for any part, then all the following parts must have |
6309 | SPARK_Mode ``Off``. Note that this may require repeating a pragma | |
6310 | SPARK_Mode (``Off``) in the body. For example, if we have a | |
6311 | configuration pragma SPARK_Mode (``On``) that turns the mode on by | |
bf5dffd3 | 6312 | default everywhere, and one particular package spec has pragma |
e94434ba | 6313 | SPARK_Mode (``Off``), then that pragma will need to be repeated in |
bf5dffd3 | 6314 | the package body. |
6315 | ||
6316 | Pragma Static_Elaboration_Desired | |
6317 | ================================= | |
6318 | ||
6319 | Syntax: | |
6320 | ||
6321 | ||
6322 | .. code-block:: ada | |
6323 | ||
6324 | pragma Static_Elaboration_Desired; | |
6325 | ||
6326 | ||
6327 | This pragma is used to indicate that the compiler should attempt to initialize | |
6328 | statically the objects declared in the library unit to which the pragma applies, | |
6329 | when these objects are initialized (explicitly or implicitly) by an aggregate. | |
6330 | In the absence of this pragma, aggregates in object declarations are expanded | |
6331 | into assignments and loops, even when the aggregate components are static | |
6332 | constants. When the aggregate is present the compiler builds a static expression | |
6333 | that requires no run-time code, so that the initialized object can be placed in | |
6334 | read-only data space. If the components are not static, or the aggregate has | |
6335 | more that 100 components, the compiler emits a warning that the pragma cannot | |
6336 | be obeyed. (See also the restriction No_Implicit_Loops, which supports static | |
6337 | construction of larger aggregates with static components that include an others | |
6338 | choice.) | |
6339 | ||
6340 | Pragma Stream_Convert | |
6341 | ===================== | |
6342 | ||
6343 | Syntax: | |
6344 | ||
6345 | ||
6346 | :: | |
6347 | ||
6348 | pragma Stream_Convert ( | |
6349 | [Entity =>] type_LOCAL_NAME, | |
6350 | [Read =>] function_NAME, | |
6351 | [Write =>] function_NAME); | |
6352 | ||
6353 | ||
6354 | This pragma provides an efficient way of providing user-defined stream | |
6355 | attributes. Not only is it simpler to use than specifying the attributes | |
6356 | directly, but more importantly, it allows the specification to be made in such | |
6357 | a way that the predefined unit Ada.Streams is not loaded unless it is actually | |
6358 | needed (i.e. unless the stream attributes are actually used); the use of | |
6359 | the Stream_Convert pragma adds no overhead at all, unless the stream | |
6360 | attributes are actually used on the designated type. | |
6361 | ||
6362 | The first argument specifies the type for which stream functions are | |
6363 | provided. The second parameter provides a function used to read values | |
6364 | of this type. It must name a function whose argument type may be any | |
6365 | subtype, and whose returned type must be the type given as the first | |
6366 | argument to the pragma. | |
6367 | ||
e94434ba | 6368 | The meaning of the ``Read`` parameter is that if a stream attribute directly |
bf5dffd3 | 6369 | or indirectly specifies reading of the type given as the first parameter, |
6370 | then a value of the type given as the argument to the Read function is | |
6371 | read from the stream, and then the Read function is used to convert this | |
6372 | to the required target type. | |
6373 | ||
e94434ba | 6374 | Similarly the ``Write`` parameter specifies how to treat write attributes |
bf5dffd3 | 6375 | that directly or indirectly apply to the type given as the first parameter. |
6376 | It must have an input parameter of the type specified by the first parameter, | |
6377 | and the return type must be the same as the input type of the Read function. | |
6378 | The effect is to first call the Write function to convert to the given stream | |
6379 | type, and then write the result type to the stream. | |
6380 | ||
6381 | The Read and Write functions must not be overloaded subprograms. If necessary | |
6382 | renamings can be supplied to meet this requirement. | |
6383 | The usage of this attribute is best illustrated by a simple example, taken | |
6384 | from the GNAT implementation of package Ada.Strings.Unbounded: | |
6385 | ||
6386 | ||
6387 | .. code-block:: ada | |
6388 | ||
6389 | function To_Unbounded (S : String) return Unbounded_String | |
6390 | renames To_Unbounded_String; | |
6391 | ||
6392 | pragma Stream_Convert | |
6393 | (Unbounded_String, To_Unbounded, To_String); | |
6394 | ||
6395 | ||
6396 | The specifications of the referenced functions, as given in the Ada | |
6397 | Reference Manual are: | |
6398 | ||
6399 | ||
6400 | .. code-block:: ada | |
6401 | ||
6402 | function To_Unbounded_String (Source : String) | |
6403 | return Unbounded_String; | |
6404 | ||
6405 | function To_String (Source : Unbounded_String) | |
6406 | return String; | |
6407 | ||
6408 | ||
6409 | The effect is that if the value of an unbounded string is written to a stream, | |
6410 | then the representation of the item in the stream is in the same format that | |
e94434ba | 6411 | would be used for ``Standard.String'Output``, and this same representation |
bf5dffd3 | 6412 | is expected when a value of this type is read from the stream. Note that the |
6413 | value written always includes the bounds, even for Unbounded_String'Write, | |
6414 | since Unbounded_String is not an array type. | |
6415 | ||
e94434ba | 6416 | Note that the ``Stream_Convert`` pragma is not effective in the case of |
bf5dffd3 | 6417 | a derived type of a non-limited tagged type. If such a type is specified then |
6418 | the pragma is silently ignored, and the default implementation of the stream | |
6419 | attributes is used instead. | |
6420 | ||
6421 | Pragma Style_Checks | |
6422 | =================== | |
6423 | ||
6424 | Syntax: | |
6425 | ||
6426 | ||
6427 | :: | |
6428 | ||
6429 | pragma Style_Checks (string_LITERAL | ALL_CHECKS | | |
6430 | On | Off [, LOCAL_NAME]); | |
6431 | ||
6432 | ||
6433 | This pragma is used in conjunction with compiler switches to control the | |
6434 | built in style checking provided by GNAT. The compiler switches, if set, | |
6435 | provide an initial setting for the switches, and this pragma may be used | |
6436 | to modify these settings, or the settings may be provided entirely by | |
6437 | the use of the pragma. This pragma can be used anywhere that a pragma | |
6438 | is legal, including use as a configuration pragma (including use in | |
6439 | the :file:`gnat.adc` file). | |
6440 | ||
6441 | The form with a string literal specifies which style options are to be | |
6442 | activated. These are additive, so they apply in addition to any previously | |
6443 | set style check options. The codes for the options are the same as those | |
6444 | used in the *-gnaty* switch to *gcc* or *gnatmake*. | |
6445 | For example the following two methods can be used to enable | |
6446 | layout checking: | |
6447 | ||
6448 | * | |
6449 | ||
6450 | :: | |
6451 | ||
6452 | pragma Style_Checks ("l"); | |
6453 | ||
6454 | ||
6455 | * | |
6456 | ||
6457 | :: | |
6458 | ||
6459 | gcc -c -gnatyl ... | |
6460 | ||
6461 | ||
e94434ba | 6462 | The form ``ALL_CHECKS`` activates all standard checks (its use is equivalent |
6463 | to the use of the :switch:`gnaty` switch with no options. | |
bf5dffd3 | 6464 | See the :title:`GNAT User's Guide` for details.) |
6465 | ||
e94434ba | 6466 | Note: the behavior is slightly different in GNAT mode (:switch:`-gnatg` used). |
6467 | In this case, ``ALL_CHECKS`` implies the standard set of GNAT mode style check | |
6468 | options (i.e. equivalent to :switch:`-gnatyg`). | |
bf5dffd3 | 6469 | |
e94434ba | 6470 | The forms with ``Off`` and ``On`` |
bf5dffd3 | 6471 | can be used to temporarily disable style checks |
6472 | as shown in the following example: | |
6473 | ||
6474 | ||
6475 | .. code-block:: ada | |
6476 | ||
6477 | pragma Style_Checks ("k"); -- requires keywords in lower case | |
6478 | pragma Style_Checks (Off); -- turn off style checks | |
6479 | NULL; -- this will not generate an error message | |
6480 | pragma Style_Checks (On); -- turn style checks back on | |
6481 | NULL; -- this will generate an error message | |
6482 | ||
6483 | ||
6484 | Finally the two argument form is allowed only if the first argument is | |
e94434ba | 6485 | ``On`` or ``Off``. The effect is to turn of semantic style checks |
bf5dffd3 | 6486 | for the specified entity, as shown in the following example: |
6487 | ||
6488 | ||
6489 | .. code-block:: ada | |
6490 | ||
6491 | pragma Style_Checks ("r"); -- require consistency of identifier casing | |
6492 | Arg : Integer; | |
6493 | Rf1 : Integer := ARG; -- incorrect, wrong case | |
6494 | pragma Style_Checks (Off, Arg); | |
6495 | Rf2 : Integer := ARG; -- OK, no error | |
6496 | ||
6497 | ||
6498 | Pragma Subtitle | |
6499 | =============== | |
6500 | ||
6501 | Syntax: | |
6502 | ||
6503 | ||
6504 | :: | |
6505 | ||
6506 | pragma Subtitle ([Subtitle =>] STRING_LITERAL); | |
6507 | ||
6508 | ||
6509 | This pragma is recognized for compatibility with other Ada compilers | |
6510 | but is ignored by GNAT. | |
6511 | ||
6512 | Pragma Suppress | |
6513 | =============== | |
6514 | ||
6515 | Syntax: | |
6516 | ||
6517 | ||
6518 | :: | |
6519 | ||
6520 | pragma Suppress (Identifier [, [On =>] Name]); | |
6521 | ||
6522 | ||
6523 | This is a standard pragma, and supports all the check names required in | |
6524 | the RM. It is included here because GNAT recognizes some additional check | |
6525 | names that are implementation defined (as permitted by the RM): | |
6526 | ||
6527 | ||
6528 | * | |
e94434ba | 6529 | ``Alignment_Check`` can be used to suppress alignment checks |
bf5dffd3 | 6530 | on addresses used in address clauses. Such checks can also be suppressed |
e94434ba | 6531 | by suppressing range checks, but the specific use of ``Alignment_Check`` |
bf5dffd3 | 6532 | allows suppression of alignment checks without suppressing other range checks. |
e94434ba | 6533 | Note that ``Alignment_Check`` is suppressed by default on machines (such as |
9eae7e2d | 6534 | the x86) with non-strict alignment. |
bf5dffd3 | 6535 | |
6536 | * | |
e94434ba | 6537 | ``Atomic_Synchronization`` can be used to suppress the special memory |
bf5dffd3 | 6538 | synchronization instructions that are normally generated for access to |
e94434ba | 6539 | ``Atomic`` variables to ensure correct synchronization between tasks |
bf5dffd3 | 6540 | that use such variables for synchronization purposes. |
6541 | ||
6542 | * | |
e94434ba | 6543 | ``Duplicated_Tag_Check`` Can be used to suppress the check that is generated |
bf5dffd3 | 6544 | for a duplicated tag value when a tagged type is declared. |
6545 | ||
a4ebc1ba | 6546 | * |
e94434ba | 6547 | ``Container_Checks`` Can be used to suppress all checks within Ada.Containers |
a4ebc1ba | 6548 | and instances of its children, including Tampering_Check. |
6549 | ||
6550 | * | |
e94434ba | 6551 | ``Tampering_Check`` Can be used to suppress tampering check in the containers. |
a4ebc1ba | 6552 | |
bf5dffd3 | 6553 | * |
e94434ba | 6554 | ``Predicate_Check`` can be used to control whether predicate checks are |
bf5dffd3 | 6555 | active. It is applicable only to predicates for which the policy is |
e94434ba | 6556 | ``Check``. Unlike ``Assertion_Policy``, which determines if a given |
bf5dffd3 | 6557 | predicate is ignored or checked for the whole program, the use of |
e94434ba | 6558 | ``Suppress`` and ``Unsuppress`` with this check name allows a given |
bf5dffd3 | 6559 | predicate to be turned on and off at specific points in the program. |
6560 | ||
6561 | * | |
e94434ba | 6562 | ``Validity_Check`` can be used specifically to control validity checks. |
6563 | If ``Suppress`` is used to suppress validity checks, then no validity | |
bf5dffd3 | 6564 | checks are performed, including those specified by the appropriate compiler |
e94434ba | 6565 | switch or the ``Validity_Checks`` pragma. |
bf5dffd3 | 6566 | |
6567 | * | |
e94434ba | 6568 | Additional check names previously introduced by use of the ``Check_Name`` |
bf5dffd3 | 6569 | pragma are also allowed. |
6570 | ||
6571 | ||
6572 | Note that pragma Suppress gives the compiler permission to omit | |
6573 | checks, but does not require the compiler to omit checks. The compiler | |
6574 | will generate checks if they are essentially free, even when they are | |
6575 | suppressed. In particular, if the compiler can prove that a certain | |
6576 | check will necessarily fail, it will generate code to do an | |
6577 | unconditional 'raise', even if checks are suppressed. The compiler | |
6578 | warns in this case. | |
6579 | ||
6580 | Of course, run-time checks are omitted whenever the compiler can prove | |
6581 | that they will not fail, whether or not checks are suppressed. | |
6582 | ||
6583 | Pragma Suppress_All | |
6584 | =================== | |
6585 | ||
6586 | Syntax: | |
6587 | ||
6588 | ||
6589 | .. code-block:: ada | |
6590 | ||
6591 | pragma Suppress_All; | |
6592 | ||
6593 | ||
6594 | This pragma can appear anywhere within a unit. | |
e94434ba | 6595 | The effect is to apply ``Suppress (All_Checks)`` to the unit |
bf5dffd3 | 6596 | in which it appears. This pragma is implemented for compatibility with DEC |
6597 | Ada 83 usage where it appears at the end of a unit, and for compatibility | |
6598 | with Rational Ada, where it appears as a program unit pragma. | |
e94434ba | 6599 | The use of the standard Ada pragma ``Suppress (All_Checks)`` |
bf5dffd3 | 6600 | as a normal configuration pragma is the preferred usage in GNAT. |
6601 | ||
39adf1e6 | 6602 | .. _Pragma-Suppress_Debug_Info: |
6603 | ||
bf5dffd3 | 6604 | Pragma Suppress_Debug_Info |
6605 | ========================== | |
6606 | ||
6607 | Syntax: | |
6608 | ||
6609 | ||
6610 | :: | |
6611 | ||
6612 | pragma Suppress_Debug_Info ([Entity =>] LOCAL_NAME); | |
6613 | ||
6614 | ||
6615 | This pragma can be used to suppress generation of debug information | |
6616 | for the specified entity. It is intended primarily for use in debugging | |
6617 | the debugger, and navigating around debugger problems. | |
6618 | ||
6619 | Pragma Suppress_Exception_Locations | |
6620 | =================================== | |
6621 | ||
6622 | Syntax: | |
6623 | ||
6624 | ||
6625 | .. code-block:: ada | |
6626 | ||
6627 | pragma Suppress_Exception_Locations; | |
6628 | ||
6629 | ||
6630 | In normal mode, a raise statement for an exception by default generates | |
6631 | an exception message giving the file name and line number for the location | |
6632 | of the raise. This is useful for debugging and logging purposes, but this | |
6633 | entails extra space for the strings for the messages. The configuration | |
e94434ba | 6634 | pragma ``Suppress_Exception_Locations`` can be used to suppress the |
bf5dffd3 | 6635 | generation of these strings, with the result that space is saved, but the |
6636 | exception message for such raises is null. This configuration pragma may | |
6637 | appear in a global configuration pragma file, or in a specific unit as | |
6638 | usual. It is not required that this pragma be used consistently within | |
6639 | a partition, so it is fine to have some units within a partition compiled | |
6640 | with this pragma and others compiled in normal mode without it. | |
6641 | ||
39adf1e6 | 6642 | .. _Pragma-Suppress_Initialization: |
6643 | ||
bf5dffd3 | 6644 | Pragma Suppress_Initialization |
6645 | ============================== | |
6646 | .. index:: Suppressing initialization | |
6647 | ||
6648 | .. index:: Initialization, suppression of | |
6649 | ||
6650 | Syntax: | |
6651 | ||
6652 | ||
6653 | :: | |
6654 | ||
6655 | pragma Suppress_Initialization ([Entity =>] variable_or_subtype_Name); | |
6656 | ||
6657 | ||
6658 | Here variable_or_subtype_Name is the name introduced by a type declaration | |
6659 | or subtype declaration or the name of a variable introduced by an | |
6660 | object declaration. | |
6661 | ||
6662 | In the case of a type or subtype | |
6663 | this pragma suppresses any implicit or explicit initialization | |
6664 | for all variables of the given type or subtype, | |
6665 | including initialization resulting from the use of pragmas | |
6666 | Normalize_Scalars or Initialize_Scalars. | |
6667 | ||
6668 | This is considered a representation item, so it cannot be given after | |
6669 | the type is frozen. It applies to all subsequent object declarations, | |
6670 | and also any allocator that creates objects of the type. | |
6671 | ||
6672 | If the pragma is given for the first subtype, then it is considered | |
6673 | to apply to the base type and all its subtypes. If the pragma is given | |
6674 | for other than a first subtype, then it applies only to the given subtype. | |
6675 | The pragma may not be given after the type is frozen. | |
6676 | ||
6677 | Note that this includes eliminating initialization of discriminants | |
6678 | for discriminated types, and tags for tagged types. In these cases, | |
6679 | you will have to use some non-portable mechanism (e.g. address | |
6680 | overlays or unchecked conversion) to achieve required initialization | |
6681 | of these fields before accessing any object of the corresponding type. | |
6682 | ||
6683 | For the variable case, implicit initialization for the named variable | |
6684 | is suppressed, just as though its subtype had been given in a pragma | |
6685 | Suppress_Initialization, as described above. | |
6686 | ||
6687 | Pragma Task_Name | |
6688 | ================ | |
6689 | ||
6690 | Syntax | |
6691 | ||
6692 | ||
6693 | .. code-block:: ada | |
6694 | ||
6695 | pragma Task_Name (string_EXPRESSION); | |
6696 | ||
6697 | ||
6698 | This pragma appears within a task definition (like pragma | |
e94434ba | 6699 | ``Priority``) and applies to the task in which it appears. The |
bf5dffd3 | 6700 | argument must be of type String, and provides a name to be used for |
6701 | the task instance when the task is created. Note that this expression | |
6702 | is not required to be static, and in particular, it can contain | |
6703 | references to task discriminants. This facility can be used to | |
6704 | provide different names for different tasks as they are created, | |
6705 | as illustrated in the example below. | |
6706 | ||
6707 | The task name is recorded internally in the run-time structures | |
6708 | and is accessible to tools like the debugger. In addition the | |
e94434ba | 6709 | routine ``Ada.Task_Identification.Image`` will return this |
bf5dffd3 | 6710 | string, with a unique task address appended. |
6711 | ||
6712 | ||
6713 | .. code-block:: ada | |
6714 | ||
6715 | -- Example of the use of pragma Task_Name | |
6716 | ||
6717 | with Ada.Task_Identification; | |
6718 | use Ada.Task_Identification; | |
6719 | with Text_IO; use Text_IO; | |
6720 | procedure t3 is | |
6721 | ||
6722 | type Astring is access String; | |
6723 | ||
6724 | task type Task_Typ (Name : access String) is | |
6725 | pragma Task_Name (Name.all); | |
6726 | end Task_Typ; | |
6727 | ||
6728 | task body Task_Typ is | |
6729 | Nam : constant String := Image (Current_Task); | |
6730 | begin | |
6731 | Put_Line ("-->" & Nam (1 .. 14) & "<--"); | |
6732 | end Task_Typ; | |
6733 | ||
6734 | type Ptr_Task is access Task_Typ; | |
6735 | Task_Var : Ptr_Task; | |
6736 | ||
6737 | begin | |
6738 | Task_Var := | |
6739 | new Task_Typ (new String'("This is task 1")); | |
6740 | Task_Var := | |
6741 | new Task_Typ (new String'("This is task 2")); | |
6742 | end; | |
6743 | ||
6744 | ||
6745 | Pragma Task_Storage | |
6746 | =================== | |
6747 | Syntax: | |
6748 | ||
6749 | ||
6750 | :: | |
6751 | ||
6752 | pragma Task_Storage ( | |
6753 | [Task_Type =>] LOCAL_NAME, | |
6754 | [Top_Guard =>] static_integer_EXPRESSION); | |
6755 | ||
6756 | ||
6757 | This pragma specifies the length of the guard area for tasks. The guard | |
6758 | area is an additional storage area allocated to a task. A value of zero | |
6759 | means that either no guard area is created or a minimal guard area is | |
6760 | created, depending on the target. This pragma can appear anywhere a | |
e94434ba | 6761 | ``Storage_Size`` attribute definition clause is allowed for a task |
bf5dffd3 | 6762 | type. |
6763 | ||
39adf1e6 | 6764 | .. _Pragma-Test_Case: |
6765 | ||
bf5dffd3 | 6766 | Pragma Test_Case |
6767 | ================ | |
6768 | .. index:: Test cases | |
6769 | ||
6770 | ||
6771 | Syntax: | |
6772 | ||
6773 | ||
6774 | :: | |
6775 | ||
6776 | pragma Test_Case ( | |
6777 | [Name =>] static_string_Expression | |
6778 | ,[Mode =>] (Nominal | Robustness) | |
6779 | [, Requires => Boolean_Expression] | |
6780 | [, Ensures => Boolean_Expression]); | |
6781 | ||
6782 | ||
e94434ba | 6783 | The ``Test_Case`` pragma allows defining fine-grain specifications |
bf5dffd3 | 6784 | for use by testing tools. |
e94434ba | 6785 | The compiler checks the validity of the ``Test_Case`` pragma, but its |
bf5dffd3 | 6786 | presence does not lead to any modification of the code generated by the |
6787 | compiler. | |
6788 | ||
e94434ba | 6789 | ``Test_Case`` pragmas may only appear immediately following the |
bf5dffd3 | 6790 | (separate) declaration of a subprogram in a package declaration, inside |
6791 | a package spec unit. Only other pragmas may intervene (that is appear | |
6792 | between the subprogram declaration and a test case). | |
6793 | ||
e94434ba | 6794 | The compiler checks that boolean expressions given in ``Requires`` and |
6795 | ``Ensures`` are valid, where the rules for ``Requires`` are the | |
6796 | same as the rule for an expression in ``Precondition`` and the rules | |
6797 | for ``Ensures`` are the same as the rule for an expression in | |
6798 | ``Postcondition``. In particular, attributes ``'Old`` and | |
6799 | ``'Result`` can only be used within the ``Ensures`` | |
bf5dffd3 | 6800 | expression. The following is an example of use within a package spec: |
6801 | ||
6802 | ||
6803 | .. code-block:: ada | |
6804 | ||
6805 | package Math_Functions is | |
6806 | ... | |
6807 | function Sqrt (Arg : Float) return Float; | |
6808 | pragma Test_Case (Name => "Test 1", | |
6809 | Mode => Nominal, | |
6810 | Requires => Arg < 10000, | |
6811 | Ensures => Sqrt'Result < 10); | |
6812 | ... | |
6813 | end Math_Functions; | |
6814 | ||
6815 | ||
6816 | The meaning of a test case is that there is at least one context where | |
e94434ba | 6817 | ``Requires`` holds such that, if the associated subprogram is executed in |
6818 | that context, then ``Ensures`` holds when the subprogram returns. | |
6819 | Mode ``Nominal`` indicates that the input context should also satisfy the | |
bf5dffd3 | 6820 | precondition of the subprogram, and the output context should also satisfy its |
e94434ba | 6821 | postcondition. Mode ``Robustness`` indicates that the precondition and |
bf5dffd3 | 6822 | postcondition of the subprogram should be ignored for this test case. |
6823 | ||
39adf1e6 | 6824 | .. _Pragma-Thread_Local_Storage: |
6825 | ||
bf5dffd3 | 6826 | Pragma Thread_Local_Storage |
6827 | =========================== | |
6828 | .. index:: Task specific storage | |
6829 | ||
6830 | .. index:: TLS (Thread Local Storage) | |
6831 | ||
6832 | .. index:: Task_Attributes | |
6833 | ||
6834 | Syntax: | |
6835 | ||
6836 | ||
6837 | :: | |
6838 | ||
6839 | pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME); | |
6840 | ||
6841 | ||
6842 | This pragma specifies that the specified entity, which must be | |
e94434ba | 6843 | a variable declared in a library-level package, is to be marked as |
6844 | "Thread Local Storage" (``TLS``). On systems supporting this (which | |
2a8172b9 | 6845 | include Windows, Solaris, GNU/Linux, and VxWorks 6), this causes each |
77a7ad42 | 6846 | thread (and hence each Ada task) to see a distinct copy of the variable. |
bf5dffd3 | 6847 | |
2a8172b9 | 6848 | The variable must not have default initialization, and if there is |
e94434ba | 6849 | an explicit initialization, it must be either ``null`` for an |
2a8172b9 | 6850 | access variable, a static expression for a scalar variable, or a fully |
6851 | static aggregate for a composite type, that is to say, an aggregate all | |
6852 | of whose components are static, and which does not include packed or | |
6853 | discriminated components. | |
6854 | ||
6855 | This provides a low-level mechanism similar to that provided by | |
e94434ba | 6856 | the ``Ada.Task_Attributes`` package, but much more efficient |
bf5dffd3 | 6857 | and is also useful in writing interface code that will interact |
6858 | with foreign threads. | |
6859 | ||
e94434ba | 6860 | If this pragma is used on a system where ``TLS`` is not supported, |
bf5dffd3 | 6861 | then an error message will be generated and the program will be rejected. |
6862 | ||
6863 | Pragma Time_Slice | |
6864 | ================= | |
6865 | ||
6866 | Syntax: | |
6867 | ||
6868 | ||
6869 | .. code-block:: ada | |
6870 | ||
6871 | pragma Time_Slice (static_duration_EXPRESSION); | |
6872 | ||
6873 | ||
6874 | For implementations of GNAT on operating systems where it is possible | |
6875 | to supply a time slice value, this pragma may be used for this purpose. | |
6876 | It is ignored if it is used in a system that does not allow this control, | |
6877 | or if it appears in other than the main program unit. | |
6878 | ||
6879 | Pragma Title | |
6880 | ============ | |
6881 | ||
6882 | Syntax: | |
6883 | ||
6884 | ||
6885 | :: | |
6886 | ||
6887 | pragma Title (TITLING_OPTION [, TITLING OPTION]); | |
6888 | ||
6889 | TITLING_OPTION ::= | |
6890 | [Title =>] STRING_LITERAL, | |
6891 | | [Subtitle =>] STRING_LITERAL | |
6892 | ||
6893 | ||
6894 | Syntax checked but otherwise ignored by GNAT. This is a listing control | |
6895 | pragma used in DEC Ada 83 implementations to provide a title and/or | |
6896 | subtitle for the program listing. The program listing generated by GNAT | |
6897 | does not have titles or subtitles. | |
6898 | ||
6899 | Unlike other pragmas, the full flexibility of named notation is allowed | |
6900 | for this pragma, i.e., the parameters may be given in any order if named | |
6901 | notation is used, and named and positional notation can be mixed | |
6902 | following the normal rules for procedure calls in Ada. | |
6903 | ||
6904 | Pragma Type_Invariant | |
6905 | ===================== | |
6906 | ||
6907 | Syntax: | |
6908 | ||
6909 | ||
6910 | :: | |
6911 | ||
6912 | pragma Type_Invariant | |
6913 | ([Entity =>] type_LOCAL_NAME, | |
6914 | [Check =>] EXPRESSION); | |
6915 | ||
6916 | ||
e94434ba | 6917 | The ``Type_Invariant`` pragma is intended to be an exact |
6918 | replacement for the language-defined ``Type_Invariant`` | |
bf5dffd3 | 6919 | aspect, and shares its restrictions and semantics. It differs |
e94434ba | 6920 | from the language defined ``Invariant`` pragma in that it |
bf5dffd3 | 6921 | does not permit a string parameter, and it is |
e94434ba | 6922 | controlled by the assertion identifier ``Type_Invariant`` |
6923 | rather than ``Invariant``. | |
bf5dffd3 | 6924 | |
39adf1e6 | 6925 | .. _Pragma-Type_Invariant_Class: |
6926 | ||
bf5dffd3 | 6927 | Pragma Type_Invariant_Class |
6928 | =========================== | |
6929 | ||
6930 | Syntax: | |
6931 | ||
6932 | ||
6933 | :: | |
6934 | ||
6935 | pragma Type_Invariant_Class | |
6936 | ([Entity =>] type_LOCAL_NAME, | |
6937 | [Check =>] EXPRESSION); | |
6938 | ||
6939 | ||
e94434ba | 6940 | The ``Type_Invariant_Class`` pragma is intended to be an exact |
6941 | replacement for the language-defined ``Type_Invariant'Class`` | |
bf5dffd3 | 6942 | aspect, and shares its restrictions and semantics. |
6943 | ||
e94434ba | 6944 | Note: This pragma is called ``Type_Invariant_Class`` rather than |
6945 | ``Type_Invariant'Class`` because the latter would not be strictly | |
bf5dffd3 | 6946 | conforming to the allowed syntax for pragmas. The motivation |
6947 | for providing pragmas equivalent to the aspects is to allow a program | |
6948 | to be written using the pragmas, and then compiled if necessary | |
6949 | using an Ada compiler that does not recognize the pragmas or | |
6950 | aspects, but is prepared to ignore the pragmas. The assertion | |
e94434ba | 6951 | policy that controls this pragma is ``Type_Invariant'Class``, |
6952 | not ``Type_Invariant_Class``. | |
bf5dffd3 | 6953 | |
6954 | Pragma Unchecked_Union | |
6955 | ====================== | |
6956 | .. index:: Unions in C | |
6957 | ||
6958 | ||
6959 | Syntax: | |
6960 | ||
6961 | ||
6962 | .. code-block:: ada | |
6963 | ||
6964 | pragma Unchecked_Union (first_subtype_LOCAL_NAME); | |
6965 | ||
6966 | ||
6967 | This pragma is used to specify a representation of a record type that is | |
6968 | equivalent to a C union. It was introduced as a GNAT implementation defined | |
6969 | pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this | |
6970 | pragma, making it language defined, and GNAT fully implements this extended | |
6971 | version in all language modes (Ada 83, Ada 95, and Ada 2005). For full | |
6972 | details, consult the Ada 2012 Reference Manual, section B.3.3. | |
6973 | ||
6974 | Pragma Unevaluated_Use_Of_Old | |
6975 | ============================= | |
6976 | .. index:: Attribute Old | |
6977 | ||
6978 | .. index:: Attribute Loop_Entry | |
6979 | ||
6980 | .. index:: Unevaluated_Use_Of_Old | |
6981 | ||
6982 | ||
6983 | Syntax: | |
6984 | ||
6985 | ||
6986 | .. code-block:: ada | |
6987 | ||
6988 | pragma Unevaluated_Use_Of_Old (Error | Warn | Allow); | |
6989 | ||
6990 | ||
6991 | This pragma controls the processing of attributes Old and Loop_Entry. | |
6992 | If either of these attributes is used in a potentially unevaluated | |
6993 | expression (e.g. the then or else parts of an if expression), then | |
6994 | normally this usage is considered illegal if the prefix of the attribute | |
6995 | is other than an entity name. The language requires this | |
6996 | behavior for Old, and GNAT copies the same rule for Loop_Entry. | |
6997 | ||
6998 | The reason for this rule is that otherwise, we can have a situation | |
6999 | where we save the Old value, and this results in an exception, even | |
7000 | though we might not evaluate the attribute. Consider this example: | |
7001 | ||
7002 | ||
7003 | .. code-block:: ada | |
7004 | ||
7005 | package UnevalOld is | |
7006 | K : Character; | |
7007 | procedure U (A : String; C : Boolean) -- ERROR | |
7008 | with Post => (if C then A(1)'Old = K else True); | |
7009 | end; | |
7010 | ||
7011 | ||
7012 | If procedure U is called with a string with a lower bound of 2, and | |
7013 | C false, then an exception would be raised trying to evaluate A(1) | |
7014 | on entry even though the value would not be actually used. | |
7015 | ||
7016 | Although the rule guarantees against this possibility, it is sometimes | |
7017 | too restrictive. For example if we know that the string has a lower | |
7018 | bound of 1, then we will never raise an exception. | |
e94434ba | 7019 | The pragma ``Unevaluated_Use_Of_Old`` can be |
7020 | used to modify this behavior. If the argument is ``Error`` then an | |
bf5dffd3 | 7021 | error is given (this is the default RM behavior). If the argument is |
e94434ba | 7022 | ``Warn`` then the usage is allowed as legal but with a warning |
7023 | that an exception might be raised. If the argument is ``Allow`` | |
bf5dffd3 | 7024 | then the usage is allowed as legal without generating a warning. |
7025 | ||
7026 | This pragma may appear as a configuration pragma, or in a declarative | |
7027 | part or package specification. In the latter case it applies to | |
7028 | uses up to the end of the corresponding statement sequence or | |
7029 | sequence of package declarations. | |
7030 | ||
7031 | Pragma Unimplemented_Unit | |
7032 | ========================= | |
7033 | ||
7034 | Syntax: | |
7035 | ||
7036 | ||
7037 | .. code-block:: ada | |
7038 | ||
7039 | pragma Unimplemented_Unit; | |
7040 | ||
7041 | ||
7042 | If this pragma occurs in a unit that is processed by the compiler, GNAT | |
7043 | aborts with the message :samp:`xxx not implemented`, where | |
e94434ba | 7044 | ``xxx`` is the name of the current compilation unit. This pragma is |
bf5dffd3 | 7045 | intended to allow the compiler to handle unimplemented library units in |
7046 | a clean manner. | |
7047 | ||
7048 | The abort only happens if code is being generated. Thus you can use | |
7049 | specs of unimplemented packages in syntax or semantic checking mode. | |
7050 | ||
39adf1e6 | 7051 | .. _Pragma-Universal_Aliasing: |
7052 | ||
bf5dffd3 | 7053 | Pragma Universal_Aliasing |
7054 | ========================= | |
7055 | ||
7056 | Syntax: | |
7057 | ||
7058 | ||
7059 | :: | |
7060 | ||
7061 | pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)]; | |
7062 | ||
7063 | ||
e94434ba | 7064 | ``type_LOCAL_NAME`` must refer to a type declaration in the current |
bf5dffd3 | 7065 | declarative part. The effect is to inhibit strict type-based aliasing |
7066 | optimization for the given type. In other words, the effect is as though | |
7067 | access types designating this type were subject to pragma No_Strict_Aliasing. | |
7068 | For a detailed description of the strict aliasing optimization, and the | |
7069 | situations in which it must be suppressed, see the section on | |
e94434ba | 7070 | ``Optimization and Strict Aliasing`` in the :title:`GNAT User's Guide`. |
bf5dffd3 | 7071 | |
39adf1e6 | 7072 | .. _Pragma-Universal_Data: |
7073 | ||
bf5dffd3 | 7074 | Pragma Universal_Data |
7075 | ===================== | |
7076 | ||
7077 | Syntax: | |
7078 | ||
7079 | ||
7080 | :: | |
7081 | ||
7082 | pragma Universal_Data [(library_unit_Name)]; | |
7083 | ||
7084 | ||
7085 | This pragma is supported only for the AAMP target and is ignored for | |
7086 | other targets. The pragma specifies that all library-level objects | |
7087 | (Counter 0 data) associated with the library unit are to be accessed | |
7088 | and updated using universal addressing (24-bit addresses for AAMP5) | |
7089 | rather than the default of 16-bit Data Environment (DENV) addressing. | |
7090 | Use of this pragma will generally result in less efficient code for | |
7091 | references to global data associated with the library unit, but | |
7092 | allows such data to be located anywhere in memory. This pragma is | |
7093 | a library unit pragma, but can also be used as a configuration pragma | |
7094 | (including use in the :file:`gnat.adc` file). The functionality | |
7095 | of this pragma is also available by applying the -univ switch on the | |
7096 | compilations of units where universal addressing of the data is desired. | |
7097 | ||
39adf1e6 | 7098 | .. _Pragma-Unmodified: |
7099 | ||
bf5dffd3 | 7100 | Pragma Unmodified |
7101 | ================= | |
7102 | .. index:: Warnings, unmodified | |
7103 | ||
7104 | Syntax: | |
7105 | ||
7106 | ||
7107 | :: | |
7108 | ||
7109 | pragma Unmodified (LOCAL_NAME {, LOCAL_NAME}); | |
7110 | ||
7111 | ||
7112 | This pragma signals that the assignable entities (variables, | |
e94434ba | 7113 | ``out`` parameters, ``in out`` parameters) whose names are listed are |
bf5dffd3 | 7114 | deliberately not assigned in the current source unit. This |
7115 | suppresses warnings about the | |
7116 | entities being referenced but not assigned, and in addition a warning will be | |
7117 | generated if one of these entities is in fact assigned in the | |
7118 | same unit as the pragma (or in the corresponding body, or one | |
7119 | of its subunits). | |
7120 | ||
7121 | This is particularly useful for clearly signaling that a particular | |
7122 | parameter is not modified, even though the spec suggests that it might | |
7123 | be. | |
7124 | ||
7125 | For the variable case, warnings are never given for unreferenced variables | |
7126 | whose name contains one of the substrings | |
e94434ba | 7127 | ``DISCARD, DUMMY, IGNORE, JUNK, UNUSED`` in any casing. Such names |
bf5dffd3 | 7128 | are typically to be used in cases where such warnings are expected. |
e94434ba | 7129 | Thus it is never necessary to use ``pragma Unmodified`` for such |
bf5dffd3 | 7130 | variables, though it is harmless to do so. |
7131 | ||
39adf1e6 | 7132 | .. _Pragma-Unreferenced: |
7133 | ||
bf5dffd3 | 7134 | Pragma Unreferenced |
7135 | =================== | |
7136 | .. index:: Warnings, unreferenced | |
7137 | ||
7138 | Syntax: | |
7139 | ||
7140 | ||
7141 | :: | |
7142 | ||
7143 | pragma Unreferenced (LOCAL_NAME {, LOCAL_NAME}); | |
7144 | pragma Unreferenced (library_unit_NAME {, library_unit_NAME}); | |
7145 | ||
7146 | ||
7147 | This pragma signals that the entities whose names are listed are | |
7148 | deliberately not referenced in the current source unit after the | |
7149 | occurrence of the pragma. This | |
7150 | suppresses warnings about the | |
7151 | entities being unreferenced, and in addition a warning will be | |
7152 | generated if one of these entities is in fact subsequently referenced in the | |
7153 | same unit as the pragma (or in the corresponding body, or one | |
7154 | of its subunits). | |
7155 | ||
7156 | This is particularly useful for clearly signaling that a particular | |
7157 | parameter is not referenced in some particular subprogram implementation | |
7158 | and that this is deliberate. It can also be useful in the case of | |
7159 | objects declared only for their initialization or finalization side | |
7160 | effects. | |
7161 | ||
e94434ba | 7162 | If ``LOCAL_NAME`` identifies more than one matching homonym in the |
bf5dffd3 | 7163 | current scope, then the entity most recently declared is the one to which |
7164 | the pragma applies. Note that in the case of accept formals, the pragma | |
e94434ba | 7165 | Unreferenced may appear immediately after the keyword ``do`` which |
bf5dffd3 | 7166 | allows the indication of whether or not accept formals are referenced |
7167 | or not to be given individually for each accept statement. | |
7168 | ||
7169 | The left hand side of an assignment does not count as a reference for the | |
7170 | purpose of this pragma. Thus it is fine to assign to an entity for which | |
7171 | pragma Unreferenced is given. | |
7172 | ||
7173 | Note that if a warning is desired for all calls to a given subprogram, | |
7174 | regardless of whether they occur in the same unit as the subprogram | |
7175 | declaration, then this pragma should not be used (calls from another | |
7176 | unit would not be flagged); pragma Obsolescent can be used instead | |
7177 | for this purpose, see :ref:`Pragma_Obsolescent`. | |
7178 | ||
e94434ba | 7179 | The second form of pragma ``Unreferenced`` is used within a context |
bf5dffd3 | 7180 | clause. In this case the arguments must be unit names of units previously |
e94434ba | 7181 | mentioned in ``with`` clauses (similar to the usage of pragma |
7182 | ``Elaborate_All``. The effect is to suppress warnings about unreferenced | |
bf5dffd3 | 7183 | units and unreferenced entities within these units. |
7184 | ||
7185 | For the variable case, warnings are never given for unreferenced variables | |
7186 | whose name contains one of the substrings | |
e94434ba | 7187 | ``DISCARD, DUMMY, IGNORE, JUNK, UNUSED`` in any casing. Such names |
bf5dffd3 | 7188 | are typically to be used in cases where such warnings are expected. |
e94434ba | 7189 | Thus it is never necessary to use ``pragma Unreferenced`` for such |
bf5dffd3 | 7190 | variables, though it is harmless to do so. |
7191 | ||
39adf1e6 | 7192 | .. _Pragma-Unreferenced_Objects: |
7193 | ||
bf5dffd3 | 7194 | Pragma Unreferenced_Objects |
7195 | =========================== | |
7196 | .. index:: Warnings, unreferenced | |
7197 | ||
7198 | Syntax: | |
7199 | ||
7200 | ||
7201 | :: | |
7202 | ||
7203 | pragma Unreferenced_Objects (local_subtype_NAME {, local_subtype_NAME}); | |
7204 | ||
7205 | ||
7206 | This pragma signals that for the types or subtypes whose names are | |
7207 | listed, objects which are declared with one of these types or subtypes may | |
7208 | not be referenced, and if no references appear, no warnings are given. | |
7209 | ||
7210 | This is particularly useful for objects which are declared solely for their | |
7211 | initialization and finalization effect. Such variables are sometimes referred | |
7212 | to as RAII variables (Resource Acquisition Is Initialization). Using this | |
7213 | pragma on the relevant type (most typically a limited controlled type), the | |
7214 | compiler will automatically suppress unwanted warnings about these variables | |
7215 | not being referenced. | |
7216 | ||
7217 | Pragma Unreserve_All_Interrupts | |
7218 | =============================== | |
7219 | ||
7220 | Syntax: | |
7221 | ||
7222 | ||
7223 | .. code-block:: ada | |
7224 | ||
7225 | pragma Unreserve_All_Interrupts; | |
7226 | ||
7227 | ||
7228 | Normally certain interrupts are reserved to the implementation. Any attempt | |
7229 | to attach an interrupt causes Program_Error to be raised, as described in | |
e94434ba | 7230 | RM C.3.2(22). A typical example is the ``SIGINT`` interrupt used in |
bf5dffd3 | 7231 | many systems for a :kbd:`Ctrl-C` interrupt. Normally this interrupt is |
7232 | reserved to the implementation, so that :kbd:`Ctrl-C` can be used to | |
7233 | interrupt execution. | |
7234 | ||
e94434ba | 7235 | If the pragma ``Unreserve_All_Interrupts`` appears anywhere in any unit in |
bf5dffd3 | 7236 | a program, then all such interrupts are unreserved. This allows the |
7237 | program to handle these interrupts, but disables their standard | |
7238 | functions. For example, if this pragma is used, then pressing | |
7239 | :kbd:`Ctrl-C` will not automatically interrupt execution. However, | |
e94434ba | 7240 | a program can then handle the ``SIGINT`` interrupt as it chooses. |
bf5dffd3 | 7241 | |
7242 | For a full list of the interrupts handled in a specific implementation, | |
e94434ba | 7243 | see the source code for the spec of ``Ada.Interrupts.Names`` in |
bf5dffd3 | 7244 | file :file:`a-intnam.ads`. This is a target dependent file that contains the |
7245 | list of interrupts recognized for a given target. The documentation in | |
7246 | this file also specifies what interrupts are affected by the use of | |
e94434ba | 7247 | the ``Unreserve_All_Interrupts`` pragma. |
bf5dffd3 | 7248 | |
7249 | For a more general facility for controlling what interrupts can be | |
e94434ba | 7250 | handled, see pragma ``Interrupt_State``, which subsumes the functionality |
7251 | of the ``Unreserve_All_Interrupts`` pragma. | |
bf5dffd3 | 7252 | |
7253 | Pragma Unsuppress | |
7254 | ================= | |
7255 | ||
7256 | Syntax: | |
7257 | ||
7258 | ||
7259 | :: | |
7260 | ||
7261 | pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); | |
7262 | ||
7263 | ||
e94434ba | 7264 | This pragma undoes the effect of a previous pragma ``Suppress``. If |
7265 | there is no corresponding pragma ``Suppress`` in effect, it has no | |
bf5dffd3 | 7266 | effect. The range of the effect is the same as for pragma |
e94434ba | 7267 | ``Suppress``. The meaning of the arguments is identical to that used |
7268 | in pragma ``Suppress``. | |
bf5dffd3 | 7269 | |
7270 | One important application is to ensure that checks are on in cases where | |
7271 | code depends on the checks for its correct functioning, so that the code | |
7272 | will compile correctly even if the compiler switches are set to suppress | |
7273 | checks. For example, in a program that depends on external names of tagged | |
7274 | types and wants to ensure that the duplicated tag check occurs even if all | |
7275 | run-time checks are suppressed by a compiler switch, the following | |
7276 | configuration pragma will ensure this test is not suppressed: | |
7277 | ||
7278 | ||
7279 | .. code-block:: ada | |
7280 | ||
7281 | pragma Unsuppress (Duplicated_Tag_Check); | |
7282 | ||
7283 | ||
7284 | This pragma is standard in Ada 2005. It is available in all earlier versions | |
7285 | of Ada as an implementation-defined pragma. | |
7286 | ||
a4ebc1ba | 7287 | Note that in addition to the checks defined in the Ada RM, GNAT recogizes a |
7288 | number of implementation-defined check names. See the description of pragma | |
e94434ba | 7289 | ``Suppress`` for full details. |
bf5dffd3 | 7290 | |
7291 | Pragma Use_VADS_Size | |
7292 | ==================== | |
7293 | .. index:: Size, VADS compatibility | |
7294 | ||
7295 | .. index:: Rational profile | |
7296 | ||
7297 | ||
7298 | Syntax: | |
7299 | ||
7300 | ||
7301 | .. code-block:: ada | |
7302 | ||
7303 | pragma Use_VADS_Size; | |
7304 | ||
7305 | ||
7306 | This is a configuration pragma. In a unit to which it applies, any use | |
7307 | of the 'Size attribute is automatically interpreted as a use of the | |
7308 | 'VADS_Size attribute. Note that this may result in incorrect semantic | |
7309 | processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in | |
7310 | the handling of existing code which depends on the interpretation of Size | |
7311 | as implemented in the VADS compiler. See description of the VADS_Size | |
7312 | attribute for further details. | |
7313 | ||
6df5adf1 | 7314 | .. _Pragma-Unused: |
7315 | ||
7316 | Pragma Unused | |
7317 | ============= | |
7318 | .. index:: Warnings, unused | |
7319 | ||
7320 | Syntax: | |
7321 | ||
7322 | ||
7323 | :: | |
7324 | ||
7325 | pragma Unused (LOCAL_NAME {, LOCAL_NAME}); | |
7326 | ||
7327 | ||
7328 | This pragma signals that the assignable entities (variables, | |
e94434ba | 7329 | ``out`` parameters, and ``in out`` parameters) whose names are listed |
6df5adf1 | 7330 | deliberately do not get assigned or referenced in the current source unit |
7331 | after the occurrence of the pragma in the current source unit. This | |
7332 | suppresses warnings about the entities that are unreferenced and/or not | |
7333 | assigned, and, in addition, a warning will be generated if one of these | |
7334 | entities gets assigned or subsequently referenced in the same unit as the | |
7335 | pragma (in the corresponding body or one of its subunits). | |
7336 | ||
7337 | This is particularly useful for clearly signaling that a particular | |
7338 | parameter is not modified or referenced, even though the spec suggests | |
7339 | that it might be. | |
7340 | ||
7341 | For the variable case, warnings are never given for unreferenced | |
7342 | variables whose name contains one of the substrings | |
e94434ba | 7343 | ``DISCARD, DUMMY, IGNORE, JUNK, UNUSED`` in any casing. Such names |
6df5adf1 | 7344 | are typically to be used in cases where such warnings are expected. |
e94434ba | 7345 | Thus it is never necessary to use ``pragma Unmodified`` for such |
0c01a524 | 7346 | variables, though it is harmless to do so. |
6df5adf1 | 7347 | |
bf5dffd3 | 7348 | Pragma Validity_Checks |
7349 | ====================== | |
7350 | ||
7351 | Syntax: | |
7352 | ||
7353 | ||
7354 | .. code-block:: ada | |
7355 | ||
7356 | pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); | |
7357 | ||
7358 | ||
7359 | This pragma is used in conjunction with compiler switches to control the | |
7360 | built-in validity checking provided by GNAT. The compiler switches, if set | |
7361 | provide an initial setting for the switches, and this pragma may be used | |
7362 | to modify these settings, or the settings may be provided entirely by | |
7363 | the use of the pragma. This pragma can be used anywhere that a pragma | |
7364 | is legal, including use as a configuration pragma (including use in | |
7365 | the :file:`gnat.adc` file). | |
7366 | ||
7367 | The form with a string literal specifies which validity options are to be | |
7368 | activated. The validity checks are first set to include only the default | |
7369 | reference manual settings, and then a string of letters in the string | |
7370 | specifies the exact set of options required. The form of this string | |
7371 | is exactly as described for the *-gnatVx* compiler switch (see the | |
7372 | GNAT User's Guide for details). For example the following two | |
e94434ba | 7373 | methods can be used to enable validity checking for mode ``in`` and |
7374 | ``in out`` subprogram parameters: | |
bf5dffd3 | 7375 | |
7376 | * | |
7377 | ||
7378 | .. code-block:: ada | |
7379 | ||
7380 | pragma Validity_Checks ("im"); | |
7381 | ||
7382 | ||
7383 | * | |
7384 | ||
7385 | .. code-block:: sh | |
7386 | ||
7387 | $ gcc -c -gnatVim ... | |
7388 | ||
7389 | ||
7390 | The form ALL_CHECKS activates all standard checks (its use is equivalent | |
f14a590b | 7391 | to the use of the :switch:`gnatVa` switch). |
bf5dffd3 | 7392 | |
f14a590b | 7393 | The forms with ``Off`` and ``On`` can be used to temporarily disable |
7394 | validity checks as shown in the following example: | |
bf5dffd3 | 7395 | |
7396 | ||
7397 | .. code-block:: ada | |
7398 | ||
7399 | pragma Validity_Checks ("c"); -- validity checks for copies | |
7400 | pragma Validity_Checks (Off); -- turn off validity checks | |
7401 | A := B; -- B will not be validity checked | |
7402 | pragma Validity_Checks (On); -- turn validity checks back on | |
7403 | A := C; -- C will be validity checked | |
7404 | ||
adb8ac81 | 7405 | .. _Pragma-Volatile: |
bf5dffd3 | 7406 | |
7407 | Pragma Volatile | |
7408 | =============== | |
7409 | ||
7410 | Syntax: | |
7411 | ||
7412 | ||
7413 | .. code-block:: ada | |
7414 | ||
7415 | pragma Volatile (LOCAL_NAME); | |
7416 | ||
7417 | ||
7418 | This pragma is defined by the Ada Reference Manual, and the GNAT | |
7419 | implementation is fully conformant with this definition. The reason it | |
7420 | is mentioned in this section is that a pragma of the same name was supplied | |
7421 | in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005 | |
7422 | implementation of pragma Volatile is upwards compatible with the | |
7423 | implementation in DEC Ada 83. | |
7424 | ||
39adf1e6 | 7425 | .. _Pragma-Volatile_Full_Access: |
7426 | ||
33b5f2fb | 7427 | Pragma Volatile_Full_Access |
7428 | =========================== | |
7429 | ||
7430 | Syntax: | |
7431 | ||
7432 | ||
7433 | .. code-block:: ada | |
7434 | ||
7435 | pragma Volatile_Full_Access (LOCAL_NAME); | |
7436 | ||
7437 | ||
7438 | This is similar in effect to pragma Volatile, except that any reference to the | |
7439 | object is guaranteed to be done only with instructions that read or write all | |
7440 | the bits of the object. Furthermore, if the object is of a composite type, | |
7441 | then any reference to a component of the object is guaranteed to read and/or | |
7442 | write all the bits of the object. | |
7443 | ||
7444 | The intention is that this be suitable for use with memory-mapped I/O devices | |
7445 | on some machines. Note that there are two important respects in which this is | |
e94434ba | 7446 | different from ``pragma Atomic``. First a reference to a ``Volatile_Full_Access`` |
33b5f2fb | 7447 | object is not a sequential action in the RM 9.10 sense and, therefore, does |
e94434ba | 7448 | not create a synchronization point. Second, in the case of ``pragma Atomic``, |
33b5f2fb | 7449 | there is no guarantee that all the bits will be accessed if the reference |
7450 | is not to the whole object; the compiler is allowed (and generally will) | |
7451 | access only part of the object in this case. | |
7452 | ||
e94434ba | 7453 | It is not permissible to specify ``Atomic`` and ``Volatile_Full_Access`` for |
33b5f2fb | 7454 | the same object. |
7455 | ||
e94434ba | 7456 | It is not permissible to specify ``Volatile_Full_Access`` for a composite |
7457 | (record or array) type or object that has at least one ``Aliased`` component. | |
33b5f2fb | 7458 | |
39adf1e6 | 7459 | .. _Pragma-Volatile_Function: |
7460 | ||
4a7c3b2f | 7461 | Pragma Volatile_Function |
7462 | ======================== | |
7463 | ||
d5dcec30 | 7464 | Syntax: |
7465 | ||
7466 | .. code-block:: ada | |
7467 | ||
7468 | pragma Volatile_Function [ (boolean_EXPRESSION) ]; | |
7469 | ||
e94434ba | 7470 | For the semantics of this pragma, see the entry for aspect ``Volatile_Function`` |
d5dcec30 | 7471 | in the SPARK 2014 Reference Manual, section 7.1.2. |
4a7c3b2f | 7472 | |
bf5dffd3 | 7473 | Pragma Warning_As_Error |
7474 | ======================= | |
7475 | ||
7476 | Syntax: | |
7477 | ||
7478 | ||
7479 | .. code-block:: ada | |
7480 | ||
7481 | pragma Warning_As_Error (static_string_EXPRESSION); | |
7482 | ||
7483 | ||
7484 | This configuration pragma allows the programmer to specify a set | |
6b466b34 | 7485 | of warnings that will be treated as errors. Any warning that |
bf5dffd3 | 7486 | matches the pattern given by the pragma argument will be treated |
6b466b34 | 7487 | as an error. This gives more precise control than -gnatwe, |
7488 | which treats warnings as errors. | |
7489 | ||
7490 | This pragma can apply to regular warnings (messages enabled by -gnatw) | |
7491 | and to style warnings (messages that start with "(style)", | |
7492 | enabled by -gnaty). | |
7493 | ||
7494 | The pattern may contain asterisks, which match zero or more characters | |
7495 | in the message. For example, you can use ``pragma Warning_As_Error | |
7496 | ("bits of*unused")`` to treat the warning message ``warning: 960 bits of | |
7497 | "a" unused`` as an error. All characters other than asterisk are treated | |
7498 | as literal characters in the match. The match is case insensitive; for | |
7499 | example XYZ matches xyz. | |
bf5dffd3 | 7500 | |
7501 | Note that the pattern matches if it occurs anywhere within the warning | |
7502 | message string (it is not necessary to put an asterisk at the start and | |
7503 | the end of the message, since this is implied). | |
7504 | ||
7505 | Another possibility for the static_string_EXPRESSION which works whether | |
7506 | or not error tags are enabled (*-gnatw.d*) is to use the | |
7507 | *-gnatw* tag string, enclosed in brackets, | |
7508 | as shown in the example below, to treat a class of warnings as errors. | |
7509 | ||
7510 | The above use of patterns to match the message applies only to warning | |
7511 | messages generated by the front end. This pragma can also be applied to | |
7512 | warnings provided by the back end and mentioned in :ref:`Pragma_Warnings`. | |
7513 | By using a single full *-Wxxx* switch in the pragma, such warnings | |
7514 | can also be treated as errors. | |
7515 | ||
7516 | The pragma can appear either in a global configuration pragma file | |
7517 | (e.g. :file:`gnat.adc`), or at the start of a file. Given a global | |
7518 | configuration pragma file containing: | |
7519 | ||
7520 | ||
7521 | .. code-block:: ada | |
7522 | ||
7523 | pragma Warning_As_Error ("[-gnatwj]"); | |
7524 | ||
7525 | ||
7526 | which will treat all obsolescent feature warnings as errors, the | |
7527 | following program compiles as shown (compile options here are | |
7528 | *-gnatwa.d -gnatl -gnatj55*). | |
7529 | ||
7530 | ||
7531 | :: | |
7532 | ||
7533 | 1. pragma Warning_As_Error ("*never assigned*"); | |
7534 | 2. function Warnerr return String is | |
7535 | 3. X : Integer; | |
7536 | | | |
7537 | >>> error: variable "X" is never read and | |
7538 | never assigned [-gnatwv] [warning-as-error] | |
7539 | ||
7540 | 4. Y : Integer; | |
7541 | | | |
7542 | >>> warning: variable "Y" is assigned but | |
7543 | never read [-gnatwu] | |
7544 | ||
7545 | 5. begin | |
7546 | 6. Y := 0; | |
7547 | 7. return %ABC%; | |
7548 | | | |
7549 | >>> error: use of "%" is an obsolescent | |
7550 | feature (RM J.2(4)), use """ instead | |
7551 | [-gnatwj] [warning-as-error] | |
7552 | ||
7553 | 8. end; | |
7554 | ||
7555 | 8 lines: No errors, 3 warnings (2 treated as errors) | |
7556 | ||
7557 | ||
7558 | Note that this pragma does not affect the set of warnings issued in | |
7559 | any way, it merely changes the effect of a matching warning if one | |
7560 | is produced as a result of other warnings options. As shown in this | |
7561 | example, if the pragma results in a warning being treated as an error, | |
7562 | the tag is changed from "warning:" to "error:" and the string | |
7563 | "[warning-as-error]" is appended to the end of the message. | |
7564 | ||
7565 | .. _Pragma_Warnings: | |
7566 | ||
7567 | Pragma Warnings | |
7568 | =============== | |
7569 | ||
7570 | Syntax: | |
7571 | ||
7572 | ||
7573 | .. code-block:: ada | |
7574 | ||
7575 | pragma Warnings ([TOOL_NAME,] DETAILS [, REASON]); | |
7576 | ||
7577 | DETAILS ::= On | Off | |
7578 | DETAILS ::= On | Off, local_NAME | |
7579 | DETAILS ::= static_string_EXPRESSION | |
7580 | DETAILS ::= On | Off, static_string_EXPRESSION | |
7581 | ||
7582 | TOOL_NAME ::= GNAT | GNATProve | |
7583 | ||
7584 | REASON ::= Reason => STRING_LITERAL {& STRING_LITERAL} | |
7585 | ||
7586 | Note: in Ada 83 mode, a string literal may be used in place of a static string | |
7587 | expression (which does not exist in Ada 83). | |
7588 | ||
e94434ba | 7589 | Note if the second argument of ``DETAILS`` is a ``local_NAME`` then the |
bf5dffd3 | 7590 | second form is always understood. If the intention is to use |
e94434ba | 7591 | the fourth form, then you can write ``NAME & ""`` to force the |
7592 | intepretation as a *static_string_EXPRESSION*. | |
bf5dffd3 | 7593 | |
e94434ba | 7594 | Note: if the first argument is a valid ``TOOL_NAME``, it will be interpreted |
7595 | that way. The use of the ``TOOL_NAME`` argument is relevant only to users | |
bf5dffd3 | 7596 | of SPARK and GNATprove, see last part of this section for details. |
7597 | ||
7598 | Normally warnings are enabled, with the output being controlled by | |
e94434ba | 7599 | the command line switch. Warnings (``Off``) turns off generation of |
7600 | warnings until a Warnings (``On``) is encountered or the end of the | |
bf5dffd3 | 7601 | current unit. If generation of warnings is turned off using this |
7602 | pragma, then some or all of the warning messages are suppressed, | |
7603 | regardless of the setting of the command line switches. | |
7604 | ||
e94434ba | 7605 | The ``Reason`` parameter may optionally appear as the last argument |
bf5dffd3 | 7606 | in any of the forms of this pragma. It is intended purely for the |
e94434ba | 7607 | purposes of documenting the reason for the ``Warnings`` pragma. |
bf5dffd3 | 7608 | The compiler will check that the argument is a static string but |
7609 | otherwise ignore this argument. Other tools may provide specialized | |
7610 | processing for this string. | |
7611 | ||
7612 | The form with a single argument (or two arguments if Reason present), | |
e94434ba | 7613 | where the first argument is ``ON`` or ``OFF`` |
bf5dffd3 | 7614 | may be used as a configuration pragma. |
7615 | ||
e94434ba | 7616 | If the ``LOCAL_NAME`` parameter is present, warnings are suppressed for |
bf5dffd3 | 7617 | the specified entity. This suppression is effective from the point where |
7618 | it occurs till the end of the extended scope of the variable (similar to | |
e94434ba | 7619 | the scope of ``Suppress``). This form cannot be used as a configuration |
bf5dffd3 | 7620 | pragma. |
7621 | ||
e94434ba | 7622 | In the case where the first argument is other than ``ON`` or |
7623 | ``OFF``, | |
bf5dffd3 | 7624 | the third form with a single static_string_EXPRESSION argument (and possible |
7625 | reason) provides more precise | |
7626 | control over which warnings are active. The string is a list of letters | |
7627 | specifying which warnings are to be activated and which deactivated. The | |
7628 | code for these letters is the same as the string used in the command | |
7629 | line switch controlling warnings. For a brief summary, use the gnatmake | |
7630 | command with no arguments, which will generate usage information containing | |
7631 | the list of warnings switches supported. For | |
e94434ba | 7632 | full details see the section on ``Warning Message Control`` in the |
bf5dffd3 | 7633 | :title:`GNAT User's Guide`. |
7634 | This form can also be used as a configuration pragma. | |
7635 | ||
e94434ba | 7636 | The warnings controlled by the :switch:`-gnatw` switch are generated by the |
bf5dffd3 | 7637 | front end of the compiler. The GCC back end can provide additional warnings |
e94434ba | 7638 | and they are controlled by the :switch:`-W` switch. Such warnings can be |
7639 | identified by the appearance of a string of the form ``[-W{xxx}]`` in the | |
7640 | message which designates the :switch:`-W{xxx}` switch that controls the message. | |
7641 | The form with a single *static_string_EXPRESSION* argument also works for these | |
7642 | warnings, but the string must be a single full :switch:`-W{xxx}` switch in this | |
bf5dffd3 | 7643 | case. The above reference lists a few examples of these additional warnings. |
7644 | ||
7645 | The specified warnings will be in effect until the end of the program | |
e94434ba | 7646 | or another pragma ``Warnings`` is encountered. The effect of the pragma is |
bf5dffd3 | 7647 | cumulative. Initially the set of warnings is the standard default set |
7648 | as possibly modified by compiler switches. Then each pragma Warning | |
7649 | modifies this set of warnings as specified. This form of the pragma may | |
7650 | also be used as a configuration pragma. | |
7651 | ||
e94434ba | 7652 | The fourth form, with an ``On|Off`` parameter and a string, is used to |
bf5dffd3 | 7653 | control individual messages, based on their text. The string argument |
7654 | is a pattern that is used to match against the text of individual | |
7655 | warning messages (not including the initial "warning: " tag). | |
7656 | ||
7657 | The pattern may contain asterisks, which match zero or more characters in | |
7658 | the message. For example, you can use | |
e94434ba | 7659 | ``pragma Warnings (Off, "bits of*unused")`` to suppress the warning |
7660 | message ``warning: 960 bits of "a" unused``. No other regular | |
bf5dffd3 | 7661 | expression notations are permitted. All characters other than asterisk in |
7662 | these three specific cases are treated as literal characters in the match. | |
7663 | The match is case insensitive, for example XYZ matches xyz. | |
7664 | ||
7665 | Note that the pattern matches if it occurs anywhere within the warning | |
7666 | message string (it is not necessary to put an asterisk at the start and | |
7667 | the end of the message, since this is implied). | |
7668 | ||
7669 | The above use of patterns to match the message applies only to warning | |
7670 | messages generated by the front end. This form of the pragma with a string | |
7671 | argument can also be used to control warnings provided by the back end and | |
e94434ba | 7672 | mentioned above. By using a single full :switch:`-W{xxx}` switch in the pragma, |
bf5dffd3 | 7673 | such warnings can be turned on and off. |
7674 | ||
7675 | There are two ways to use the pragma in this form. The OFF form can be used | |
7676 | as a configuration pragma. The effect is to suppress all warnings (if any) | |
7677 | that match the pattern string throughout the compilation (or match the | |
7678 | -W switch in the back end case). | |
7679 | ||
7680 | The second usage is to suppress a warning locally, and in this case, two | |
7681 | pragmas must appear in sequence: | |
7682 | ||
7683 | ||
7684 | .. code-block:: ada | |
7685 | ||
7686 | pragma Warnings (Off, Pattern); | |
7687 | ... code where given warning is to be suppressed | |
7688 | pragma Warnings (On, Pattern); | |
7689 | ||
7690 | ||
7691 | In this usage, the pattern string must match in the Off and On | |
7692 | pragmas, and (if *-gnatw.w* is given) at least one matching | |
7693 | warning must be suppressed. | |
7694 | ||
3453ac26 | 7695 | Note: if the ON form is not found, then the effect of the OFF form extends |
7696 | until the end of the file (pragma Warnings is purely textual, so its effect | |
7697 | does not stop at the end of the enclosing scope). | |
7698 | ||
bf5dffd3 | 7699 | Note: to write a string that will match any warning, use the string |
e94434ba | 7700 | ``"***"``. It will not work to use a single asterisk or two |
bf5dffd3 | 7701 | asterisks since this looks like an operator name. This form with three |
e94434ba | 7702 | asterisks is similar in effect to specifying ``pragma Warnings (Off)`` except (if :switch:`-gnatw.w` is given) that a matching |
7703 | ``pragma Warnings (On, "***")`` will be required. This can be | |
bf5dffd3 | 7704 | helpful in avoiding forgetting to turn warnings back on. |
7705 | ||
e94434ba | 7706 | Note: the debug flag :switch:`-gnatd.i` (``/NOWARNINGS_PRAGMAS`` in VMS) can be |
bf5dffd3 | 7707 | used to cause the compiler to entirely ignore all WARNINGS pragmas. This can |
7708 | be useful in checking whether obsolete pragmas in existing programs are hiding | |
7709 | real problems. | |
7710 | ||
7711 | Note: pragma Warnings does not affect the processing of style messages. See | |
7712 | separate entry for pragma Style_Checks for control of style messages. | |
7713 | ||
7714 | Users of the formal verification tool GNATprove for the SPARK subset of Ada may | |
e94434ba | 7715 | use the version of the pragma with a ``TOOL_NAME`` parameter. |
bf5dffd3 | 7716 | |
e94434ba | 7717 | If present, ``TOOL_NAME`` is the name of a tool, currently either ``GNAT`` for the |
7718 | compiler or ``GNATprove`` for the formal verification tool. A given tool only | |
bf5dffd3 | 7719 | takes into account pragma Warnings that do not specify a tool name, or that |
7720 | specify the matching tool name. This makes it possible to disable warnings | |
7721 | selectively for each tool, and as a consequence to detect useless pragma | |
e94434ba | 7722 | Warnings with switch :switch:`-gnatw.w`. |
bf5dffd3 | 7723 | |
7724 | Pragma Weak_External | |
7725 | ==================== | |
7726 | ||
7727 | Syntax: | |
7728 | ||
7729 | ||
7730 | .. code-block:: ada | |
7731 | ||
7732 | pragma Weak_External ([Entity =>] LOCAL_NAME); | |
7733 | ||
7734 | ||
e94434ba | 7735 | ``LOCAL_NAME`` must refer to an object that is declared at the library |
bf5dffd3 | 7736 | level. This pragma specifies that the given entity should be marked as a |
e94434ba | 7737 | weak symbol for the linker. It is equivalent to ``__attribute__((weak))`` |
7738 | in GNU C and causes ``LOCAL_NAME`` to be emitted as a weak symbol instead | |
bf5dffd3 | 7739 | of a regular symbol, that is to say a symbol that does not have to be |
7740 | resolved by the linker if used in conjunction with a pragma Import. | |
7741 | ||
7742 | When a weak symbol is not resolved by the linker, its address is set to | |
7743 | zero. This is useful in writing interfaces to external modules that may | |
7744 | or may not be linked in the final executable, for example depending on | |
7745 | configuration settings. | |
7746 | ||
7747 | If a program references at run time an entity to which this pragma has been | |
7748 | applied, and the corresponding symbol was not resolved at link time, then | |
7749 | the execution of the program is erroneous. It is not erroneous to take the | |
7750 | Address of such an entity, for example to guard potential references, | |
7751 | as shown in the example below. | |
7752 | ||
7753 | Some file formats do not support weak symbols so not all target machines | |
7754 | support this pragma. | |
7755 | ||
7756 | ||
7757 | .. code-block:: ada | |
7758 | ||
7759 | -- Example of the use of pragma Weak_External | |
7760 | ||
7761 | package External_Module is | |
7762 | key : Integer; | |
7763 | pragma Import (C, key); | |
7764 | pragma Weak_External (key); | |
7765 | function Present return boolean; | |
7766 | end External_Module; | |
7767 | ||
7768 | with System; use System; | |
7769 | package body External_Module is | |
7770 | function Present return boolean is | |
7771 | begin | |
7772 | return key'Address /= System.Null_Address; | |
7773 | end Present; | |
7774 | end External_Module; | |
7775 | ||
7776 | ||
7777 | Pragma Wide_Character_Encoding | |
7778 | ============================== | |
7779 | ||
7780 | Syntax: | |
7781 | ||
7782 | ||
7783 | .. code-block:: ada | |
7784 | ||
7785 | pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL); | |
7786 | ||
7787 | ||
7788 | This pragma specifies the wide character encoding to be used in program | |
7789 | source text appearing subsequently. It is a configuration pragma, but may | |
7790 | also be used at any point that a pragma is allowed, and it is permissible | |
7791 | to have more than one such pragma in a file, allowing multiple encodings | |
7792 | to appear within the same file. | |
7793 | ||
8f09eafa | 7794 | However, note that the pragma cannot immediately precede the relevant |
7795 | wide character, because then the previous encoding will still be in | |
7796 | effect, causing "illegal character" errors. | |
7797 | ||
bf5dffd3 | 7798 | The argument can be an identifier or a character literal. In the identifier |
e94434ba | 7799 | case, it is one of ``HEX``, ``UPPER``, ``SHIFT_JIS``, |
7800 | ``EUC``, ``UTF8``, or ``BRACKETS``. In the character literal | |
bf5dffd3 | 7801 | case it is correspondingly one of the characters :kbd:`h`, :kbd:`u`, |
7802 | :kbd:`s`, :kbd:`e`, :kbd:`8`, or :kbd:`b`. | |
7803 | ||
7804 | Note that when the pragma is used within a file, it affects only the | |
7805 | encoding within that file, and does not affect withed units, specs, | |
7806 | or subunits. |