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
323 * The value denoted by ``First`` must denote a primitive operation of the
324 container type that returns a ``Cursor``, which must a be a type declared in
325 the container package or visible from it. For example:
326
327 .. code-block:: ada
328
329 function First_Cursor (Cont : Container) return Cursor;
330
331 * The value of ``Next`` is a primitive operation of the container type that takes
332 both a container and a cursor and yields a cursor. For example:
333
334 .. code-block:: ada
335
336 function Advance (Cont : Container; Position : Cursor) return Cursor;
337
338 * The value of ``Has_Element`` is a primitive operation of the container type
339 that takes both a container and a cursor and yields a boolean. For example:
340
341 .. code-block:: ada
342
343 function Cursor_Has_Element (Cont : Container; Position : Cursor) return Boolean;
344
345 * The value of ``Element`` is a primitive operation of the container type that
346 takes both a container and a cursor and yields an ``Element_Type``, which must
347 be a type declared in the container package or visible from it. For example:
348
349 .. code-block:: ada
350
351 function Get_Element (Cont : Container; Position : Cursor) return Element_Type;
352
353 This aspect is used in the GNAT-defined formal container packages.
354
355 Aspect Linker_Section
356 =====================
357 .. index:: Linker_Section
358
359 This aspect is equivalent to :ref:`pragma Linker_Section<Pragma-Linker_Section>`.
360
361 Aspect Lock_Free
362 ================
363 .. index:: Lock_Free
364
365 This boolean aspect is equivalent to :ref:`pragma Lock_Free<Pragma-Lock_Free>`.
366
367 Aspect Max_Queue_Length
368 =======================
369 .. index:: Max_Queue_Length
370
371 This aspect is equivalent to :ref:`pragma Max_Queue_Length<Pragma-Max_Queue_Length>`.
372
373 Aspect No_Caching
374 =================
375 .. index:: No_Caching
376
377 This boolean aspect is equivalent to :ref:`pragma No_Caching<Pragma-No_Caching>`.
378
379 Aspect No_Elaboration_Code_All
380 ==============================
381 .. index:: No_Elaboration_Code_All
382
383 This aspect is equivalent to :ref:`pragma No_Elaboration_Code_All<Pragma-No_Elaboration_Code_All>`
384 for a program unit.
385
386 Aspect No_Inline
387 ================
388 .. index:: No_Inline
389
390 This boolean aspect is equivalent to :ref:`pragma No_Inline<Pragma-No_Inline>`.
391
392 Aspect No_Tagged_Streams
393 ========================
394 .. index:: No_Tagged_Streams
395
396 This aspect is equivalent to :ref:`pragma No_Tagged_Streams<Pragma-No_Tagged_Streams>` with an
397 argument specifying a root tagged type (thus this aspect can only be
398 applied to such a type).
399
400 Aspect No_Task_Parts
401 ========================
402 .. index:: No_Task_Parts
403
404 Applies to a type. If True, requires that the type and any descendants
405 do not have any task parts. The rules for this aspect are the same as
406 for the language-defined No_Controlled_Parts aspect (see RM-H.4.1),
407 replacing "controlled" with "task".
408
409 If No_Task_Parts is True for a type T, then the compiler can optimize
410 away certain tasking-related code that would otherwise be needed
411 for T'Class, because descendants of T might contain tasks.
412
413 Aspect Object_Size
414 ==================
415 .. index:: Object_Size
416
417 This aspect is equivalent to :ref:`attribute Object_Size<Attribute-Object_Size>`.
418
419 Aspect Obsolescent
420 ==================
421 .. index:: Obsolsecent
422
423 This aspect is equivalent to :ref:`pragma Obsolescent<Pragma_Obsolescent>`. Note that the
424 evaluation of this aspect happens at the point of occurrence, it is not
425 delayed until the freeze point.
426
427 Aspect Part_Of
428 ==============
429 .. index:: Part_Of
430
431 This aspect is equivalent to :ref:`pragma Part_Of<Pragma-Part_Of>`.
432
433 Aspect Persistent_BSS
434 =====================
435 .. index:: Persistent_BSS
436
437 This boolean aspect is equivalent to :ref:`pragma Persistent_BSS<Pragma-Persistent_BSS>`.
438
439 Aspect Predicate
440 ================
441 .. index:: Predicate
442
443 This aspect is equivalent to :ref:`pragma Predicate<Pragma-Predicate>`. It is thus
444 similar to the language defined aspects ``Dynamic_Predicate``
445 and ``Static_Predicate`` except that whether the resulting
446 predicate is static or dynamic is controlled by the form of the
447 expression. It is also separately controllable using pragma
448 ``Assertion_Policy``.
449
450 Aspect Pure_Function
451 ====================
452 .. index:: Pure_Function
453
454 This boolean aspect is equivalent to :ref:`pragma Pure_Function<Pragma-Pure_Function>`.
455
456 Aspect Refined_Depends
457 ======================
458 .. index:: Refined_Depends
459
460 This aspect is equivalent to :ref:`pragma Refined_Depends<Pragma-Refined_Depends>`.
461
462 Aspect Refined_Global
463 =====================
464 .. index:: Refined_Global
465
466 This aspect is equivalent to :ref:`pragma Refined_Global<Pragma-Refined_Global>`.
467
468 Aspect Refined_Post
469 ===================
470 .. index:: Refined_Post
471
472 This aspect is equivalent to :ref:`pragma Refined_Post<Pragma-Refined_Post>`.
473
474 Aspect Refined_State
475 ====================
476 .. index:: Refined_State
477
478 This aspect is equivalent to :ref:`pragma Refined_State<Pragma-Refined_State>`.
479
480 Aspect Relaxed_Initialization
481 =============================
482 .. index:: Refined_Initialization
483
484 For the syntax and semantics of this aspect, see the SPARK 2014 Reference
485 Manual, section 6.10.
486
487 Aspect Remote_Access_Type
488 =========================
489 .. index:: Remote_Access_Type
490
491 This aspect is equivalent to :ref:`pragma Remote_Access_Type<Pragma-Remote_Access_Type>`.
492
493 Aspect Secondary_Stack_Size
494 ===========================
495
496 .. index:: Secondary_Stack_Size
497
498 This aspect is equivalent to :ref:`pragma Secondary_Stack_Size<Pragma-Secondary_Stack_Size>`.
499
500
501 Aspect Scalar_Storage_Order
502 ===========================
503 .. index:: Scalar_Storage_Order
504
505 This aspect is equivalent to a :ref:`attribute Scalar_Storage_Order<Attribute-Scalar_Storage_Order>`.
506
507 Aspect Shared
508 =============
509 .. index:: Shared
510
511 This boolean aspect is equivalent to :ref:`pragma Shared<Pragma-Shared>`
512 and is thus a synonym for aspect ``Atomic``.
513
514 Aspect Simple_Storage_Pool
515 ==========================
516 .. index:: Simple_Storage_Pool
517
518 This aspect is equivalent to :ref:`attribute Simple_Storage_Pool<Attribute_Simple_Storage_Pool>`.
519
520 Aspect Simple_Storage_Pool_Type
521 ===============================
522 .. index:: Simple_Storage_Pool_Type
523
524 This boolean aspect is equivalent to :ref:`pragma Simple_Storage_Pool_Type<Pragma-Simple_Storage_Pool_Type>`.
525
526 Aspect SPARK_Mode
527 =================
528 .. index:: SPARK_Mode
529
530 This aspect is equivalent to :ref:`pragma SPARK_Mode<Pragma-SPARK_Mode>` and
531 may be specified for either or both of the specification and body
532 of a subprogram or package.
533
534 Aspect Suppress_Debug_Info
535 ==========================
536 .. index:: Suppress_Debug_Info
537
538 This boolean aspect is equivalent to :ref:`pragma Suppress_Debug_Info<Pragma-Suppress_Debug_Info>`.
539
540 Aspect Suppress_Initialization
541 ==============================
542 .. index:: Suppress_Initialization
543
544 This boolean aspect is equivalent to :ref:`pragma Suppress_Initialization<Pragma-Suppress_Initialization>`.
545
546 Aspect Test_Case
547 ================
548 .. index:: Test_Case
549
550 This aspect is equivalent to :ref:`pragma Test_Case<Pragma-Test_Case>`.
551
552 Aspect Thread_Local_Storage
553 ===========================
554 .. index:: Thread_Local_Storage
555
556 This boolean aspect is equivalent to :ref:`pragma Thread_Local_Storage<Pragma-Thread_Local_Storage>`.
557
558 Aspect Universal_Aliasing
559 =========================
560 .. index:: Universal_Aliasing
561
562 This boolean aspect is equivalent to :ref:`pragma Universal_Aliasing<Pragma-Universal_Aliasing>`.
563
564 Aspect Unmodified
565 =================
566 .. index:: Unmodified
567
568 This boolean aspect is equivalent to :ref:`pragma Unmodified<Pragma-Unmodified>`.
569
570 Aspect Unreferenced
571 ===================
572 .. index:: Unreferenced
573
574 This boolean aspect is equivalent to :ref:`pragma Unreferenced<Pragma-Unreferenced>`.
575
576 When using the ``-gnat2022`` switch, this aspect is also supported on formal
577 parameters, which is in particular the only form possible for expression
578 functions.
579
580 Aspect Unreferenced_Objects
581 ===========================
582 .. index:: Unreferenced_Objects
583
584 This boolean aspect is equivalent to :ref:`pragma Unreferenced_Objects<Pragma-Unreferenced_Objects>`.
585
586 Aspect Value_Size
587 =================
588 .. index:: Value_Size
589
590 This aspect is equivalent to :ref:`attribute Value_Size<Attribute-Value_Size>`.
591
592 Aspect Volatile_Full_Access
593 ===========================
594 .. index:: Volatile_Full_Access
595
596 This boolean aspect is equivalent to :ref:`pragma Volatile_Full_Access<Pragma-Volatile_Full_Access>`.
597
598 Aspect Volatile_Function
599 ===========================
600 .. index:: Volatile_Function
601
602 This boolean aspect is equivalent to :ref:`pragma Volatile_Function<Pragma-Volatile_Function>`.
603
604 Aspect Warnings
605 ===============
606 .. index:: Warnings
607
608 This aspect is equivalent to the two argument form of :ref:`pragma Warnings<Pragma_Warnings>`,
609 where the first argument is ``ON`` or ``OFF`` and the second argument
610 is the entity.