13.11 Storage Management

[The Max_Size_In_Storage_Elements and Max_Alignment_For_Allocation attributes may be useful in writing user-defined pool types.]

Static Semantics

For every subtype S, the following attributes are defined:

S'Max_Size_In_Storage_Elements

Denotes the maximum value for Size_In_Storage_Elements that can be requested by the implementation via Allocate for an access type whose designated subtype is S. The value of this attribute is of type universal_integer.

3.a

ramification

If S is an unconstrained array subtype, or an unconstrained subtype with discriminants, S'Max_Size_In_Storage_Elements might be very large.

4/5

S'Max_Alignment_For_Allocation

Denotes the maximum value for Alignment that can be requested by the implementation via Allocate for an access type whose designated subtype is S. The value of this attribute is of type universal_integer.

5/5

For a type with access discriminants, if the implementation allocates space for a coextension in the same pool as that of the object having the access discriminant, then these attributes account for any calls on Allocate that can be performed to provide space for such coextensions.

5.a/3

implementation advice

The values of these attributes should reflect only the calls that might be made to the pool specified for an access type with designated type S. Thus, if the coextensions would normally be allocated from a different pool than the one used for the main object (that is, the of 13.11 for determining the pool of an anonymous access discriminant is not followed), then these attributes should not reflect any calls on Allocate used to allocate the coextensions.

5.b/3

ramification

Coextensions of coextensions of this type (and so on) are included in the values of these attributes if they are allocated from the same pool.

Wording Changes from Ada 95

5.c/2

note

Corrected the wording so that a fortune-telling compiler that can see the future execution of the program is not required.

Extensions to Ada 2005

5.d/3

note

The Max_Alignment_For_Allocation attribute is new.

13.11.2 Unchecked Storage Deallocation

[ Unchecked storage deallocation of an object designated by a value of an access type is achieved by a call to an instance of the generic procedure Unchecked_Deallocation.]

Static Semantics

The following language-defined generic library procedure exists:

generic
   type Object(<>) is limited private;
   type Name   is access  Object;
procedure Ada.Unchecked_Deallocation(X : in out Name)
   with Preelaborate, Nonblocking,
        Global => in out Name'Storage_Pool,
        Convention => Intrinsic; 

3.a/3

reason

The aspect Convention implies that the attribute Access is not allowed for instances of Unchecked_Deallocation.

Legality Rules

3.1/3

A call on an instance of Unchecked_Deallocation is illegal if the actual access type of the instance is a type for which the Storage_Size has been specified by a static expression with value zero or is defined by the language to be zero. In addition to the places where Legality Rules normally apply (see 12.3), this rule applies also in the private part of an instance of a generic unit.

3.b/3

discussion

This rule is the same as the rule for allocators. We could have left the last sentence out, as a call to Unchecked_Deallocation cannot occur in a specification as it is a procedure call, but we left it for consistency and to avoid future maintenance hazards.

Dynamic Semantics

Given an instance of Unchecked_Deallocation declared as follows:

procedure Free is
    new Ada.Unchecked_Deallocation(
        object_subtype_name, access_to_variable_subtype_name);

Procedure Free has the following effect:

After executing Free(X), the value of X is null.
b): Free(X), when X is already equal to null, has no effect.
c): Free(X), when X is not equal to null first performs finalization of the object designated by X (and any coextensions of the object — see 3.10.2), as described in 7.6.1. It then deallocates the storage occupied by the object designated by X (and any coextensions). If the storage pool is a user-defined object, then the storage is deallocated by calling Deallocate as described in 13.11. There is one exception: if the object being freed contains tasks, it is unspecified whether the object is deallocated.

9.a/3

ramification

Free calls only the specified Deallocate procedure to do deallocation.

10/4

After the finalization step of Free(X), the object designated by X, and any subcomponents (and coextensions) thereof, no longer exist; their storage can be reused for other purposes.

Bounded (Run-Time) Errors

It is a bounded error to free a discriminated, unterminated task object. The possible consequences are:

11.a

reason

This is an error because the task might refer to its discriminants, and the discriminants might be deallocated by freeing the task object.

No exception is raised.

Program_Error or Tasking_Error is raised at the point of the deallocation.

Program_Error or Tasking_Error is raised in the task the next time it references any of the discriminants.

14.a

implementation note

This last case presumes an implementation where the task references its discriminants indirectly, and the pointer is nulled out when the task object is deallocated.

In the first two cases, the storage for the discriminants (and for any enclosing object if it is designated by an access discriminant of the task) is not reclaimed prior to task termination.

15.a

ramification

The storage might never be reclaimed.

15.1/4

An access value that designates a nonexistent object is called a dangling reference.

15.b/4

discussion

These can result from use of Unchecked_Deallocation, Unchecked_Deallocate_Subpool, and attribute Unchecked_Access. Bad results from Unchecked_Conversion and from stream-oriented attributes are abnormal by 13.9.1, which is stronger and thus takes precedence.

15.2/4

[If a dangling reference is dereferenced (implicitly or explicitly), execution is erroneous (see below).] If there is no explicit or implicit dereference, then it is a bounded error to evaluate an expression whose result is a dangling reference. If the error is detected, either Constraint_Error or Program_Error is raised. Otherwise, execution proceeds normally, but with the possibility that the access value designates some other existing object.

15.c/4

reason

If a dangling reference is compared with another access value, a result of either True or False is allowed. We need to allow this so that simple implementations of access values (for instance, as a bare address) can work if the memory in question is reused. (The formal definition of access equality is that it returns True if both access values designate the same object; that can never be True if one of the values is a dangling reference, and the other is not, but both values could refer to the same memory.) Membership tests that do not involve an implicit dereference generally do not depend on the access value at all.

15.d/4

note

We allow Constraint_Error to be raised here so that dangling reference and null pointer checks can be combined into a single check. If different exceptions are required, then the checks have to be made separately - but there's little semantic difference (neither designate a usable object).

15.e/4

ramification

If a dangling reference is assigned into an object, including being passed to a formal parameter, that object also contains a dangling reference afterwards.

15.f/4

discussion

For equality and membership operations on composite types, this applies to any parts that are access types, as these operations are created based on the operations of the components (which triggers the bounded error). For other operations on composite types, the bounded error is not triggered. For instance, an assignment of a composite object with a subcomponent that is a dangling reference has to work normally; no exception can be raised, but the target object will have a subcomponent that is a dangling references, and a (direct) use of that subcomponent is again a bounded error. This is similar to the way that assignments of invalid subcomponents are handled (see 13.9.1).

Erroneous Execution

16/3

Evaluating a name that denotes a nonexistent object, or a protected subprogram or subprogram renaming whose associated object (if any) is nonexistent, is erroneous. The execution of a call to an instance of Unchecked_Deallocation is erroneous if the object was created other than by an allocator for an access type whose pool is Name'Storage_Pool.

16.a/3

reason

The part about a protected subprogram is intended to cover the case of an access-to-protected-subprogram where the associated object has been deallocated. The part about a subprogram renaming is intended to cover the case of a renaming of a prefixed view where the prefix object has been deallocated, or the case of a renaming of an entry or protected subprogram where the associated task or protected object has been deallocated.

16.b/3

ramification

This text does not cover the case of a name that contains a null access value, as null does not denote an object (rather than denoting a nonexistent object).

Implementation Advice

For a standard storage pool, Free should actually reclaim the storage.

17.a.1/2

implementation advice

For a standard storage pool, an instance of Unchecked_Deallocation should actually reclaim the storage.

17.a/2

ramification

This is not a testable property, since we do not know how much storage is used by a given pool element, nor whether fragmentation can occur.

17.1/3

A call on an instance of Unchecked_Deallocation with a nonnull access value should raise Program_Error if the actual access type of the instance is a type for which the Storage_Size has been specified to be zero or is defined by the language to be zero.

17.a.1/3

implementation advice

17.b

discussion

If the call is not illegal (as in a generic body), we recommend that it raise Program_Error. Since the execution of this call is erroneous (any allocator from the pool will have raised Storage_Error, so the nonnull access value must have been allocated from a different pool or be a stack-allocated object), we can't require any behavior — anything at all would be a legitimate implementation.

note

NOTE 1 The rules here that refer to Free apply to any instance of Unchecked_Deallocation.

note

NOTE 2 Unchecked_Deallocation cannot be instantiated for an access-to-constant type. This is implied by the rules of 12.5.4.

Wording Changes from Ada 95

19.a/2

note

The rules for coextensions are clarified (mainly by adding that term). In theory, this reflects no change from Ada 95 (coextensions existed in Ada 95, they just didn't have a name).

Wording Changes from Ada 2005

19.b/3

correction

Added a rule that using an access-to-protected-subprogram is erroneous if the associated object no longer exists. It is hard to imagine an alternative meaning here, and this has no effect on correct programs.

19.c/3

correction

Moved the requirements on an implementation-generated call to Deallocate to 13.11, in order to put all of the rules associated with implementation-generated calls to Allocate and Deallocate together.

19.d/3

correction

Added wording so that calling an instance of Unchecked_Deallocation is treated similarly to allocators for access types where allocators would be banned.

Inconsistencies With Ada 2012

19.e/4

note

Corrigendum: Defined a "dangling reference", and specified that a dangling reference might designate some other existing object. This allows simple implementations of access values and reuse of object memory after deallocation. In prior versions of Ada, "=" between a dangling reference and an access to an existing object has to return False, even if the existing object and the object designated by the dangling reference are allocated in the same memory. A program that depended upon that could break with this revised rule. However, as a practical matter, almost all Ada implementations use simple implementations of access types that do not meet that requirement. So such a program would not work (consistently) on most Ada implementations; thus the change shouldn't break any existing programs - it just aligns the Standard with actual practice.

19.f/4

note

A side effect of this change is to allow an Ada implementation to detect dangling references in more places. This does not require any Ada implementation to change, and if the implementation does change, it just means that errors will be detected earlier.

Wording Changes from Ada 2012

19.g/4

note

Corrigendum: Clarified that deallocated objects cease to exist after finalization but before Deallocate is called. This is necessary to prevent erroneous execution from being triggered by the rules in 13.11 in the time between the end of finalization and the end of the call to the instance of Unchecked_Deallocation.

13.11.3 Default Storage Pools

1/4

[Pragma and aspect Default_Storage_Pool specify the storage pool that will be used in the absence of an explicit specification of a storage pool or storage size for an access type.]

Syntax

The form of a pragma Default_Storage_Pool is as follows:

3/3

pragma Default_Storage_Pool (storage_pool_indicator);

3.1/4

storage_pool_indicator ::= storage_pool_name | null | Standard

3.2/3

A pragma Default_Storage_Pool is allowed immediately within the visible part of a package_specification, immediately within a declarative_part, or as a configuration pragma.

Name Resolution Rules

3.3/3

The storage_pool_name is expected to be of type Root_Storage_Pool'Class.

Legality Rules

4/3

The storage_pool_name shall denote a variable.

4.1/4

The Standard storage_pool_indicator is an identifier specific to a pragma (see 2.8) and does not denote any declaration. If the storage_pool_indicator is Standard, then there shall not be a declaration with defining_identifier Standard that is immediately visible at the point of the pragma, other than package Standard itself.

4.a.1/4

reason

We considered having the Standard storage_pool_indicator resolve to package Standard rather than being an identifier specific to a pragma. That would eliminate the need for a special check. But it would be bizarre to have something that could resolve to either an object or a (single) package, and resolving to package Standard would imply that the standard pool is an object declared in that package. A storage pool object must be a variable (see 13.11), yet preelaborable packages depend on package Standard, which would require implementers to implement the standard storage pool with Preelaborable_Initialization, which is an unnecessary restriction.

4.a.2/4

note

No declaration of Standard can ever be use-visible, as the language-defined nonoverloadable definition of Standard will hide any use-visible declarations. Thus we need only concern ourselves with eliminating any possible confusion with regard to immediately visible declarations with the defining_identifier Standard.

4.2/4

If the pragma is used as a configuration pragma, the storage_pool_indicator shall be either null or Standard, and it defines the default pool to be the given storage_pool_indicator within all applicable compilation units (see 10.1.5), except within the immediate scope of another pragma Default_Storage_Pool. Otherwise, [the pragma occurs immediately within a sequence of declarations, and] it defines the default pool within the immediate scope of the pragma to be the given storage_pool_indicator, except within the immediate scope of a later pragma Default_Storage_Pool. [Thus, an inner pragma overrides an outer one.]

4.3/4

A pragma Default_Storage_Pool shall not be used as a configuration pragma that applies to a compilation unit that is within the immediate scope of another pragma Default_Storage_Pool.

4.a/3

reason

This is to prevent confusion in cases like this:

4.b/3

package Parent is
   pragma Default_Storage_Pool(...);
   ...
end Parent;
4.c/3pragma Default_Storage_Pool(...); -- Illegal!
package Parent.Child is
   ...
end Parent.Child;

4.d/3

note

where the Default_Storage_Pool on Parent.Child would not (if it were legal) override the one in Parent.

Static Semantics

5/4

The language-defined aspect Default_Storage_Pool may be specified for a generic instance; it defines the default pool for access types within an instance. .

5.1/4

The Default_Storage_Pool aspect may be specified as Standard, which is an identifier specific to an aspect (see 13.1.1) and defines the default pool to be Standard. In this case, there shall not be a declaration with defining_identifier Standard that is immediately visible at the point of the aspect specification, other than package Standard itself.

5.2/5

Otherwise, the expected type for the Default_Storage_Pool aspect is Root_Storage_Pool'Class and the aspect_definition shall be a name that denotes a variable. This aspect overrides any Default_Storage_Pool pragma that applies to the generic unit; if the aspect is not specified, the default pool of the instance is that defined for the generic unit.

5.a/3

note

Aspect Description for Default_Storage_Pool: Default storage pool for a generic instance.

5.3/4

The effect of specifying the aspect Default_Storage_Pool on an instance of a language-defined generic unit is implementation-defined.

5.a.1/4

implementation defined

The effect of specifying aspect Default_Storage_Pool on an instance of a language-defined generic unit.

6/3

For nonderived access types declared in places where the default pool is defined by the pragma or aspect, their Storage_Pool or Storage_Size attribute is determined as follows, unless Storage_Pool or Storage_Size is specified for the type:

6.1/3

If the default pool is null, the Storage_Size attribute is defined by the language to be zero. [Therefore, an allocator for such a type is illegal.]

6.2/4

If the default pool is neither null nor Standard, the Storage_Pool attribute is that pool.

6.3/4

Otherwise (including when the default pool is specified as Standard), the standard storage pool is used for the type as described in 13.11.

6.a/3

ramification

Default_Storage_Pool is the only way to specify the storage pool for an anonymous access type.

6.b/3

note

Note that coextensions should be allocated in the same pool (or on the stack) as the outer object (see 13.11); the Storage_Pool of the access discriminant (and hence the Default_Storage_Pool) is supposed to be ignored for coextensions. This matches the required finalization point for coextensions.

6.b.1/3

note

The default storage pool for an allocator that occurs within an instance of a generic is defined by the Default_Storage_Pool aspect of the instantiation (if specified), or by the Default_Storage_Pool pragma that applied to the generic; the Default_Storage_Pool pragma that applies to the instantiation is irrelevant.

6.b.2/3

note

It is possible to specify the Default_Storage_Pool aspect for an instantiation such that allocations will fail. For example, the generic unit might be expecting a pool that supports certain sizes and alignments, and the one on the instance might be more restrictive. It is the programmer's responsibility to get this right.

6.b.3/3

note

The semantics of the Default_Storage_Pool aspect are similar to passing a pool object as a generic formal, and putting pragma Default_Storage_Pool at the top of the generic's visible part, specifying that formal.

7/3

This paragraph was deleted.

Implementation Permissions

8/3

An object created by an allocator that is passed as the actual parameter to an access parameter may be allocated on the stack, and automatically reclaimed, regardless of the default pool.

8.a/3

discussion

This matches the required finalization point for such an allocated object.

9/5

note

NOTE 1 Default_Storage_Pool can be used with restrictions No_Coextensions and No_Access_Parameter_Allocators (see H.4) to ensure that all allocators use the default pool.

Wording Changes from Ada 83

9.a/3

note

This paragraph was deleted.

Incompatibilities With Ada 2005

9.b/3

note

Pragma Controlled has been dropped from Ada, as it has no effect in any known Ada implementations and it seems to promise capabilities not expected in Ada implementations. This is usually not an incompatibility, as the pragma merely becomes unrecognized (with a warning) and can be implemented as an implementation-defined pragma if desired. However, it is incompatible if it is (now) implemented as an implementation-defined pragma, someone used this pragma in a unit, and they also used restriction No_Implementation_Pragmas on that unit. In that case, the pragma would now violate the restriction; but use of this pragma (which does nothing) should be very rare, so this is not a significant issue.

Extensions to Ada 2005

9.c/4

note

The pragma Default_Storage_Pool and aspect Default_Storage_Pool are new.

Wording Changes from Ada 2005

9.d/3

note

The entire discussion of garbage collection (and especially that of controlled objects) is deleted. Ada 2012 provides subpools (see 13.11.4) for storage management of objects, including controlled objects, a mechanism which is much more predictable than garbage collection. Note that no version of Ada allows early finalization of controlled objects (other than via the use of Unchecked_Deallocation or Unchecked_Deallocate_Subpool), so that garbage collection of such objects would be ineffective in the standard mode anyway.

Extensions to Ada 2012

9.e/4

note

Corrigendum: The storage_pool_indicator Standard is new.

Wording Changes from Ada 2012

9.f/4

note

Corrigendum: We now explicitly say that the behavior of language-defined generic units when given the Default_Storage_Pool aspect is implementation-defined. Portable code cannot rely on such a package using a particular pool implementation.

13.11.4 Storage Subpools

This subclause defines a package to support the partitioning of a storage pool into subpools. A subpool may be specified as the default to be used for allocation from the associated storage pool, or a particular subpool may be specified as part of an allocator (see 4.8).

Static Semantics

The following language-defined library package exists:

package System.Storage_Pools.Subpools 
    with  Preelaborate, Global => in out synchronized is 
4/5
type Root_Storage_Pool_With_Subpools is
      abstract new Root_Storage_Pool with private
      with Preelaborable_Initialization;
5/5
type Root_Subpool is abstract tagged limited private
      with Preelaborable_Initialization;
6/3type Subpool_Handle is access all Root_Subpool'Class;
   for Subpool_Handle'Storage_Size use 0;
7/3function Create_Subpool (Pool : in out Root_Storage_Pool_With_Subpools)
      return not null Subpool_Handle is abstract;
8/3
-- The following operations are intended for pool implementers:
9/3function Pool_of_Subpool (Subpool : not null Subpool_Handle)
      return access Root_Storage_Pool_With_Subpools'Class;
10/5
procedure Set_Pool_of_Subpool (
      Subpool : in not null Subpool_Handle;
      To : in out Root_Storage_Pool_With_Subpools'Class)
         with Global => overriding in out Subpool;
11/5
procedure Allocate_From_Subpool (
      Pool : in out Root_Storage_Pool_With_Subpools;
      Storage_Address : out Address;
      Size_In_Storage_Elements : in Storage_Elements.Storage_Count;
      Alignment : in Storage_Elements.Storage_Count;
      Subpool : in not null Subpool_Handle) is abstract
         with Pre'Class => Pool_of_Subpool(Subpool) = Pool'Access,
              Global => overriding in out Subpool;
12/3procedure Deallocate_Subpool (
      Pool : in out Root_Storage_Pool_With_Subpools;
      Subpool : in out Subpool_Handle) is abstract
         with Pre'Class => Pool_of_Subpool(Subpool) = Pool'Access;
13/3
function Default_Subpool_for_Pool (
      Pool : in out Root_Storage_Pool_With_Subpools)
         return not null Subpool_Handle;
14/3overriding
   procedure Allocate (
      Pool : in out Root_Storage_Pool_With_Subpools;
      Storage_Address : out Address;
      Size_In_Storage_Elements : in Storage_Elements.Storage_Count;
      Alignment : in Storage_Elements.Storage_Count);
15/3overriding
   procedure Deallocate (
      Pool : in out Root_Storage_Pool_With_Subpools;
      Storage_Address : in Address;
      Size_In_Storage_Elements : in Storage_Elements.Storage_Count;
      Alignment : in Storage_Elements.Storage_Count) is null;
16/3
overriding
   function Storage_Size (Pool : Root_Storage_Pool_With_Subpools)
      return Storage_Elements.Storage_Count
          is (Storage_Elements.Storage_Count'Last);
17/3private
   ... -- not specified by the language
end System.Storage_Pools.Subpools;

18/3

A subpool is a separately reclaimable portion of a storage pool, identified by an object of type Subpool_Handle (a subpool handle). A subpool handle also identifies the enclosing storage pool, a storage pool that supports subpools, which is a storage pool whose type is descended from Root_Storage_Pool_With_Subpools. A subpool is created by calling Create_Subpool or a similar constructor; the constructor returns the subpool handle.

19/5

A subpool object is an object of a type descended from Root_Subpool. [Typically, subpool objects are managed by the containing storage pool; only the handles have to be exposed to clients of the storage pool. Subpool objects are designated by subpool handles, and are the run-time representation of a subpool.]

19.a/3

proof

We know that subpool handles designate subpool objects because the declaration of Subpool_Handle says so.

20/4

Each subpool belongs to a single storage pool [(which will always be a pool that supports subpools)]. An access to the pool that a subpool belongs to can be obtained by calling Pool_of_Subpool with the subpool handle. Set_Pool_of_Subpool causes the subpool of the subpool handle to belong to the given pool[; this is intended to be called from subpool constructors like Create_Subpool.] Set_Pool_of_Subpool propagates Program_Error if the subpool already belongs to a pool. If Set_Pool_of_Subpool has not yet been called for a subpool, Pool_of_Subpool returns null.

20.a/3

discussion

Pool_of_Subpool and Set_Pool_of_Subpool are provided by the Ada implementation and typically will not be overridden by the pool implementer.

21/3

When an allocator for a type whose storage pool supports subpools is evaluated, a call is made on Allocate_From_Subpool passing in a Subpool_Handle, in addition to the parameters as defined for calls on Allocate (see 13.11). The subpool designated by the subpool_handle_name is used, if specified in an allocator. Otherwise, Default_Subpool_for_Pool of the Pool is used to provide a subpool handle. All requirements on the Allocate procedure also apply to Allocate_from_Subpool.

21.a/3

discussion

Deallocate_Subpool is expected to do whatever is needed to deallocate all of the objects contained in the subpool; it is called from Unchecked_Deallocate_Subpool (see 13.11.5).

21.b/3

note

Typically, the pool implementer will not override Allocate. In the canonical definition of the language, it will never be called for a pool that supports subpools (there is an Implementation Permission below that allows it to be called in certain rare cases).

Legality Rules

22/3

If a storage pool that supports subpools is specified as the Storage_Pool for an access type, the access type is called a subpool access type. A subpool access type shall be a pool-specific access type.

23/3

The accessibility level of a subpool access type shall not be statically deeper than that of the storage pool object. If the specified storage pool object is a storage pool that supports subpools, then the name that denotes the object shall not denote part of a formal parameter, nor shall it denote part of a dereference of a value of a non-library-level general access type. In addition to the places where Legality Rules normally apply (see 12.3), these rules also apply in the private part of an instance of a generic unit.

Dynamic Semantics

24/3

When an access type with a specified storage pool is frozen (see 13.14), if the tag of the storage pool object identifies a storage pool that supports subpools, the following checks are made:

25/3

the name used to specify the storage pool object does not denote part of a formal parameter nor part of a dereference of a value of a non-library-level general access type; and

26/3

the accessibility level of the access type is not deeper than that of the storage pool object.

27/3

Program_Error is raised if either of these checks fail.

27.a/3

reason

This check (and its static counterpart) ensures that the type of the allocated objects exists at least as long as the storage pool object, so that the subpools are finalized (which finalizes any remaining allocated objects) before the type of the objects ceases to exist. The access type itself (and the associated collection) will cease to exist before the storage pool ceases to exist.

27.b/3

note

We also disallow the use of formal parameters and dereferences of non-library-level general access types when specifying a storage pool object if it supports subpools, because the "apparent" accessibility level is potentially deeper than that of the underlying object. Neither of these cases is very likely to occur in practice.

28/3

A call to Subpools.Allocate(P, Addr, Size, Align) does the following:

29/3

Allocate_From_Subpool
  (Root_Storage_Pool_With_Subpools'Class(P),
   Addr, Size, Align,
   Subpool => Default_Subpool_for_Pool
                (Root_Storage_Pool_With_Subpools'Class(P)));

30/3

An allocator that allocates in a subpool raises Program_Error if the allocated object has task parts.

30.a/3

reason

This is to ease implementation. We envision relaxing this restriction in a future version of Ada, once implementation experience has been gained. At this time, we are unable to come up with a set of rules for task termination that is both useful, and surely feasible to implement.

31/3

Unless overridden, Default_Subpool_for_Pool propagates Program_Error.

Erroneous Execution

31.1/4

If Allocate_From_Subpool does not meet one or more of the requirements on the Allocate procedure as given in the Erroneous Execution rules of 13.11, then the program execution is erroneous.

Implementation Permissions

32/3

When an allocator for a type whose storage pool is of type Root_Storage_Pool'Class is evaluated, but supports subpools, the implementation may call Allocate rather than Allocate_From_Subpool. [This will have the same effect, so long as Allocate has not been overridden.]

32.a/3

reason

This ensures either of two implementation models are possible for an allocator with no subpool_specification. Note that the "supports subpools" property is not known at compile time for a pool of the class-wide type.

32.b/3

The implementation can dispatch to Storage_Pools.Allocate. If the pool supports subpools, this will call Allocate_From_Subpool with the default subpool so long as Allocate has not been overridden.

32.c/3

The implementation can declare Allocate_From_Subpool as a primitive of Root_Storage_Pool in the private part of Storage_Pools. This means that the Allocate_From_Subpool for Root_Storage_Pool_With_Subpools overrides that private one. The implementation can thus call the private one, which will call Allocate for non-subpool-supporting pools. The effect of this implementation does not change if Allocate is overridden for a pool that supports subpools.

33/5

note

NOTE 1 A user-defined storage pool type that supports subpools can be implemented by extending the Root_Storage_Pool_With_Subpools type, and overriding the primitive subprograms Create_Subpool, Allocate_From_Subpool, and Deallocate_Subpool. Create_Subpool is expected to call Set_Pool_Of_Subpool before returning the subpool handle. To make use of such a pool, a user can declare an object of the type extension, use it to define the Storage_Pool attribute of one or more access types, and then call Create_Subpool to obtain subpool handles associated with the pool.

34/5

note

NOTE 2 A user-defined storage pool type that supports subpools can define additional subpool constructors similar to Create_Subpool (these typically will have additional parameters).

35/5

note

NOTE 3 The pool implementor can override Default_Subpool_For_Pool if they want the pool to support a default subpool for the pool. The implementor can override Deallocate if individual object reclamation is to be supported, and can override Storage_Size if there is some limit on the total size of the storage pool. The implementor can override Initialize and Finalize if there is any desire for nontrivial initialization and finalization for the pool as a whole. For example, Finalize can reclaim blocks of storage that are allocated over and above the space occupied by the pool object itself. The pool implementor can extend the Root_Subpool type as necessary to carry additional information with each subpool provided by Create_Subpool.

Extensions to Ada 2005

35.a/3

note

Subpools and the package System.Storage_Pools.Subpools are new.

Wording Changes from Ada 2012

35.b/4

note

Corrigendum: Clarified that an incorrect implementation of Allocate_From_Subpool causes execution to become erroneous. The wording already said that the requirements of Allocate apply to Allocate_From_Subpool, so we're just confirming the consequences of violating those requirements also apply.

35.c/4

note

Corrigendum: Clarified that Pool_of_Subpool returns null if Set_Pool_of_Subpool has not been called. As that can be inferred from the definition, and all known existing implementations return null in this case, we document this as a wording change rather than a possible inconsistency.

13.11.5 Subpool Reclamation

A subpool may be explicitly deallocated using Unchecked_Deallocate_Subpool.

Static Semantics

The following language-defined library procedure exists:

with System.Storage_Pools.Subpools;
procedure Ada.Unchecked_Deallocate_Subpool
   (Subpool : in out System.Storage_Pools.Subpools.Subpool_Handle)
   with Global => in out all;

3.a/5

discussion

The Global specification for this routine needs to account for the dispatching call to the user-defined Deallocate_Subpool routine. We can't use the Dispatching aspect (see H.7.1) as that requires a statically named object (we have a function call here), so we have to use in out all in order to allow the user-defined subprogram to do anything it needs to do.

4/3

If Subpool is null, a call on Unchecked_Deallocate_Subpool has no effect. Otherwise, the subpool is finalized, and Subpool is set to null.

5/5

Finalization of a subpool has the following effects in the given order:

6/5

This paragraph was deleted.a)

b): Any of the objects allocated from the subpool that still exist are finalized in an arbitrary order;
c): All of the objects allocated from the subpool cease to exist;
d): The following [dispatching] call is then made:

9/3

Deallocate_Subpool(Pool_of_Subpool(Subpool).all, Subpool);

9.1/5

The subpool ceases to belong to any pool.

10/3

Finalization of a Root_Storage_Pool_With_Subpools object finalizes all subpools that belong to that pool that have not yet been finalized.

10.a/3

discussion

There is no need to call Unchecked_Deallocation on an object allocated in a subpool. Such objects are deallocated all at once, when Unchecked_Deallocate_Subpool is called.

10.b/3

note

If Unchecked_Deallocation is called, the object is finalized, and then Deallocate is called on the Pool, which typically will do nothing. If it wants to free memory, it will need some way to get from the address of the object to the subpool.

10.c/3

note

There is no Deallocate_From_Subpool. There is no efficient way for the implementation to determine the subpool for an arbitrary object, and if the pool implementer can determine that, they can use that as part of the implementation of Deallocate.

10.d/3

note

If Unchecked_Deallocation is not called (the usual case), the object will be finalized when Unchecked_Deallocate_Subpool is called.

10.e/3

note

If that's never called, then the object will be finalized when the Pool_With_Subpools is finalized (by permission — it might happen when the collection of the access type is finalized).

Extensions to Ada 2005

10.f/3

note

Unchecked_Deallocate_Subpool is new.

Wording Changes from Ada 2012

10.g/4

note

Corrigendum: Added missing wording to state that the objects cease to exist after the completion of finalization. This is formally an inconsistency (it would be possible to depend on the fact that objects finalized by Unchecked_Deallocate_Subpool still exist), but that violates every sane expectation for a procedure called "Deallocate" something.

10.h/5

note

Clarified that the steps of deallocating a subpool occur in a specific order. This shouldn't change any implementation; no implementation is going to finalize deallocated objects or implement Unchecked_Deallocate_Subpool so it is certain to raise Constraint_Error.

13.11.6 Storage Subpool Example

Examples

The following example is a simple but complete implementation of the classic Mark/Release pool using subpools: