Debian Codegraph @

gcc/ada/doc/gnat_rm/implementation_defined_aspects.rst

raw
1 .. _Implementation_Defined_Aspects:
2
3 ******************************
4 Implementation Defined Aspects
5 ******************************
6
7 Ada defines (throughout the Ada 2012 reference manual, summarized
8 in Annex K) a set of aspects that can be specified for certain entities.
9 These language defined aspects are implemented in GNAT in Ada 2012 mode
10 and work as described in the Ada 2012 Reference Manual.
11
12 In addition, Ada 2012 allows implementations to define additional aspects
13 whose meaning is defined by the implementation. GNAT provides
14 a number of these implementation-defined aspects which can be used
15 to extend and enhance the functionality of the compiler. This section of
16 the GNAT reference manual describes these additional aspects.
17
18 Note that any program using these aspects may not be portable to
19 other compilers (although GNAT implements this set of aspects on all
20 platforms). Therefore if portability to other compilers is an important
21 consideration, you should minimize the use of these aspects.
22
23 Note that for many of these aspects, the effect is essentially similar
24 to the use of a pragma or attribute specification with the same name
25 applied to the entity. For example, if we write:
26
27
28 .. code-block:: ada
29
30 type R is range 1 .. 100
31 with Value_Size => 10;
32
33
34 then the effect is the same as:
35
36 .. code-block:: ada
37
38 type R is range 1 .. 100;
39 for R'Value_Size use 10;
40
41
42 and if we write:
43
44 .. code-block:: ada
45
46 type R is new Integer
47 with Shared => True;
48
49
50 then the effect is the same as:
51
52 .. code-block:: ada
53
54 type R is new Integer;
55 pragma Shared (R);
56
57
58 In the documentation below, such cases are simply marked
59 as being boolean aspects equivalent to the corresponding pragma
60 or attribute definition clause.
61
62 Aspect Abstract_State
63 =====================
64
65 .. index:: Abstract_State
66
67 This aspect is equivalent to :ref:`pragma Abstract_State<Pragma-Abstract_State>`.
68
69 Aspect Annotate
70 ===============
71
72 .. index:: Annotate
73
74 There are three forms of this aspect (where ID is an identifier,
75 and ARG is a general expression),
76 corresponding to :ref:`pragma Annotate<Pragma-Annotate>`.
77
78
79
80 *Annotate => ID*
81 Equivalent to ``pragma Annotate (ID, Entity => Name);``
82
83
84 *Annotate => (ID)*
85 Equivalent to ``pragma Annotate (ID, Entity => Name);``
86
87
88 *Annotate => (ID ,ID {, ARG})*
89 Equivalent to ``pragma Annotate (ID, ID {, ARG}, Entity => Name);``
90
91 Aspect Async_Readers
92 ====================
93 .. index:: Async_Readers
94
95 This boolean aspect is equivalent to :ref:`pragma Async_Readers<Pragma-Async_Readers>`.
96
97 Aspect Async_Writers
98 ====================
99 .. index:: Async_Writers
100
101 This boolean aspect is equivalent to :ref:`pragma Async_Writers<Pragma-Async_Writers>`.
102
103 Aspect Constant_After_Elaboration
104 =================================
105 .. index:: Constant_After_Elaboration
106
107 This aspect is equivalent to :ref:`pragma Constant_After_Elaboration<Pragma-Constant_After_Elaboration>`.
108
109 Aspect Contract_Cases
110 =====================
111 .. index:: Contract_Cases
112
113 This aspect is equivalent to :ref:`pragma Contract_Cases<Pragma-Contract_Cases>`, the sequence
114 of clauses being enclosed in parentheses so that syntactically it is an
115 aggregate.
116
117 Aspect Depends
118 ==============
119 .. index:: Depends
120
121 This aspect is equivalent to :ref:`pragma Depends<Pragma-Depends>`.
122
123 Aspect Default_Initial_Condition
124 ================================
125 .. index:: Default_Initial_Condition
126
127 This aspect is equivalent to :ref:`pragma Default_Initial_Condition<Pragma-Default_Initial_Condition>`.
128
129 Aspect Dimension
130 ================
131 .. index:: Dimension
132
133 The ``Dimension`` aspect is used to specify the dimensions of a given
134 subtype of a dimensioned numeric type. The aspect also specifies a symbol
135 used when doing formatted output of dimensioned quantities. The syntax is::
136
137 with Dimension =>
138 ([Symbol =>] SYMBOL, DIMENSION_VALUE {, DIMENSION_Value})
139
140 SYMBOL ::= STRING_LITERAL | CHARACTER_LITERAL
141
142 DIMENSION_VALUE ::=
143 RATIONAL
144 | others => RATIONAL
145 | DISCRETE_CHOICE_LIST => RATIONAL
146
147 RATIONAL ::= [-] NUMERIC_LITERAL [/ NUMERIC_LITERAL]
148
149
150 This aspect can only be applied to a subtype whose parent type has
151 a ``Dimension_System`` aspect. The aspect must specify values for
152 all dimensions of the system. The rational values are the powers of the
153 corresponding dimensions that are used by the compiler to verify that
154 physical (numeric) computations are dimensionally consistent. For example,
155 the computation of a force must result in dimensions (L => 1, M => 1, T => -2).
156 For further examples of the usage
157 of this aspect, see package ``System.Dim.Mks``.
158 Note that when the dimensioned type is an integer type, then any
159 dimension value must be an integer literal.
160
161 Aspect Dimension_System
162 =======================
163 .. index:: Dimension_System
164
165 The ``Dimension_System`` aspect is used to define a system of
166 dimensions that will be used in subsequent subtype declarations with
167 ``Dimension`` aspects that reference this system. The syntax is::
168
169 with Dimension_System => (DIMENSION {, DIMENSION});
170
171 DIMENSION ::= ([Unit_Name =>] IDENTIFIER,
172 [Unit_Symbol =>] SYMBOL,
173 [Dim_Symbol =>] SYMBOL)
174
175 SYMBOL ::= CHARACTER_LITERAL | STRING_LITERAL
176
177
178 This aspect is applied to a type, which must be a numeric derived type
179 (typically a floating-point type), that
180 will represent values within the dimension system. Each ``DIMENSION``
181 corresponds to one particular dimension. A maximum of 7 dimensions may
182 be specified. ``Unit_Name`` is the name of the dimension (for example
183 ``Meter``). ``Unit_Symbol`` is the shorthand used for quantities
184 of this dimension (for example ``m`` for ``Meter``).
185 ``Dim_Symbol`` gives
186 the identification within the dimension system (typically this is a
187 single letter, e.g. ``L`` standing for length for unit name ``Meter``).
188 The ``Unit_Symbol`` is used in formatted output of dimensioned quantities.
189 The ``Dim_Symbol`` is used in error messages when numeric operations have
190 inconsistent dimensions.
191
192 GNAT provides the standard definition of the International MKS system in
193 the run-time package ``System.Dim.Mks``. You can easily define
194 similar packages for cgs units or British units, and define conversion factors
195 between values in different systems. The MKS system is characterized by the
196 following aspect:
197
198 .. code-block:: ada
199
200 type Mks_Type is new Long_Long_Float with
201 Dimension_System => (
202 (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'),
203 (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'),
204 (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'),
205 (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'),
206 (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => '@'),
207 (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'),
208 (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J'));
209
210
211 Note that in the above type definition, we use the ``at`` symbol (``@``) to
212 represent a theta character (avoiding the use of extended Latin-1
213 characters in this context).
214
215 See section 'Performing Dimensionality Analysis in GNAT' in the GNAT Users
216 Guide for detailed examples of use of the dimension system.
217
218 Aspect Disable_Controlled
219 =========================
220 .. index:: Disable_Controlled
221
222 The aspect ``Disable_Controlled`` is defined for controlled record types. If
223 active, this aspect causes suppression of all related calls to ``Initialize``,
224 ``Adjust``, and ``Finalize``. The intended use is for conditional compilation,
225 where for example you might want a record to be controlled or not depending on
226 whether some run-time check is enabled or suppressed.
227
228 Aspect Effective_Reads
229 ======================
230 .. index:: Effective_Reads
231
232 This aspect is equivalent to :ref:`pragma Effective_Reads<Pragma-Effective_Reads>`.
233
234 Aspect Effective_Writes
235 =======================
236 .. index:: Effective_Writes
237
238 This aspect is equivalent to :ref:`pragma Effective_Writes<Pragma-Effective_Writes>`.
239
240 Aspect Extensions_Visible
241 =========================
242 .. index:: Extensions_Visible
243
244 This aspect is equivalent to :ref:`pragma Extensions_Visible<Pragma-Extensions_Visible>`.
245
246 Aspect Favor_Top_Level
247 ======================
248 .. index:: Favor_Top_Level
249
250 This boolean aspect is equivalent to :ref:`pragma Favor_Top_Level<Pragma-Favor_Top_Level>`.
251
252 Aspect Ghost
253 =============
254 .. index:: Ghost
255
256 This aspect is equivalent to :ref:`pragma Ghost<Pragma-Ghost>`.
257
258 Aspect Global
259 =============
260 .. index:: Global
261
262 This aspect is equivalent to :ref:`pragma Global<Pragma-Global>`.
263
264 Aspect Initial_Condition
265 ========================
266 .. index:: Initial_Condition
267
268 This aspect is equivalent to :ref:`pragma Initial_Condition<Pragma-Initial_Condition>`.
269
270 Aspect Initializes
271 ==================
272 .. index:: Initializes
273
274 This aspect is equivalent to :ref:`pragma Initializes<Pragma-Initializes>`.
275
276 Aspect Inline_Always
277 ====================
278 .. index:: Inline_Always
279
280 This boolean aspect is equivalent to :ref:`pragma Inline_Always<Pragma-Inline_Always>`.
281
282 Aspect Invariant
283 ================
284 .. index:: Invariant
285
286 This aspect is equivalent to :ref:`pragma Invariant<Pragma-Invariant>`. It is a
287 synonym for the language defined aspect ``Type_Invariant`` except
288 that it is separately controllable using pragma ``Assertion_Policy``.
289
290 Aspect Invariant'Class
291 ======================
292 .. index:: Invariant'Class
293
294 This aspect is equivalent to :ref:`pragma Type_Invariant_Class<Pragma-Type_Invariant_Class>`. It is a
295 synonym for the language defined aspect ``Type_Invariant'Class`` except
296 that it is separately controllable using pragma ``Assertion_Policy``.
297
298 Aspect Iterable
299 ===============
300 .. index:: Iterable
301
302 This aspect provides a light-weight mechanism for loops and quantified
303 expressions over container types, without the overhead imposed by the tampering
304 checks of standard Ada 2012 iterators. The value of the aspect is an aggregate
305 with six named components, of which the last three are optional: ``First``,
306 ``Next``, ``Has_Element``, ``Element``, ``Last``, and ``Previous``.
307 When only the first three components are specified, only the
308 ``for .. in`` form of iteration over cursors is available. When ``Element``
309 is specified, both this form and the ``for .. of`` form of iteration over
310 elements are available. If the last two components are specified, reverse
311 iterations over the container can be specified (analogous to what can be done
312 over predefined containers that support the ``Reverse_Iterator`` interface).
313 The following is a typical example of use:
314
315 .. code-block:: ada
316
317 type List is private with
318 Iterable => (First => First_Cursor,
319 Next => Advance,
320 Has_Element => Cursor_Has_Element
321 [,Element => Get_Element]
322 [,Last => Last_Cursor]
323 [,Previous => Retreat]);
324
325 * The values of ``First`` and ``Last`` are primitive operations of the
326 container type that return a ``Cursor``, which must be a type declared in
327 the container package or visible from it. For example:
328
329 .. code-block:: ada
330
331 function First_Cursor (Cont : Container) return Cursor;
332 function Last_Cursor (Cont : Container) return Cursor;
333
334 * The values of ``Next`` and ``Previous`` are primitive operations of the container type that take
335 both a container and a cursor and yield a cursor. For example:
336
337 .. code-block:: ada
338
339 function Advance (Cont : Container; Position : Cursor) return Cursor;
340 function Retreat (Cont : Container; Position : Cursor) return Cursor;
341
342 * The value of ``Has_Element`` is a primitive operation of the container type
343 that takes both a container and a cursor and yields a boolean. For example:
344
345 .. code-block:: ada
346
347 function Cursor_Has_Element (Cont : Container; Position : Cursor) return Boolean;
348
349 * The value of ``Element`` is a primitive operation of the container type that
350 takes both a container and a cursor and yields an ``Element_Type``, which must
351 be a type declared in the container package or visible from it. For example:
352
353 .. code-block:: ada
354
355 function Get_Element (Cont : Container; Position : Cursor) return Element_Type;
356
357 This aspect is used in the GNAT-defined formal container packages.
358
359 Aspect Linker_Section
360 =====================
361 .. index:: Linker_Section
362
363 This aspect is equivalent to :ref:`pragma Linker_Section<Pragma-Linker_Section>`.
364
365 Aspect Lock_Free
366 ================
367 .. index:: Lock_Free
368
369 This boolean aspect is equivalent to :ref:`pragma Lock_Free<Pragma-Lock_Free>`.
370
371 Aspect Max_Queue_Length
372 =======================
373 .. index:: Max_Queue_Length
374
375 This aspect is equivalent to :ref:`pragma Max_Queue_Length<Pragma-Max_Queue_Length>`.
376
377 Aspect No_Caching
378 =================
379 .. index:: No_Caching
380
381 This boolean aspect is equivalent to :ref:`pragma No_Caching<Pragma-No_Caching>`.
382
383 Aspect No_Elaboration_Code_All
384 ==============================
385 .. index:: No_Elaboration_Code_All
386
387 This aspect is equivalent to :ref:`pragma No_Elaboration_Code_All<Pragma-No_Elaboration_Code_All>`
388 for a program unit.
389
390 Aspect No_Inline
391 ================
392 .. index:: No_Inline
393
394 This boolean aspect is equivalent to :ref:`pragma No_Inline<Pragma-No_Inline>`.
395
396 Aspect No_Tagged_Streams
397 ========================
398 .. index:: No_Tagged_Streams
399
400 This aspect is equivalent to :ref:`pragma No_Tagged_Streams<Pragma-No_Tagged_Streams>` with an
401 argument specifying a root tagged type (thus this aspect can only be
402 applied to such a type).
403
404 Aspect No_Task_Parts
405 ========================
406 .. index:: No_Task_Parts
407
408 Applies to a type. If True, requires that the type and any descendants
409 do not have any task parts. The rules for this aspect are the same as
410 for the language-defined No_Controlled_Parts aspect (see RM-H.4.1),
411 replacing "controlled" with "task".
412
413 If No_Task_Parts is True for a type T, then the compiler can optimize
414 away certain tasking-related code that would otherwise be needed
415 for T'Class, because descendants of T might contain tasks.
416
417 Aspect Object_Size
418 ==================
419 .. index:: Object_Size
420
421 This aspect is equivalent to :ref:`attribute Object_Size<Attribute-Object_Size>`.
422
423 Aspect Obsolescent
424 ==================
425 .. index:: Obsolescent
426
427 This aspect is equivalent to :ref:`pragma Obsolescent<Pragma_Obsolescent>`. Note that the
428 evaluation of this aspect happens at the point of occurrence, it is not
429 delayed until the freeze point.
430
431 Aspect Part_Of
432 ==============
433 .. index:: Part_Of
434
435 This aspect is equivalent to :ref:`pragma Part_Of<Pragma-Part_Of>`.
436
437 Aspect Persistent_BSS
438 =====================
439 .. index:: Persistent_BSS
440
441 This boolean aspect is equivalent to :ref:`pragma Persistent_BSS<Pragma-Persistent_BSS>`.
442
443 Aspect Predicate
444 ================
445 .. index:: Predicate
446
447 This aspect is equivalent to :ref:`pragma Predicate<Pragma-Predicate>`. It is thus
448 similar to the language defined aspects ``Dynamic_Predicate``
449 and ``Static_Predicate`` except that whether the resulting
450 predicate is static or dynamic is controlled by the form of the
451 expression. It is also separately controllable using pragma
452 ``Assertion_Policy``.
453
454 Aspect Pure_Function
455 ====================
456 .. index:: Pure_Function
457
458 This boolean aspect is equivalent to :ref:`pragma Pure_Function<Pragma-Pure_Function>`.
459
460 Aspect Refined_Depends
461 ======================
462 .. index:: Refined_Depends
463
464 This aspect is equivalent to :ref:`pragma Refined_Depends<Pragma-Refined_Depends>`.
465
466 Aspect Refined_Global
467 =====================
468 .. index:: Refined_Global
469
470 This aspect is equivalent to :ref:`pragma Refined_Global<Pragma-Refined_Global>`.
471
472 Aspect Refined_Post
473 ===================
474 .. index:: Refined_Post
475
476 This aspect is equivalent to :ref:`pragma Refined_Post<Pragma-Refined_Post>`.
477
478 Aspect Refined_State
479 ====================
480 .. index:: Refined_State
481
482 This aspect is equivalent to :ref:`pragma Refined_State<Pragma-Refined_State>`.
483
484 Aspect Relaxed_Initialization
485 =============================
486 .. index:: Refined_Initialization
487
488 For the syntax and semantics of this aspect, see the SPARK 2014 Reference
489 Manual, section 6.10.
490
491 Aspect Remote_Access_Type
492 =========================
493 .. index:: Remote_Access_Type
494
495 This aspect is equivalent to :ref:`pragma Remote_Access_Type<Pragma-Remote_Access_Type>`.
496
497 Aspect Secondary_Stack_Size
498 ===========================
499
500 .. index:: Secondary_Stack_Size
501
502 This aspect is equivalent to :ref:`pragma Secondary_Stack_Size<Pragma-Secondary_Stack_Size>`.
503
504
505 Aspect Scalar_Storage_Order
506 ===========================
507 .. index:: Scalar_Storage_Order
508
509 This aspect is equivalent to a :ref:`attribute Scalar_Storage_Order<Attribute-Scalar_Storage_Order>`.
510
511 Aspect Shared
512 =============
513 .. index:: Shared
514
515 This boolean aspect is equivalent to :ref:`pragma Shared<Pragma-Shared>`
516 and is thus a synonym for aspect ``Atomic``.
517
518 Aspect Simple_Storage_Pool
519 ==========================
520 .. index:: Simple_Storage_Pool
521
522 This aspect is equivalent to :ref:`attribute Simple_Storage_Pool<Attribute_Simple_Storage_Pool>`.
523
524 Aspect Simple_Storage_Pool_Type
525 ===============================
526 .. index:: Simple_Storage_Pool_Type
527
528 This boolean aspect is equivalent to :ref:`pragma Simple_Storage_Pool_Type<Pragma-Simple_Storage_Pool_Type>`.
529
530 Aspect SPARK_Mode
531 =================
532 .. index:: SPARK_Mode
533
534 This aspect is equivalent to :ref:`pragma SPARK_Mode<Pragma-SPARK_Mode>` and
535 may be specified for either or both of the specification and body
536 of a subprogram or package.
537
538 Aspect Suppress_Debug_Info
539 ==========================
540 .. index:: Suppress_Debug_Info
541
542 This boolean aspect is equivalent to :ref:`pragma Suppress_Debug_Info<Pragma-Suppress_Debug_Info>`.
543
544 Aspect Suppress_Initialization
545 ==============================
546 .. index:: Suppress_Initialization
547
548 This boolean aspect is equivalent to :ref:`pragma Suppress_Initialization<Pragma-Suppress_Initialization>`.
549
550 Aspect Test_Case
551 ================
552 .. index:: Test_Case
553
554 This aspect is equivalent to :ref:`pragma Test_Case<Pragma-Test_Case>`.
555
556 Aspect Thread_Local_Storage
557 ===========================
558 .. index:: Thread_Local_Storage
559
560 This boolean aspect is equivalent to :ref:`pragma Thread_Local_Storage<Pragma-Thread_Local_Storage>`.
561
562 Aspect Universal_Aliasing
563 =========================
564 .. index:: Universal_Aliasing
565
566 This boolean aspect is equivalent to :ref:`pragma Universal_Aliasing<Pragma-Universal_Aliasing>`.
567
568 Aspect Unmodified
569 =================
570 .. index:: Unmodified
571
572 This boolean aspect is equivalent to :ref:`pragma Unmodified<Pragma-Unmodified>`.
573
574 Aspect Unreferenced
575 ===================
576 .. index:: Unreferenced
577
578 This boolean aspect is equivalent to :ref:`pragma Unreferenced<Pragma-Unreferenced>`.
579
580 When using the ``-gnat2022`` switch, this aspect is also supported on formal
581 parameters, which is in particular the only form possible for expression
582 functions.
583
584 Aspect Unreferenced_Objects
585 ===========================
586 .. index:: Unreferenced_Objects
587
588 This boolean aspect is equivalent to :ref:`pragma Unreferenced_Objects<Pragma-Unreferenced_Objects>`.
589
590 Aspect Value_Size
591 =================
592 .. index:: Value_Size
593
594 This aspect is equivalent to :ref:`attribute Value_Size<Attribute-Value_Size>`.
595
596 Aspect Volatile_Full_Access
597 ===========================
598 .. index:: Volatile_Full_Access
599
600 This boolean aspect is equivalent to :ref:`pragma Volatile_Full_Access<Pragma-Volatile_Full_Access>`.
601
602 Aspect Volatile_Function
603 ===========================
604 .. index:: Volatile_Function
605
606 This boolean aspect is equivalent to :ref:`pragma Volatile_Function<Pragma-Volatile_Function>`.
607
608 Aspect Warnings
609 ===============
610 .. index:: Warnings
611
612 This aspect is equivalent to the two argument form of :ref:`pragma Warnings<Pragma_Warnings>`,
613 where the first argument is ``ON`` or ``OFF`` and the second argument
614 is the entity.