Debian Codegraph @

gcc/ada/doc/gnat_rm/gnat_language_extensions.rst

raw
1 .. _GNAT_Language_Extensions:
2
3 ************************
4 GNAT language extensions
5 ************************
6
7 The GNAT compiler implements a certain number of language extensions on top of
8 the latest Ada standard, implementing its own extended superset of Ada.
9
10 There are two sets of language extensions:
11
12 * The first is the curated set. The features in that set are features that we
13 consider being worthy additions to the Ada language, and that we want to make
14 available to users early on.
15
16 * The second is the experimental set. It includes the first, but also
17 experimental features, which are considered experimental because
18 they're still in an early prototyping phase.
19 These features might be removed or heavily modified at any time.
20
21 How to activate the extended GNAT Ada superset
22 ==============================================
23
24 There are two ways to activate the extended GNAT Ada superset:
25
26 * The :ref:`Pragma Extensions_Allowed<Pragma_Extensions_Allowed>`. To activate
27 the curated set of extensions, you should use
28
29 .. code-block:: ada
30
31 pragma Extensions_Allowed (On)
32
33 As a configuration pragma, you can either put it at the beginning of a source
34 file, or in a ``.adc`` file corresponding to your project.
35
36 * The ``-gnatX`` command-line option will
37 activate the curated subset of extensions.
38
39 .. attention:: You can activate the experimental set of extensions
40 in addition by using either
41 the ``-gnatX0`` command-line option, or the pragma ``Extensions_Allowed`` with
42 ``All_Extensions`` as an argument. However, it is not recommended you use
43 this subset for serious projects; it is only meant as a technology preview
44 for use in playground experiments.
45
46 .. _Curated_Language_Extensions:
47
48 Curated Extensions
49 ==================
50
51 Features activated via ``-gnatX`` or
52 ``pragma Extensions_Allowed (On)``.
53
54 Local Declarations Without Block
55 --------------------------------
56
57 A ``basic_declarative_item`` may appear at the place of any statement. This
58 avoids the heavy syntax of block_statements just to declare something locally.
59
60 The only valid kinds of declarations for now are ``object_declaration``,
61 ``object_renaming_declaration``, ``use_package_clause``, and
62 ``use_type_clause``.
63
64 For example:
65
66 .. code-block:: ada
67
68 if X > 5 then
69 X := X + 1;
70
71 Squared : constant Integer := X**2;
72
73 X := X + Squared;
74 end if;
75
76 It is generally a good practice to declare local variables (or constants) with as
77 short a lifetime as possible. However, introducing a declare block to accomplish
78 this is a relatively heavy syntactic load along with a traditional extra level
79 of indentation. The alternative syntax supported here allows declarations
80 in any statement sequence.
81 The lifetime of such local declarations is until the end of
82 the enclosing construct. The same enclosing construct cannot contain several
83 declarations of the same defining name; however, overriding symbols from higher-level
84 scopes works similarly to the explicit ``declare`` block.
85
86 If the enclosing construct allows an exception handler (such as an accept
87 statement, begin-except-end block or a subprogram body), declarations that
88 appear at the place of a statement are *not* visible within the handler. Only
89 declarations that precede the beginning of the construct with an exception
90 handler would be visible in this handler.
91
92 .. attention::
93
94 Here are a couple of examples illustrating the scoping rules described above.
95
96 1. Those declarations are not visible from the potential exception handler:
97
98 .. code-block:: ada
99
100 begin
101 A : Integer
102 ...
103 exception
104 when others =>
105 Put_Line (A'Image) -- ILLEGAL
106 end;
107
108 2. The following is legal
109
110 .. code-block:: ada
111
112 declare
113 A : Integer := 10;
114 begin
115 A : Integer := 12;
116 end;
117
118 because it is roughly expanded into
119
120 .. code-block:: ada
121
122 declare
123 A : Integer := 10;
124 begin
125 declare
126 A : Integer := 12;
127 begin
128 ...
129 end;
130 end;
131
132 And as such the second ``A`` declaration is hiding the first one.
133
134 Deep delta Aggregates
135 ---------------------
136
137 Ada 2022's delta aggregates are extended to allow deep updates.
138
139 A delta aggregate may be used to specify new values for subcomponents of the
140 copied base value, instead of only new values for direct components of the
141 copied base value. This allows a more compact expression of updated values with
142 a single delta aggregate, instead of multiple nested delta aggregates.
143
144 The syntax of delta aggregates in the extended version is the following:
145
146 Syntax
147 ^^^^^^
148
149 .. code::
150
151 delta_aggregate ::= record_delta_aggregate | array_delta_aggregate
152
153 record_delta_aggregate ::=
154 ( base_expression with delta record_subcomponent_association_list )
155
156 record_subcomponent_association_list ::=
157 record_subcomponent_association {, record_subcomponent_association}
158
159 record_subcomponent_association ::=
160 record_subcomponent_choice_list => expression
161
162 record_subcomponent_choice_list ::=
163 record_subcomponent_choice {'|' record_subcomponent_choice}
164
165 record_subcomponent_choice ::=
166 component_selector_name
167 | record_subcomponent_choice (expression)
168 | record_subcomponent_choice . component_selector_name
169
170 array_delta_aggregate ::=
171 ( base_expression with delta array_component_association_list )
172 | '[' base_expression with delta array_component_association_list ']'
173 | ( base_expression with delta array_subcomponent_association_list )
174 | '[' base_expression with delta array_subcomponent_association_list ']'
175
176 array_subcomponent_association_list ::=
177 array_subcomponent_association {, array_subcomponent_association}
178
179 array_subcomponent_association ::=
180 array_subcomponent_choice_list => expression
181
182 array_subcomponent_choice_list ::=
183 array_subcomponent_choice {'|' array_subcomponent_choice}
184
185 array_subcomponent_choice ::=
186 ( expression )
187 | array_subcomponent_choice (expression)
188 | array_subcomponent_choice . component_selector_name
189
190 Legality Rules
191 ^^^^^^^^^^^^^^
192
193 1. For an ``array_delta_aggregate``, the discrete_choice shall not be **others**.
194
195 2. For an ``array_delta_aggregate``, the dimensionality of the type of the
196 ``delta_aggregate`` shall be 1.
197
198 3. For an ``array_delta_aggregate``, the ``base_expression`` and each
199 expression in every ``array_component_association`` or
200 ``array_subcomponent_association`` shall be of a nonlimited type.
201
202 4. For a ``record_delta_aggregate``, no ``record_subcomponent_choices`` that
203 consists of only ``component_selector_names`` shall be the same or a prefix
204 of another record_subcomponent_choice.
205
206 5. For an ``array_subcomponent_choice`` or a ``record_subcomponent_choice`` the
207 ``component_selector_name`` shall not be a subcomponent that depends on
208 discriminants of an unconstrained record subtype with defaulted
209 discriminants unless its prefix consists of only
210 ``component_selector_names``.
211
212 [Rationale: As a result of this rule, accessing the subcomponent can only
213 lead to a discriminant check failure if the subcomponent was not present in
214 the object denoted by the base_expression, prior to any update.]
215
216 Dynamic Semantics
217 ^^^^^^^^^^^^^^^^^
218
219 The evaluation of a ``delta_aggregate`` begins with the evaluation of the
220 ``base_expression`` of the delta_aggregate; then that value is used to create
221 and initialize the anonymous object of the aggregate. The bounds of the
222 anonymous object of an ``array_delta_aggregate`` and the discriminants (if any)
223 of the anonymous object of a ``record_delta_aggregate`` are those of the
224 ``base_expression``.
225
226 If a ``record_delta_aggregate`` is of a specific tagged type, its tag is that
227 of the specific type; if it is of a class-wide type, its tag is that of the
228 base_expression.
229
230 For a ``delta_aggregate``, for each ``discrete_choice`` or each subcomponent
231 associated with a ``record_subcomponent_associated``,
232 ``array_component_association`` or ``array_subcomponent_association`` (in the
233 order given in the enclosing ``discrete_choice_list`` or
234 ``subcomponent_association_list``, respectively):
235
236 - if the associated subcomponent belongs to a variant, a check is made that the
237 values of the governing discriminants are such that the anonymous object has
238 this component. The exception ``Constraint_Error`` is raised if this check fails.
239
240 - if the associated subcomponent is a subcomponent of an array, then for each
241 represented index value (in ascending order, if the ``discrete_choice``
242 represents a range):
243
244 * the index value is converted to the index type of the array type.
245
246 * a check is made that the index value belongs to the index range of the
247 corresponding array part of the anonymous object; ``Constraint_Error`` is
248 raised if this check fails.
249
250 * the expression of the ``record_subcomponent_association``,
251 ``array_component_association`` or ``array_subcomponent_association`` is
252 evaluated, converted to the nominal subtype of the associated subcomponent,
253 and assigned to the corresponding subcomponent of the anonymous object.
254
255 Examples
256 ^^^^^^^^
257
258 .. code-block:: ada
259 :linenos:
260
261 declare
262 type Point is record
263 X, Y : Integer;
264 end record;
265
266 type Segment is array (1 .. 2) of Point;
267 type Triangle is array (1 .. 3) of Segment;
268
269 S : Segment := (1 .. 2 => (0, 0));
270 T : Triangle := (1 .. 3 => (1 .. 2 => (0, 0)));
271 begin
272 S := (S with delta (1).X | (2).Y => 12, (1).Y => 15);
273
274 pragma Assert (S (1).X = 12);
275 pragma Assert (S (2).Y = 12);
276 pragma Assert (S (1).Y = 15);
277
278 T := (T with delta (2)(1).Y => 18);
279 pragma Assert (T (2)(1).Y = 18);
280 end;
281
282
283 Fixed lower bounds for array types and subtypes
284 -----------------------------------------------
285
286 Unconstrained array types and subtypes can be specified with a lower bound that
287 is fixed to a certain value, by writing an index range that uses the syntax
288 ``<lower-bound-expression> .. <>``. This guarantees that all objects of the
289 type or subtype will have the specified lower bound.
290
291 For example, a matrix type with fixed lower bounds of zero for each dimension
292 can be declared by the following:
293
294 .. code-block:: ada
295
296 type Matrix is
297 array (Natural range 0 .. <>, Natural range 0 .. <>) of Integer;
298
299 Objects of type ``Matrix`` declared with an index constraint must have index
300 ranges starting at zero:
301
302 .. code-block:: ada
303
304 M1 : Matrix (0 .. 9, 0 .. 19);
305 M2 : Matrix (2 .. 11, 3 .. 22); -- Warning about bounds; will raise CE
306
307 Similarly, a subtype of ``String`` can be declared that specifies the lower
308 bound of objects of that subtype to be ``1``:
309
310 .. code-block:: ada
311
312 subtype String_1 is String (1 .. <>);
313
314 If a string slice is passed to a formal of subtype ``String_1`` in a call to a
315 subprogram ``S``, the slice's bounds will "slide" so that the lower bound is
316 ``1``.
317
318 Within ``S``, the lower bound of the formal is known to be ``1``, so, unlike a
319 normal unconstrained ``String`` formal, there is no need to worry about
320 accounting for other possible lower-bound values. Sliding of bounds also occurs
321 in other contexts, such as for object declarations with an unconstrained
322 subtype with fixed lower bound, as well as in subtype conversions.
323
324 Use of this feature increases safety by simplifying code, and can also improve
325 the efficiency of indexing operations, since the compiler statically knows the
326 lower bound of unconstrained array formals when the formal's subtype has index
327 ranges with static fixed lower bounds.
328
329 Prefixed-view notation for calls to primitive subprograms of untagged types
330 ---------------------------------------------------------------------------
331
332 When operating on an untagged type, if it has any primitive operations, and the
333 first parameter of an operation is of the type (or is an access parameter with
334 an anonymous type that designates the type), you may invoke these operations
335 using an ``object.op(...)`` notation, where the parameter that would normally be
336 the first parameter is brought out front, and the remaining parameters (if any)
337 appear within parentheses after the name of the primitive operation.
338
339 This same notation is already available for tagged types. This extension allows
340 for untagged types. It is allowed for all primitive operations of the type
341 independent of whether they were originally declared in a package spec,
342 or were inherited and/or overridden as part of a derived type
343 declaration occurring anywhere, so long as the first parameter is of the type,
344 or an access parameter designating the type.
345
346 For example:
347
348 .. code-block:: ada
349
350 generic
351 type Elem_Type is private;
352 package Vectors is
353 type Vector is private;
354 procedure Add_Element (V : in out Vector; Elem : Elem_Type);
355 function Nth_Element (V : Vector; N : Positive) return Elem_Type;
356 function Length (V : Vector) return Natural;
357 private
358 function Capacity (V : Vector) return Natural;
359 -- Return number of elements that may be added without causing
360 -- any new allocation of space
361
362 type Vector is ...
363 with Type_Invariant => Vector.Length <= Vector.Capacity;
364 ...
365 end Vectors;
366
367 package Int_Vecs is new Vectors(Integer);
368
369 V : Int_Vecs.Vector;
370 ...
371 V.Add_Element(42);
372 V.Add_Element(-33);
373
374 pragma Assert (V.Length = 2);
375 pragma Assert (V.Nth_Element(1) = 42);
376
377 Expression defaults for generic formal functions
378 ------------------------------------------------
379
380 The declaration of a generic formal function is allowed to specify
381 an expression as a default, using the syntax of an expression function.
382
383 Here is an example of this feature:
384
385 .. code-block:: ada
386
387 generic
388 type T is private;
389 with function Copy (Item : T) return T is (Item); -- Defaults to Item
390 package Stacks is
391
392 type Stack is limited private;
393
394 procedure Push (S : in out Stack; X : T); -- Calls Copy on X
395 function Pop (S : in out Stack) return T; -- Calls Copy to return item
396
397 private
398 -- ...
399 end Stacks;
400
401 If Stacks is instantiated with an explicit actual for Copy,
402 then that will be called when Copy is called in the generic body.
403 If the default is used (i.e. there is no actual corresponding to Copy),
404 then calls to Copy in the instance will simply return Item.
405
406 String interpolation
407 --------------------
408
409 The syntax for string literals is extended to support string interpolation.
410 An interpolated string literal starts with ``f``, immediately before
411 the first double-quote character.
412
413 Within an interpolated string literal, an arbitrary expression, when
414 enclosed in ``{ ... }``, is expanded at run time into the result of calling
415 ``'Image`` on the result of evaluating the expression enclosed by the brace
416 characters, unless it is already a string or a single character.
417
418 Here is an example of this feature where the expressions ``Name`` and ``X + Y``
419 will be evaluated and included in the string.
420
421 .. code-block:: ada
422
423 procedure Test_Interpolation is
424 X : Integer := 12;
425 Y : Integer := 15;
426 Name : String := "Leo";
427 begin
428 Put_Line (f"The name is {Name} and the sum is {X + Y}.");
429 end Test_Interpolation;
430
431 This will print:
432
433 .. code-block:: ada
434
435 The name is Leo and the sum is 27.
436
437 In addition, an escape character (``\``) is provided for inserting certain
438 standard control characters (such as ``\t`` for tabulation or ``\n`` for
439 newline) or to escape characters with special significance to the
440 interpolated string syntax, namely ``"``, ``{``, ``}``,and ``\`` itself.
441
442 ================= =================
443 escaped_character meaning
444 ----------------- -----------------
445 ``\a`` ALERT
446 ``\b`` BACKSPACE
447 ``\f`` FORM FEED
448 ``\n`` LINE FEED
449 ``\r`` CARRIAGE RETURN
450 ``\t`` CHARACTER TABULATION
451 ``\v`` LINE TABULATION
452 ``\0`` NUL
453 ----------------- -----------------
454 ``\\`` ``\``
455 ``\"`` ``"``
456 ``\{`` ``{``
457 ``\}`` ``}``
458 ================= =================
459
460 Note that, unlike normal string literals, doubled double-quote characters have no
461 special significance. So to include a double-quote or a brace character
462 in an interpolated string, they must be preceded by a ``\``.
463 Multiple interpolated strings are concatenated.
464 For example:
465
466 .. code-block:: ada
467
468 Put_Line
469 (f"X = {X} and Y = {Y} and X+Y = {X+Y};\n" &
470 f" a double quote is \" and" &
471 f" an open brace is \{");
472
473 This will print:
474
475 .. code-block:: ada
476
477 X = 12 and Y = 15 and X+Y = 27
478 a double quote is " and an open brace is {
479
480 Constrained attribute for generic objects
481 -----------------------------------------
482
483 The ``Constrained`` attribute is permitted for objects of generic types. The
484 result indicates whether the corresponding actual is constrained.
485
486 ``Static`` aspect on intrinsic functions
487 ----------------------------------------
488
489 The Ada 202x ``Static`` aspect can be specified on Intrinsic imported functions
490 and the compiler will evaluate some of these intrinsics statically, in
491 particular the ``Shift_Left`` and ``Shift_Right`` intrinsics.
492
493 First Controlling Parameter
494 ---------------------------
495
496 A new pragma/aspect, ``First_Controlling_Parameter``, is introduced for tagged
497 types, altering the semantics of primitive/controlling parameters. When a
498 tagged type is marked with this aspect, only subprograms where the first
499 parameter is of that type will be considered dispatching primitives. This
500 pragma/aspect applies to the entire hierarchy, starting from the specified
501 type, without affecting inherited primitives.
502
503 Here is an example of this feature:
504
505 .. code-block:: ada
506
507 package Example is
508 type Root is tagged private;
509
510 procedure P (V : Integer; V2 : Root);
511 -- Primitive
512
513 type Child is tagged private
514 with First_Controlling_Parameter;
515
516 private
517 type Root is tagged null record;
518 type Child is new Root with null record;
519
520 overriding
521 procedure P (V : Integer; V2 : Child);
522 -- Primitive
523
524 procedure P2 (V : Integer; V2 : Child);
525 -- NOT Primitive
526
527 function F return Child; -- NOT Primitive
528
529 function F2 (V : Child) return Child;
530 -- Primitive, but only controlling on the first parameter
531 end Example;
532
533 Note that ``function F2 (V : Child) return Child;`` differs from ``F2 (V : Child)
534 return Child'Class;`` in that the return type is a specific, definite type. This
535 is also distinct from the legacy semantics, where further derivations with
536 added fields would require overriding the function.
537
538 The option ``-gnatw_j``, that you can pass to the compiler directly, enables
539 warnings related to this new language feature. For instance, compiling the
540 example above without this switch produces no warnings, but compiling it with
541 ``-gnatw_j`` generates the following warning on the declaration of procedure P2:
542
543 .. code-block:: ada
544
545 warning: not a dispatching primitive of tagged type "Child"
546 warning: disallowed by First_Controlling_Parameter on "Child"
547
548 For generic formal tagged types, you can specify whether the type has the
549 First_Controlling_Parameter aspect enabled:
550
551 .. code-block:: ada
552
553 generic
554 type T is tagged private with First_Controlling_Parameter;
555 package T is
556 type U is new T with null record;
557 function Foo return U; -- Not a primitive
558 end T;
559
560 For tagged partial views, the value of the aspect must be consistent between
561 the partial and full views:
562
563 .. code-block:: ada
564
565 package R is
566 type T is tagged private;
567 ...
568 private
569 type T is tagged null record with First_Controlling_Parameter; -- ILLEGAL
570 end R;
571
572 Restricting the position of controlling parameter offers several advantages:
573
574 * Simplification of the dispatching rules improves readability of Ada programs.
575 One doesn't need to analyze all subprogram parameters to understand if the given
576 subprogram is a primitive of a certain tagged type.
577
578 * A programmer is free to use any type, including class-wide types, on other
579 parameters of a subprogram, without the need to consider possible effects of
580 overriding a primitive or creating new one.
581
582 * The result of a function is never a controlling result.
583
584
585 .. _Experimental_Language_Extensions:
586
587 Experimental Language Extensions
588 ================================
589
590 Features activated via ``-gnatX0`` or
591 ``pragma Extensions_Allowed (All_Extensions)``.
592
593 Conditional when constructs
594 ---------------------------
595
596 This feature extends the use of ``when`` as a way to condition a control-flow
597 related statement, to all control-flow related statements.
598
599 To do a conditional return in a procedure the following syntax should be used:
600
601 .. code-block:: ada
602
603 procedure P (Condition : Boolean) is
604 begin
605 return when Condition;
606 end P;
607
608 This will return from the procedure if ``Condition`` is true.
609
610 When being used in a function the conditional part comes after the return value:
611
612 .. code-block:: ada
613
614 function Is_Null (I : Integer) return Boolean is
615 begin
616 return True when I = 0;
617 return False;
618 end;
619
620 In a similar way to the ``exit when`` a ``goto ... when`` can be employed:
621
622 .. code-block:: ada
623
624 procedure Low_Level_Optimized is
625 Flags : Bitmapping;
626 begin
627 Do_1 (Flags);
628 goto Cleanup when Flags (1);
629
630 Do_2 (Flags);
631 goto Cleanup when Flags (32);
632
633 -- ...
634
635 <<Cleanup>>
636 -- ...
637 end;
638
639 .. code-block
640
641 To use a conditional raise construct:
642
643 .. code-block:: ada
644
645 procedure Foo is
646 begin
647 raise Error when Imported_C_Func /= 0;
648 end;
649
650 An exception message can also be added:
651
652 .. code-block:: ada
653
654 procedure Foo is
655 begin
656 raise Error with "Unix Error"
657 when Imported_C_Func /= 0;
658 end;
659
660 Storage Model
661 -------------
662
663 This extends Storage Pools into a more efficient model allowing higher performance,
664 easier integration with low footprint embedded run-times and copying data between
665 different pools of memory. The latter is especially useful when working with distributed
666 memory models, in particular to support interactions with GPU.
667
668 Aspect Storage_Model_Type
669 ^^^^^^^^^^^^^^^^^^^^^^^^^^
670
671 A Storage model is a type with a specified ``Storage_Model_Type``
672 aspect, e.g.:
673
674 .. code-block:: Ada
675
676 type A_Model is null record
677 with Storage_Model_Type (...);
678
679 Storage_Model_Type itself accepts six parameters:
680
681 - Address_Type, the type of the address managed by this model. This has to be
682 a scalar type or derived from System.Address.
683 - Allocate, a procedure used for allocating memory in this model
684 - Deallocate, a procedure used for deallocating memory in this model
685 - Copy_To, a procedure used to copy memory from native memory to this model
686 - Copy_From, a procedure used to copy memory from this model to native memory
687 - Storage_Size, a function returning the amount of memory left
688 - Null_Address, a value for the null address value
689
690 By default, Address_Type is System.Address, and the five subprograms
691 perform native operations (e.g. the allocator is the native ``new`` allocator).
692 Users can decide to specify one or more of these. When an Address_Type is
693 specified to be other than System.Address, all of the subprograms have
694 to be specified.
695
696 The prototypes of these procedures are as follows:
697
698 .. code-block:: Ada
699
700 procedure Allocate
701 (Model : in out A_Model;
702 Storage_Address : out Address_Type;
703 Size : Storage_Count;
704 Alignment : Storage_Count);
705
706 procedure Deallocate
707 (Model : in out A_Model;
708 Storage_Address : out Address_Type;
709 Size : Storage_Count;
710 Alignment : Storage_Count);
711
712 procedure Copy_To
713 (Model : in out A_Model;
714 Target : Address_Type;
715 Source : System.Address;
716 Size : Storage_Count);
717
718 procedure Copy_From
719 (Model : in out A_Model;
720 Target : System.Address;
721 Source : Address_Type;
722 Size : Storage_Count);
723
724 function Storage_Size
725 (Pool : A_Model)
726 return Storage_Count;
727
728 Here's an example of how this could be instantiated in the context of CUDA:
729
730 .. code-block:: Ada
731
732 package CUDA_Memory is
733
734 type CUDA_Storage_Model is null record
735 with Storage_Model_Type => (
736 Address_Type => CUDA_Address,
737 Allocate => CUDA_Allocate,
738 Deallocate => CUDA_Deallocate,
739 Copy_To => CUDA_Copy_To,
740 Copy_From => CUDA_Copy_From,
741 Storage_Size => CUDA_Storage_Size,
742 Null_Address => CUDA_Null_Address
743 );
744
745 type CUDA_Address is new System.Address;
746 -- We're assuming for now same address size on host and device
747
748 procedure CUDA_Allocate
749 (Model : in out CUDA_Storage_Model;
750 Storage_Address : out CUDA_Address;
751 Size : Storage_Count;
752 Alignment : Storage_Count);
753
754 procedure CUDA_Deallocate
755 (Model : in out CUDA_Storage_Model;
756 Storage_Address : out CUDA_Address;
757 Size : Storage_Count;
758 Alignment : Storage_Count);
759
760 procedure CUDA_Copy_To
761 (Model : in out CUDA_Storage_Model;
762 Target : CUDA_Address;
763 Source : System.Address;
764 Size : Storage_Count);
765
766 procedure CUDA_Copy_From
767 (Model : in out CUDA_Storage_Model;
768 Target : System.Address;
769 Source : CUDA_Address;
770 Size : Storage_Count);
771
772 function CUDA_Storage_Size
773 (Pool : CUDA_Storage_Model)
774 return Storage_Count return Storage_Count'Last;
775
776 CUDA_Null_Address : constant CUDA_Address :=
777 CUDA_Address (System.Null_Address);
778
779 CUDA_Memory : CUDA_Storage_Model;
780
781 end CUDA_Memory;
782
783 Aspect Designated_Storage_Model
784 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
785
786 A new aspect, Designated_Storage_Model, allows to specify the memory model
787 for the objects pointed by an access type. Under this aspect, allocations
788 and deallocations will come from the specified memory model instead
789 of the standard ones. In addition, if write operations are needed for
790 initialization, or if there is a copy of the target object from and to a
791 standard memory area, the Copy_To and Copy_From functions will be called.
792 It allows to encompass the capabilities of storage pools, e.g.:
793
794 .. code-block:: Ada
795
796 procedure Main is
797 type Integer_Array is array (Integer range <>) of Integer;
798
799 type Host_Array_Access is access all Integer_Array;
800 type Device_Array_Access is access Integer_Array
801 with Designated_Storage_Model => CUDA_Memory;
802
803 procedure Free is new Unchecked_Deallocation
804 (Host_Array_Type, Host_Array_Access);
805 procedure Free is new Unchecked_Deallocation
806 (Device_Array_Type, Device_Array_Access);
807
808 Host_Array : Host_Array_Access := new Integer_Array (1 .. 10);
809
810 Device_Array : Device_Array_Access := new Host_Array (1 .. 10);
811 -- Calls CUDA_Storage_Model.Allocate to allocate the fat pointers and
812 -- the bounds, then CUDA_Storage_Model.Copy_In to copy the values of the
813 -- boundaries.
814 begin
815 Host_Array.all := (others => 0);
816
817 Device_Array.all := Host_Array.all;
818 -- Calls CUDA_Storage_Model.Copy_To to write to the device array from the
819 -- native memory.
820
821 Host_Array.all := Device_Array.all;
822 -- Calls CUDA_Storage_Model.Copy_From to read from the device array and
823 -- write to native memory.
824
825 Free (Host_Array);
826
827 Free (Device_Array);
828 -- Calls CUDA_Storage_Model.Deallocate;
829 end;
830
831 Taking ``'Address`` of an object with a specific memory model returns an object of
832 the type of the address for that memory category, which may be different from
833 System.Address.
834
835 When copying is performed between two specific memory models, the native memory
836 is used as a temporary between the two. E.g.:
837
838 .. code-block:: Ada
839
840 type Foo_I is access Integer with Designated_Storage_Model => Foo;
841 type Bar_I is access Integer with Designated_Storage_Model => Bar;
842
843 X : Foo_I := new Integer;
844 Y : Bar_I := new Integer;
845 begin
846 X.all := Y.all;
847
848 conceptually becomes:
849
850 .. code-block:: Ada
851
852 X : Foo_I := new Integer;
853 T : Integer;
854 Y : Bar_I := new Integer;
855 begin
856 T := Y.all;
857 X.all := T;
858
859 Legacy Storage Pools
860 ^^^^^^^^^^^^^^^^^^^^^
861
862 Legacy Storage Pools are now replaced by a Storage_Model_Type.
863 They are implemented as follows:
864
865 .. code-block:: Ada
866
867 type Root_Storage_Pool is abstract
868 new Ada.Finalization.Limited_Controlled with private
869 with Storage_Model_Type => (
870 Allocate => Allocate,
871 Deallocate => Deallocate,
872 Storage_Size => Storage_Size
873 );
874 pragma Preelaborable_Initialization (Root_Storage_Pool);
875
876 procedure Allocate
877 (Pool : in out Root_Storage_Pool;
878 Storage_Address : out System.Address;
879 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count;
880 Alignment : System.Storage_Elements.Storage_Count)
881 is abstract;
882
883 procedure Deallocate
884 (Pool : in out Root_Storage_Pool;
885 Storage_Address : System.Address;
886 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count;
887 Alignment : System.Storage_Elements.Storage_Count)
888 is abstract;
889
890 function Storage_Size
891 (Pool : Root_Storage_Pool)
892 return System.Storage_Elements.Storage_Count
893 is abstract;
894
895 The legacy notation:
896
897 .. code-block:: Ada
898
899 type My_Pools is new Root_Storage_Pool with record [...]
900
901 My_Pool_Instance : Storage_Model_Pool.Storage_Model :=
902 My_Pools'(others => <>);
903
904 type Acc is access Integer_Array with Storage_Pool => My_Pool;
905
906 can still be accepted as a shortcut for the new syntax.
907
908 Attribute Super
909 ---------------
910 .. index:: Super
911
912 The ``Super`` attribute can be applied to objects of tagged types in order
913 to obtain a view conversion to the most immediate specific parent type.
914
915 It cannot be applied to objects of types without any ancestors.
916
917 .. code-block:: ada
918
919 type T1 is tagged null record;
920 procedure P (V : T1);
921
922 type T2 is new T1 with null record;
923
924 type T3 is new T2 with null record;
925 procedure P (V : T3);
926
927 procedure Call (
928 V1 : T1'Class;
929 V2 : T2'Class;
930 V3 : T3'Class) is
931 begin
932 V1'Super.P; -- Illegal call as T1 doesn't have any ancestors
933 V2'Super.P; -- Equivalent to "T1 (V).P;", a non-dispatching call
934 -- to T1's primitive procedure P.
935 V3'Super.P; -- Equivalent to "T2 (V).P;"; Since T2 doesn't
936 -- override P, a non-dispatching call to T1.P is
937 -- executed.
938 end;
939
940 Simpler Accessibility Model
941 ---------------------------
942
943 The goal of this feature is to simplify the accessibility rules by removing
944 dynamic accessibility checks that are often difficult to understand and debug.
945 The new rules eliminate the need for runtime accessibility checks by imposing
946 more conservative legality rules when enabled via a new restriction (see RM 13.12),
947 No_Dynamic_Accessibility_Checks, which prevents dangling reference problems
948 at compile time.
949
950 This restriction has no effect on the user-visible behavior of a program when executed;
951 the only effect of this restriction is to enable additional compile-time checks
952 (described below) which ensure statically that Ada's dynamic accessibility checks
953 will not fail.
954
955 The feature can be activated with ``pragma Restrictions (No_Dynamic_Accessibility_Checks);``.
956 As a result, additional compile-time checks are performed; these checks pertain to
957 stand-alone objects, subprogram parameters, and function results as described below.
958
959 All of the refined rules are compatible with the [use of anonymous access types in SPARK]
960 (http://docs.adacore.com/spark2014-docs/html/lrm/declarations-and-types.html#access-types).
961
962
963 Stand-alone objects
964 ^^^^^^^^^^^^^^^^^^^^
965
966 .. code-block:: ada
967
968 Var : access T := ...
969 Var_To_Cst : access constant T := ...
970 Cst : constant access T := ...
971 Cst_To_Cst : constant access constant T := ...
972
973 In this section, we will refer to a stand-alone object of an anonymous access
974 type as an SO.
975
976 When the restriction is in effect, the "statically deeper" relationship
977 (see RM 3.10.2(4)) does apply to the type of a SO (contrary to RM 3.10.2(19.2))
978 and, for the purposes of compile-time checks, the accessibility level of the
979 type of a SO is the accessibility level of that SO.
980 This supports many common use-cases without the employment of ``Unchecked_Access``
981 while still removing the need for dynamic checks.
982
983 This statically disallows cases that would otherwise require a dynamic accessibility
984 check, such as
985
986 .. code-block:: ada
987
988 type Ref is access all Integer;
989 Ptr : Ref;
990 Good : aliased Integer;
991
992 procedure Proc is
993 Bad : aliased Integer;
994 Stand_Alone : access Integer;
995 begin
996 if <some condition> then
997 Stand_Alone := Good'Access;
998 else
999 Stand_Alone := Bad'Access;
1000 end if;
1001 Ptr := Ref (Stand_Alone);
1002 end Proc;
1003
1004 If a No_Dynamic_Accessibility_Checks restriction is in effect, then the otherwise-legal
1005 type conversion (the right-hand side of the assignment to Ptr) becomes a violation
1006 of the RM 4.6 rule "The accessibility level of the operand type shall not be
1007 statically deeper than that of the target type ...".
1008
1009 Subprogram parameters
1010 ^^^^^^^^^^^^^^^^^^^^^^
1011
1012 .. code-block:: ada
1013
1014 procedure P (V : access T; X : access constant T);
1015
1016
1017 In most cases (the exceptions are described below), a No_Dynamic_Accessibility_Checks
1018 restriction means that the "statically deeper" relationship does apply to the anonymous
1019 type of an access parameter specifying an access-to-object type (contrary to RM 3.10.2(19.1))
1020 and, for purposes of compile-time "statically deeper" checks, the accessibility level
1021 of the type of such a parameter is the accessibility level of the parameter.
1022
1023 This change (at least as described so far) doesn't affect the caller's side, but on the
1024 callee's side it means that object designated by a non-null parameter of an anonymous
1025 access type is treated as having the same accessibility level as a local object declared
1026 immediately within the called subprogram.
1027
1028 With the restriction in effect, the otherwise-legal type conversion in the following example
1029 becomes illegal:
1030
1031 .. code-block:: ada
1032
1033 type Ref is access all Integer;
1034 Ptr : Ref;
1035
1036 procedure Proc (Param : access Integer) is
1037 begin
1038 Ptr := Ref (Param);
1039 end Proc;
1040
1041 The aforementioned exceptions have to do with return statements from functions that either
1042 return the given parameter (in the case of a function whose result type is an anonymous
1043 access type) or return the given parameter value as an access discriminant of the function
1044 result (or of some discriminated part thereof). More specifically, the "statically deeper"
1045 changes described above do not apply for purposes of checking the "shall not be statically
1046 deeper" rule for access discriminant parts of function results (RM 6.5(5.9)) or in determining
1047 the legality of an (implicit) type conversion from the anonymous access type of a parameter
1048 of a function to an anonymous access result type of that function. In order to prevent these
1049 rule relaxations from introducing the possibility of dynamic accessibility check failures,
1050 compensating compile-time checks are performed at the call site to prevent cases where
1051 including the value of an access parameter as part of a function result could make such
1052 check failures possible (specifically, the discriminant checks of RM 6.5(21) or, in the
1053 case of an anonymous access result type, the RM 4.6(48) check performed when converting
1054 to that result type). These compile-time checks are described in the next section.
1055
1056 From the callee's perspective, the level of anonymous access formal parameters would be
1057 between the level of the subprogram and the level of the subprogram's locals. This has the effect
1058 of formal parameters being treated as local to the callee except in:
1059
1060 * Use as a function result
1061 * Use as a value for an access discriminant in result object
1062 * Use as an assignments between formal parameters
1063
1064 Note that with these more restricted rules we lose track of accessibility levels when assigned to
1065 local objects thus making (in the example below) the assignment to Node2.Link from Temp below
1066 compile-time illegal.
1067
1068 .. code-block:: ada
1069
1070 type Node is record
1071 Data : Integer;
1072 Link : access Node;
1073 end record;
1074
1075 procedure Swap_Links (Node1, Node2 : in out Node) is
1076 Temp : constant access Node := Node1.Link; -- We lose the "association" to Node1
1077 begin
1078 Node1.Link := Node2.Link; -- Allowed
1079 Node2.Link := Temp; -- Not allowed
1080 end;
1081
1082 function Identity (N : access Node) return access Node is
1083 Local : constant access Node := N;
1084 begin
1085 if True then
1086 return N; -- Allowed
1087 else
1088 return Local; -- Not allowed
1089 end if;
1090 end;
1091
1092 Function results
1093 ^^^^^^^^^^^^^^^^
1094
1095 .. code-block:: ada
1096
1097 function Get (X : Rec) return access T;
1098
1099 If the result subtype of a function is either an anonymous access (sub)type, a
1100 class-wide (sub)type, an unconstrained subtype with an access discriminant, or
1101 a type with an unconstrained subcomponent subtype that has at least one access
1102 discriminant (this last case is only possible if the access discriminant has a
1103 default value), then we say that the function result type "might require an
1104 anonymous-access-part accessibility check". If a function has an access parameter,
1105 or a parameter whose subtype "might require an anonymous-access-part accessibility
1106 check", then we say that the each such parameter "might be used to pass in an
1107 anonymous-access value". If the first of these conditions holds for the result
1108 subtype of a function and the second condition holds for at least one parameter
1109 that function, then it is possible that a call to that function could return a
1110 result that contains anonymous-access values that were passed in via the parameter.
1111
1112 Given a function call where the result type "might require an anonymous-access-part
1113 accessibility check" and a formal parameter of that function that "might be used to
1114 pass in an anonymous-access value", either the type of that formal parameter is an
1115 anonymous access type or it is not. If it is, and if a No_Dynamic_Access_Checks
1116 restriction is in effect, then the accessibility level of the type of the actual
1117 parameter shall be statically known to not be deeper than that of the master of
1118 the call. If it isn't, then the accessibility level of the actual parameter shall
1119 be statically known to not be deeper than that of the master of the call.
1120
1121 Function result example:
1122
1123 .. code-block:: ada
1124
1125 declare
1126 type T is record
1127 Comp : aliased Integer;
1128 end record;
1129
1130 function Identity (Param : access Integer) return access Integer is
1131 begin
1132 return Param; -- Legal
1133 end;
1134
1135 function Identity_2 (Param : aliased Integer) return access Integer is
1136 begin
1137 return Param'Access; -- Legal
1138 end;
1139
1140 X : access Integer;
1141 begin
1142 X := Identity (X); -- Legal
1143 declare
1144 Y : access Integer;
1145 Z : aliased Integer;
1146 begin
1147 X := Identity (Y); -- Illegal since Y is too deep
1148 X := Identity_2 (Z); -- Illegal since Z is too deep
1149 end;
1150 end;
1151
1152 In order to avoid having to expand the definition of "might be used to pass in an
1153 anonymous-access value" to include any parameter of a tagged type, the
1154 No_Dynamic_Access_Checks restriction also imposes a requirement that a type extension
1155 cannot include the explicit definition of an access discriminant.
1156
1157 Here is an example of one such case of an upward conversion which would lead to a memory leak:
1158
1159 .. code-block:: ada
1160
1161 declare
1162 type T is tagged null record;
1163 type T2 (Disc : access Integer) is new T with null record; -- Must be illegal
1164
1165 function Identity (Param : aliased T'Class) return access Integer is
1166 begin
1167 return T2 (T'Class (Param)).Disc; -- Here P gets effectively returned and set to X
1168 end;
1169
1170 X : access Integer;
1171 begin
1172 declare
1173 P : aliased Integer;
1174 Y : T2 (P'Access);
1175 begin
1176 X := Identity (T'Class (Y)); -- Pass local variable P (via Y's discriminant),
1177 -- leading to a memory leak.
1178 end;
1179 end;
1180 ```
1181
1182 Thus we need to make the following illegal to avoid such situations:
1183
1184 ```ada
1185 package Pkg1 is
1186 type T1 is tagged null record;
1187 function Func (X1 : T1) return access Integer is (null);
1188 end;
1189
1190 package Pkg2 is
1191 type T2 (Ptr1, Ptr2 : access Integer) is new Pkg1.T1 with null record; -- Illegal
1192 ...
1193 end;
1194
1195 In order to prevent upward conversions of anonymous function results (like below), we
1196 also would need to assure that the level of such a result (from the callee's perspective)
1197 is statically deeper:
1198
1199 .. code-block:: ada
1200
1201 declare
1202 type Ref is access all Integer;
1203 Ptr : Ref;
1204 function Foo (Param : access Integer) return access Integer is
1205 begin
1206 return Result : access Integer := Param; do
1207 Ptr := Ref (Result); -- Not allowed
1208 end return;
1209 end;
1210 begin
1211 declare
1212 Local : aliased Integer;
1213 begin
1214 Foo (Local'Access).all := 123;
1215 end;
1216 end;
1217
1218 Case pattern matching
1219 ---------------------
1220
1221 The selector for a case statement (but not for a case expression) may
1222 be of a composite type, subject to some restrictions (described below).
1223 Aggregate syntax is used for choices of such a case statement; however,
1224 in cases where a "normal" aggregate would require a discrete value, a
1225 discrete subtype may be used instead; box notation can also be used to
1226 match all values.
1227
1228 Consider this example:
1229
1230 .. code-block:: ada
1231
1232 type Rec is record
1233 F1, F2 : Integer;
1234 end record;
1235
1236 procedure Caser_1 (X : Rec) is
1237 begin
1238 case X is
1239 when (F1 => Positive, F2 => Positive) =>
1240 Do_This;
1241 when (F1 => Natural, F2 => <>) | (F1 => <>, F2 => Natural) =>
1242 Do_That;
1243 when others =>
1244 Do_The_Other_Thing;
1245 end case;
1246 end Caser_1;
1247
1248 If ``Caser_1`` is called and both components of X are positive, then
1249 ``Do_This`` will be called; otherwise, if either component is nonnegative
1250 then ``Do_That`` will be called; otherwise, ``Do_The_Other_Thing`` will be
1251 called.
1252
1253 In addition, pattern bindings are supported. This is a mechanism
1254 for binding a name to a component of a matching value for use within
1255 an alternative of a case statement. For a component association
1256 that occurs within a case choice, the expression may be followed by
1257 ``is <identifier>``. In the special case of a "box" component association,
1258 the identifier may instead be provided within the box. Either of these
1259 indicates that the given identifier denotes (a constant view of) the matching
1260 subcomponent of the case selector.
1261
1262 .. attention:: Binding is not yet supported for arrays or subcomponents
1263 thereof.
1264
1265 Consider this example (which uses type ``Rec`` from the previous example):
1266
1267 .. code-block:: ada
1268
1269 procedure Caser_2 (X : Rec) is
1270 begin
1271 case X is
1272 when (F1 => Positive is Abc, F2 => Positive) =>
1273 Do_This (Abc)
1274 when (F1 => Natural is N1, F2 => <N2>) |
1275 (F1 => <N2>, F2 => Natural is N1) =>
1276 Do_That (Param_1 => N1, Param_2 => N2);
1277 when others =>
1278 Do_The_Other_Thing;
1279 end case;
1280 end Caser_2;
1281
1282 This example is the same as the previous one with respect to determining
1283 whether ``Do_This``, ``Do_That``, or ``Do_The_Other_Thing`` will be called. But
1284 for this version, ``Do_This`` takes a parameter and ``Do_That`` takes two
1285 parameters. If ``Do_This`` is called, the actual parameter in the call will be
1286 ``X.F1``.
1287
1288 If ``Do_That`` is called, the situation is more complex because there are two
1289 choices for that alternative. If ``Do_That`` is called because the first choice
1290 matched (i.e., because ``X.F1`` is nonnegative and either ``X.F1`` or ``X.F2``
1291 is zero or negative), then the actual parameters of the call will be (in order)
1292 ``X.F1`` and ``X.F2``. If ``Do_That`` is called because the second choice
1293 matched (and the first one did not), then the actual parameters will be
1294 reversed.
1295
1296 Within the choice list for single alternative, each choice must define the same
1297 set of bindings and the component subtypes for for a given identifier must all
1298 statically match. Currently, the case of a binding for a nondiscrete component
1299 is not implemented.
1300
1301 If the set of values that match the choice(s) of an earlier alternative
1302 overlaps the corresponding set of a later alternative, then the first set shall
1303 be a proper subset of the second (and the later alternative will not be
1304 executed if the earlier alternative "matches"). All possible values of the
1305 composite type shall be covered. The composite type of the selector shall be an
1306 array or record type that is neither limited nor class-wide. Currently, a "when
1307 others =>" case choice is required; it is intended that this requirement will
1308 be relaxed at some point.
1309
1310 If a subcomponent's subtype does not meet certain restrictions, then the only
1311 value that can be specified for that subcomponent in a case choice expression
1312 is a "box" component association (which matches all possible values for the
1313 subcomponent). This restriction applies if:
1314
1315 - the component subtype is not a record, array, or discrete type; or
1316
1317 - the component subtype is subject to a non-static constraint or has a
1318 predicate; or:
1319
1320 - the component type is an enumeration type that is subject to an enumeration
1321 representation clause; or
1322
1323 - the component type is a multidimensional array type or an array type with a
1324 nonstatic index subtype.
1325
1326 Support for casing on arrays (and on records that contain arrays) is
1327 currently subject to some restrictions. Non-positional
1328 array aggregates are not supported as (or within) case choices. Likewise
1329 for array type and subtype names. The current implementation exceeds
1330 compile-time capacity limits in some annoyingly common scenarios; the
1331 message generated in such cases is usually "Capacity exceeded in compiling
1332 case statement with composite selector type".
1333
1334 Mutably Tagged Types with Size'Class Aspect
1335 -------------------------------------------
1336
1337 The ``Size'Class`` aspect can be applied to a tagged type to specify a size
1338 constraint for the type and its descendants. When this aspect is specified
1339 on a tagged type, the class-wide type of that type is considered to be a
1340 "mutably tagged" type - meaning that objects of the class-wide type can have
1341 their tag changed by assignment from objects with a different tag.
1342
1343 Example:
1344
1345 .. code-block:: ada
1346
1347 type Base is tagged null record
1348 with Size'Class => 16 * 8; -- Size in bits (128 bits, or 16 bytes)
1349
1350 type Derived_Type is new Base with record
1351 Data_Field : Integer;
1352 end record; -- ERROR if Derived_Type exceeds 16 bytes
1353
1354 Class-wide types with a specified ``Size'Class`` can be used as the type of
1355 array components, record components, and stand-alone objects.
1356
1357 .. code-block:: ada
1358
1359 Inst : Base'Class;
1360 type Array_of_Base is array (Positive range <>) of Base'Class;
1361
1362 If the ``Size'Class`` aspect is specified for a type ``T``, then every
1363 specific descendant of ``T`` [redundant: (including ``T``)]
1364
1365 - shall have a Size that does not exceed the specified value; and
1366
1367 - shall be undiscriminated; and
1368
1369 - shall have no composite subcomponent whose subtype is subject to a
1370 dynamic constraint; and
1371
1372 - shall have no interface progenitors; and
1373
1374 - shall not have a tagged partial view other than a private extension; and
1375
1376 - shall not have a statically deeper accessibility level than that of ``T``.
1377
1378 In addition to the places where Legality Rules normally apply (see 12.3),
1379 these legality rules apply also in the private part and in the body of an
1380 instance of a generic unit.
1381
1382 For any subtype ``S`` that is a subtype of a descendant of ``T``, ``S'Class'Size`` is
1383 defined to yield the specified value [redundant:, although ``S'Class'Size`` is
1384 not a static expression].
1385
1386 A class-wide descendant of a type with a specified ``Size'Class`` aspect is
1387 defined to be a "mutably tagged" type. Any subtype of a mutably tagged type is,
1388 by definition, a definite subtype (RM 3.3 notwithstanding). Default
1389 initialization of an object of such a definite subtype proceeds as for the
1390 corresponding specific type, except that ``Program_Error`` is raised if the
1391 specific type is abstract. [In particular, the initial tag of the object is
1392 that of the corresponding specific type.]
1393
1394 An object of a tagged type is defined to be "tag-constrained" if it is
1395
1396 - an object whose type is not mutably tagged; or
1397
1398 - a constant object; or
1399
1400 - a view conversion of a tag-constrained object; or
1401
1402 - a formal ``in out`` or ``out`` parameter whose corresponding
1403 actual parameter is tag-constrained.
1404
1405 In the case of an assignment to a tagged variable that
1406 is not tag-constrained, no check is performed that the tag of the value of
1407 the expression is the same as that of the target (RM 5.2 notwithstanding).
1408 Instead, the tag of the target object becomes that of the source object of
1409 the assignment.
1410 An assignment to a composite object similarly copies the tags of any
1411 subcomponents of the source object that have a mutably-tagged type.
1412
1413 The ``Constrained`` attribute is defined for any name denoting an object of a
1414 mutably tagged type (RM 3.7.2 notwithstanding). In this case, the Constrained
1415 attribute yields the value True if the object is tag-constrained and False
1416 otherwise.
1417
1418 Renaming is not allowed (see 8.5.1) for a type conversion having an operand of
1419 a mutably tagged type ``MT`` and a target type ``TT`` such that ``TT'Class``
1420 does not cover ``MT``, nor for any part of such an object, nor for any slice
1421 of such an object. This rule also applies in any context where a name is
1422 required to be one for which "renaming is allowed" (for example, see RM 12.4).
1423
1424 A name denoting a view of a variable of a mutably tagged type shall not
1425 occur as an operative constituent of the prefix of a name denoting a
1426 prefixed view of a callable entity, except as the callee name in a call to
1427 the callable entity.
1428
1429 For a type conversion between two general access types, either both or neither
1430 of the designated types shall be mutably tagged. For an ``Access`` (or
1431 ``Unchecked_Access``) attribute reference, the designated type of the type of the
1432 attribute reference and the type of the prefix of the attribute shall either
1433 both or neither be mutably tagged.
1434
1435 The execution of a construct is erroneous if the construct has a constituent
1436 that is a name denoting a subcomponent of a tagged object and the object's
1437 tag is changed by this execution between evaluating the name and the last use
1438 (within this execution) of the subcomponent denoted by the name.
1439
1440 If the type of a formal parameter is a specific tagged type then the execution
1441 of the call is erroneous if the tag of the actual is changed while the formal
1442 parameter exists (that is, before leaving the corresponding callable
1443 construct).
1444
1445 Generalized Finalization
1446 ------------------------
1447
1448 The ``Finalizable`` aspect can be applied to any record type, tagged or not,
1449 to specify that it provides the same level of control on the operations of
1450 initialization, finalization, and assignment of objects as the controlled
1451 types (see RM 7.6(2) for a high-level overview). The only restriction is
1452 that the record type must be a root type, in other words not a derived type.
1453
1454 The aspect additionally makes it possible to specify relaxed semantics for
1455 the finalization operations by means of the ``Relaxed_Finalization`` setting.
1456 Here is the archetypal example:
1457
1458 .. code-block:: ada
1459
1460 type T is record
1461 ...
1462 end record
1463 with Finalizable => (Initialize => Initialize,
1464 Adjust => Adjust,
1465 Finalize => Finalize,
1466 Relaxed_Finalization => True);
1467
1468 procedure Adjust (Obj : in out T);
1469 procedure Finalize (Obj : in out T);
1470 procedure Initialize (Obj : in out T);
1471
1472 The three procedures have the same profile, with a single ``in out`` parameter,
1473 and also have the same dynamic semantics as for controlled types:
1474
1475 - ``Initialize`` is called when an object of type ``T`` is declared without
1476 initialization expression.
1477
1478 - ``Adjust`` is called after an object of type ``T`` is assigned a new value.
1479
1480 - ``Finalize`` is called when an object of type ``T`` goes out of scope (for
1481 stack-allocated objects) or is deallocated (for heap-allocated objects).
1482 It is also called when the value is replaced by an assignment.
1483
1484 However, when ``Relaxed_Finalization`` is either ``True`` or not explicitly
1485 specified, the following differences are implemented relative to the semantics
1486 of controlled types:
1487
1488 * The compiler has permission to perform no automatic finalization of
1489 heap-allocated objects: ``Finalize`` is only called when such an object
1490 is explicitly deallocated, or when the designated object is assigned a new
1491 value. As a consequence, no runtime support is needed for performing
1492 implicit deallocation. In particular, no per-object header data is needed
1493 for heap-allocated objects.
1494
1495 Heap-allocated objects allocated through a nested access type will therefore
1496 **not** be deallocated either. The result is simply that memory will be leaked
1497 in this case.
1498
1499 * The ``Adjust`` and ``Finalize`` procedures are automatically considered as
1500 having the :ref:`No_Raise_Aspect` specified for them. In particular, the
1501 compiler has permission to enforce none of the guarantees specified by the
1502 RM 7.6.1 (14/1) and subsequent subclauses.
1503
1504 Simple example of ref-counted type:
1505
1506 .. code-block:: ada
1507
1508 type T is record
1509 Value : Integer;
1510 Ref_Count : Natural := 0;
1511 end record;
1512
1513 procedure Inc_Ref (X : in out T);
1514 procedure Dec_Ref (X : in out T);
1515
1516 type T_Access is access all T;
1517
1518 type T_Ref is record
1519 Value : T_Access;
1520 end record
1521 with Finalizable => (Adjust => Adjust,
1522 Finalize => Finalize);
1523
1524 procedure Adjust (Ref : in out T_Ref) is
1525 begin
1526 Inc_Ref (Ref.Value);
1527 end Adjust;
1528
1529 procedure Finalize (Ref : in out T_Ref) is
1530 begin
1531 Def_Ref (Ref.Value);
1532 end Finalize;
1533
1534 Simple file handle that ensures resources are properly released:
1535
1536 .. code-block:: ada
1537
1538 package P is
1539 type File (<>) is limited private;
1540
1541 function Open (Path : String) return File;
1542
1543 procedure Close (F : in out File);
1544
1545 private
1546 type File is limited record
1547 Handle : ...;
1548 end record
1549 with Finalizable (Finalize => Close);
1550 end P;
1551
1552 Finalizable tagged types
1553 ^^^^^^^^^^^^^^^^^^^^^^^^
1554
1555 The aspect is inherited by derived types and the primitives may be overridden
1556 by the derivation. The compiler-generated calls to these operations are then
1557 dispatching whenever it makes sense, i.e. when the object in question is of a
1558 class-wide type and the class includes at least one finalizable tagged type.
1559
1560 Composite types
1561 ^^^^^^^^^^^^^^^
1562
1563 When a finalizable type is used as a component of a composite type, the latter
1564 becomes finalizable as well. The three primitives are derived automatically
1565 in order to call the primitives of their components. The dynamic semantics is
1566 the same as for controlled components of composite types.
1567
1568 Interoperability with controlled types
1569 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1570
1571 Finalizable types are fully interoperable with controlled types, in particular
1572 it is possible for a finalizable type to have a controlled component and vice
1573 versa, but the stricter dynamic semantics, in other words that of controlled
1574 types, is applied in this case.
1575
1576 .. _No_Raise_Aspect:
1577
1578 No_Raise aspect
1579 ----------------
1580
1581 The ``No_Raise`` aspect can be applied to a subprogram to declare that this
1582 subprogram is not expected to raise an exception. Should an exception still
1583 be raised during the execution of the subprogram, it is caught at the end of
1584 this execution and ``Program_Error`` is propagated to the caller.
1585
1586 Inference of Dependent Types in Generic Instantiations
1587 ------------------------------------------------------
1588
1589 If a generic formal type T2 depends on another formal type T1,
1590 the actual for T1 can be inferred from the actual for T2.
1591 That is, you can give the actual for T2, and leave out the one
1592 for T1.
1593
1594 For example, ``Ada.Unchecked_Deallocation`` has two generic formals:
1595
1596 .. code-block:: ada
1597
1598 generic
1599 type Object (<>) is limited private;
1600 type Name is access Object;
1601 procedure Ada.Unchecked_Deallocation (X : in out Name);
1602
1603 where ``Name`` depends on ``Object``. With this language extension,
1604 you can leave out the actual for ``Object``, as in:
1605
1606 .. code-block:: ada
1607
1608 type Integer_Access is access all Integer;
1609
1610 procedure Free is new Unchecked_Deallocation (Name => Integer_Access);
1611
1612 The compiler will infer that the actual type for ``Object`` is ``Integer``.
1613 Note that named notation is always required when using inference.
1614
1615 The following inferences are allowed:
1616
1617 - For a formal access type, the designated type can be inferred.
1618
1619 - For a formal array type, the index type(s) and the component
1620 type can be inferred.
1621
1622 - For a formal type with discriminants, the type(s) of the discriminants
1623 can be inferred.
1624
1625 Example for arrays:
1626
1627 .. code-block:: ada
1628
1629 generic
1630 type Element_Type is private;
1631 type Index_Type is (<>);
1632 type Array_Type is array (Index_Type range <>) of Element_Type;
1633 package Array_Operations is
1634 ...
1635 end Array_Operations;
1636
1637 ...
1638
1639 type Int_Array is array (Positive range <>) of Integer;
1640
1641 package Int_Array_Operations is new Array_Operations (Array_Type => Int_Array);
1642
1643 The index and component types of ``Array_Type`` are inferred from
1644 ``Int_Array``, so that the above instantiation is equivalent to
1645 the following standard-Ada instantiation:
1646
1647 .. code-block:: ada
1648
1649 package Int_Array_Operations is new Array_Operations
1650 (Element_Type => Integer,
1651 Index_Type => Positive,
1652 Array_Type => Int_Array);
1653
1654
1655 External_Initialization Aspect
1656 ------------------------------
1657
1658 The ``External_Initialization`` aspect provides a feature similar to Rust's ``include_bytes!``
1659 and to C23's ``#embed``. It has the effect of initializing an object with the contents of
1660 a file specified by a file path.
1661
1662 Only string objects and objects of type ``Ada.Streams.Stream_Element_Array`` can be subject
1663 to the ``External_Initialization`` aspect.
1664
1665 Example:
1666
1667 .. code-block:: ada
1668
1669 with Ada.Streams;
1670
1671 package P is
1672 S : constant String with External_Initialization => "foo.txt";
1673
1674 X : constant Ada.Streams.Stream_Element_Array with External_Initialization => "bar.bin";
1675 end P;
1676
1677 ``External_Initialization`` aspect accepts the following parameters:
1678
1679 - mandatory ``Path``: the path the compiler uses to access the binary resource.
1680
1681 If ``Path`` is a relative path, it is interpreted relatively to the directory of the file that contains the aspect specification.
1682
1683 .. attention:: The maximum size of loaded files is limited to 2\ :sup:`31` bytes.
1684
1685
1686 Finally construct
1687 -----------------
1688
1689 The ``finally`` keyword makes it possible to have a sequence of statements be executed when
1690 another sequence of statements is completed, whether normally or abnormally.
1691
1692 This feature is similar to the one with the same name in other languages such as Java.
1693
1694 Syntax
1695 ^^^^^^
1696
1697 .. code-block:: text
1698
1699 handled_sequence_of_statements ::=
1700 sequence_of_statements
1701 [exception
1702 exception_handler
1703 {exception_handler}]
1704 [finally
1705 sequence_of_statements]
1706
1707 Legality Rules
1708 ^^^^^^^^^^^^^^
1709
1710 Return statements in the ``sequence_of_statements`` attached to the finally that would cause control
1711 to be transferred outside the finally part are forbidden.
1712
1713 Goto & exit where the target is outside of the finally's ``sequence_of_statements`` are forbidden
1714
1715 Dynamic Semantics
1716 ^^^^^^^^^^^^^^^^^
1717
1718 Statements in the optional ``sequence_of_statements`` contained in the ``finally`` branch will be
1719 executed unconditionally, after the main ``sequence_of_statements`` is executed, and after any
1720 potential ``exception_handler`` is executed.
1721
1722 If an exception is raised in the finally part, it cannot be caught by the ``exception_handler``.
1723
1724 Abort/ATC (asynchronous transfer of control) cannot interrupt a finally block, nor prevent its
1725 execution, that is the finally block must be executed in full even if the containing task is
1726 aborted, or if the control is transferred out of the block.