13.11 Storage Management
This Reference Manual output has not been verified, and may contain omissions or errors. Report any problems on the tracking issue
[ Each access-to-object type has an associated storage pool. The storage allocated by an allocator comes from the pool; instances of Unchecked_Deallocation return storage to the pool. Several access types can share the same pool.]
[A storage pool is a variable of a type in the class rooted at Root_Storage_Pool, which is an abstract limited controlled type. By default, the implementation chooses a standard storage pool for each access-to-object type. The user may define new pool types, and may override the choice of pool for an access-to-object type by specifying Storage_Pool for the type.]
By default, the implementation might choose to have a single global storage pool, which is used (by default) by all access types, which might mean that storage is reclaimed automatically only upon partition completion. Alternatively, it might choose to create a new pool at each accessibility level, which might mean that storage is reclaimed for an access type when leaving the appropriate scope. Other schemes are possible.
Term entry: storage pool object — object associated with one or more access types from which the storage for objects created by allocators of the access type(s) is obtained
Note: Some storage pools can be partitioned into subpools in order to support finer-grained storage management.
Legality Rules
3If Storage_Pool is specified for a given access type, Storage_Size shall not be specified for it.
The Storage_Pool determines the Storage_Size; hence it would not make sense to specify both. Note that this rule is simplified by the fact that the aspects in question cannot be specified for derived types, nor for nonfirst subtypes, so we don't have to worry about whether, say, Storage_Pool on a derived type overrides Storage_Size on the parent type. For the same reason, “specified” means the same thing as “directly specified” here.
Static Semantics
4The following language-defined library package exists:
with Ada.Finalization;
with System.Storage_Elements;
package System.Storage_Pools
with Pure, Nonblocking => False is
6/5
type Root_Storage_Pool is
abstract new Ada.Finalization.Limited_Controlled with private
with Preelaborable_Initialization;
7
procedure Allocate(
Pool : in out Root_Storage_Pool;
Storage_Address : out Address;
Size_In_Storage_Elements : in Storage_Elements.Storage_Count;
Alignment : in Storage_Elements.Storage_Count) is abstract;
8
procedure Deallocate(
Pool : in out Root_Storage_Pool;
Storage_Address : in Address;
Size_In_Storage_Elements : in Storage_Elements.Storage_Count;
Alignment : in Storage_Elements.Storage_Count) is abstract;
9
function Storage_Size(Pool : Root_Storage_Pool)
return Storage_Elements.Storage_Count is abstract;
10
private
... -- not specified by the language
end System.Storage_Pools;
The Alignment parameter is provided to Deallocate because some allocation strategies require it. If it is not needed, it can be ignored.
A storage pool type (or pool type) is a descendant of Root_Storage_Pool. The elements of a storage pool are the objects allocated in the pool by allocators.
In most cases, an element corresponds to a single memory block allocated by Allocate. However, in some cases the implementation may choose to associate more than one memory block with a given pool element.
{8652/0009} For every access-to-object subtype S, the following representation attributes are defined:
S'Storage_Pool
- Denotes the storage pool of the type of S. The type of this attribute is Root_Storage_Pool'Class.
S'Storage_Size- Yields the result of calling Storage_Size(S'Storage_Pool)[, which is intended to be a measure of the number of storage elements reserved for the pool.] The type of this attribute is universal_integer.
Storage_Size is not a measure of how much un-allocated space is left in the pool. That is, it includes both allocated and unallocated space. Implementations and users may provide a Storage_Available function for their pools, if so desired.
Storage_Size or Storage_Pool may be specified for a nonderived access-to-object type via an attribute_definition_clause; the name in a Storage_Pool clause shall denote a variable. If the nominal subtype of the name specified for Storage_Pool is nonblocking (see 9.5), then the primitive Allocate, Deallocate, and Storage_Size subprograms of that type shall be nonblocking. Additionally, if the pool is one that supports subpools (see 13.11.4), the primitive Default_Subpool_for_Pool, Allocate_From_Subpool, and Deallocate_Subpool subprograms shall be nonblocking.
Aspect Description for Storage_Pool: Pool of memory from which new will allocate for a given access type.
Aspect Description for Storage_Size (access): Sets memory size for allocations for an access type.
We need to be able to describe in contracts (especially for generic units) whether the operations of a storage pool allow blocking, and we do that with the nonblocking status of the type. We make the check when the pool is specified so we can avoid adding a special check to the declaration of a pool type – we want pool types to follow the same rules as any other type.
An allocator of a type T that does not support subpools allocates storage from T's storage pool. If the storage pool is a user-defined object, then the storage is allocated by calling Allocate as described below. Allocators for types that support subpools are described in 13.11.4.
If the implementation chooses to represent the designated subtype in multiple pieces, one allocator evaluation might result in more than one call upon Allocate. In any case, allocators for the access type obtain all the required storage for an object of the designated type by calling the specified Allocate procedure.
{8652/0111} If D (the designated type of T) includes subcomponents of other access types, they will be allocated from the storage pools for those types, even if those allocators are executed as part of the allocator of T (as part of the initialization of the object). For instance, an access-to-task type TT may allocate the data structures used to implement the task value from other storage pools. (In particular, the task stack does not necessarily need to be allocated from the storage pool for TT.)
If Storage_Pool is not specified for a type defined by an access_to_object_definition, then the implementation chooses a standard storage pool for it in an implementation-defined manner. In this case, the exception Storage_Error is raised by an allocator if there is not enough storage. It is implementation defined whether or not the implementation provides user-accessible names for the standard pool type(s).
The manner of choosing a storage pool is covered by a Documentation Requirement below, so it is not summarized here.
Whether or not the implementation provides user-accessible names for the standard pool type(s).
To be honest: pragma Default_Storage_Pool (see 13.11.3) can be used to specify a specific pool (or none at all) to be used with access types declared in a particular declaration list, rather than a standard storage pool.
Although there is no language-defined user-accessible name for the standard pool type(s), the default use of a standard pool may be indicated using the identifier Standard in the pragma Default_Storage_Pool.
An access-to-object type defined by a derived_type_definition inherits its pool from its parent type, so all access-to-object types in the same derivation class share the same pool. Hence the “defined by an access_to_object_definition” wording above.
There is no requirement that all storage pools be implemented using a contiguous block of memory (although each allocation returns a pointer to a contiguous block of memory).
The type(s) of the standard pool(s), and the primitive Allocate, Deallocate, and Storage_Size subprograms for the standard pool(s) are nonblocking. Concurrent invocations of these subprograms do not conflict with one another (see 9.10) when applied to standard storage pools.
We need to specify that the type is nonblocking so that an instance of Unchecked_Deallocation is nonblocking if the object type is nonblocking (as the type is used in the contract). Ada 95 did not declare standard allocation/deallocation as potentially blocking, so these things can be used in protected types, and we want that to remain true (with static checking).
If Storage_Size is specified for an access type T, an implementation-defined pool P is used for the type. The Storage_Size of P is at least that requested, and the storage for P is reclaimed when the master containing the declaration of the access type is left. If the implementation cannot satisfy the request, Storage_Error is raised at the freezing point of type T. The storage pool P is used only for allocators returning type T or other access types specified to use T'Storage_Pool. Storage_Error is raised by an allocator returning such a type if the storage space of P is exhausted (additional memory is not allocated). The type of P, and the primitive Allocate, Deallocate, and Storage_Size subprograms of P are nonblocking.
If neither Storage_Pool nor Storage_Size are specified, then the meaning of Storage_Size is implementation defined.
The meaning of Storage_Size when neither the Storage_Size nor the Storage_Pool is specified for an access type.
The Storage_Size function and attribute will return the actual size, rather than the requested size. Comments about rounding up, zero, and negative on task Storage_Size apply here, as well. See also AI83-00557, AI83-00558, and AI83-00608.
The expression in a Storage_Size clause need not be static.
The reclamation happens after the master is finalized.
For a pool allocated on the stack, normal stack cut-back can accomplish the reclamation. For a library-level pool, normal partition termination actions can accomplish the reclamation.
If Storage_Pool is specified for an access type, then the specified pool is used.
The effect of calling Allocate and Deallocate for a standard storage pool directly (rather than implicitly via an allocator or an instance of Unchecked_Deallocation) is unspecified.
For example, an allocator might put the pool element on a finalization list. If the user directly Deallocates it, instead of calling an instance of Unchecked_Deallocation, then the implementation would probably try to finalize the object upon master completion, which would be bad news. Therefore, the implementation should define such situations as erroneous.
Erroneous Execution
21If Storage_Pool is specified for an access type, then if Allocate can satisfy the request, it should allocate a contiguous block of memory, and return the address of the first storage element in Storage_Address. The block should contain Size_In_Storage_Elements storage elements, and should be aligned according to Alignment. The allocated storage should not be used for any other purpose while the pool element remains in existence. If the request cannot be satisfied, then Allocate should propagate an exception [(such as Storage_Error)]. If Allocate behaves in any other manner, then the program execution is erroneous.
Implementation Requirements
21.1/3The Allocate procedure of a user-defined storage pool object P may be called by the implementation only to allocate storage for a type T whose pool is P, only at the following points:
- During the execution of an
allocatorof type T;
This includes during the evaluation of the initializing expression such as an aggregate; this is important if the initializing expression is built in place. We need to allow allocation to be deferred until the size of the object is known.
- During the execution of a return statement for a function whose result is built-in-place in the result of an
allocatorof type T;
We need this bullet as well as the preceding one in order that exceptions that propagate from such a call to Allocate can be handled within the return statement. We don't want to require the generation of special handling code in this unusual case, as it would add overhead to most return statements of composite types.
- During the execution of an assignment operation with a target of an allocated object of type T with a part that has an unconstrained discriminated subtype with defaults.
We allow Allocate to be called during assignment of objects with mutable parts so that mutable objects can be implemented with reallocation on assignment. (Unfortunately, the term "mutable" is only defined in the AARM, so we have to use the long-winded wording shown here.)
Of course, explicit calls to Allocate are also allowed and are not bound by any of the rules found here.
For each of the calls of Allocate described above, P (equivalent to T'Storage_Pool) is passed as the Pool parameter. The Size_In_Storage_Elements parameter indicates the number of storage elements to be allocated, and is no more than D'Max_Size_In_Storage_Elements, where D is the designated subtype of T. The Alignment parameter is a nonzero integral multiple of D'Alignment if D is a specific type, and otherwise is a nonzero integral multiple of the alignment of the specific type identified by the tag of the object being created; it is unspecified if there is no such value. The Alignment parameter is no more than D'Max_Alignment_For_Allocation. The result returned in the Storage_Address parameter is used as the address of the allocated storage, which is a contiguous block of memory of Size_In_Storage_Elements storage elements. [Any exception propagated by Allocate is propagated by the construct that contained the call.]
Note that the implementation does not turn other exceptions into Storage_Error.
“Nonzero integral multiple” of an alignment includes the alignment value itself, of course. The value is unspecified if the alignment of the specific type is zero.
The number of calls to Allocate that will be used to implement an allocator for any particular type is unspecified. The number of calls to Deallocate that will be used to implement an instance of Unchecked_Deallocation (see 13.11.2) for any particular object is the same as the number of Allocate calls for that object.
This supports objects that are allocated in one or more parts. The second sentence prevents extra or missing calls to Deallocate.
To be honest: The number of calls to Deallocate from all sources for an object always will be the same as the number of calls to Allocate from all sources for that object. However, in unusual cases, not all of those Deallocate calls may be made by an instance of Unchecked_Deallocation. Specifically, in the unusual case of assigning to an object of a mutable variant record type such that the variant changes, some of the Deallocate calls may be made by the assignment (as may some of the Allocate calls).
We do not define the relative order of multiple calls used to deallocate the same object — that is, if the allocator allocated two pieces x and y, then an instance of Unchecked_Deallocation might deallocate x and then y, or it might deallocate y and then x.
The Deallocate procedure of a user-defined storage pool object P may be called by the implementation to deallocate storage for a type T whose pool is P only at the places when an Allocate call is allowed for P, during the execution of an instance of Unchecked_Deallocation for T, or as part of the finalization of the collection of T. For such a call of Deallocate, P (equivalent to T'Storage_Pool) is passed as the Pool parameter. The value of the Storage_Address parameter for a call to Deallocate is the value returned in the Storage_Address parameter of the corresponding successful call to Allocate. The values of the Size_In_Storage_Elements and Alignment parameters are the same values passed to the corresponding Allocate call. Any exception propagated by Deallocate is propagated by the construct that contained the call.
We allow Deallocate to be called anywhere that Allocate is, in order to allow the recovery of storage from failed allocations (that is, those that raise exceptions); from extended return statements that exit via a goto, exit, or locally handled exception; and from objects that are reallocated when they are assigned. In each of these cases, we would have a storage leak if the implementation did not recover the storage (there is no way for the programmer to do it). We do not require such recovery, however, as it could be a serious performance drag on these operations.
Documentation Requirements
22/5An implementation shall document the set of values that a user-defined Allocate procedure has to accept for the Alignment parameter. An implementation shall document how the standard storage pool is chosen, and how storage is allocated by standard storage pools.
Documentation Requirement: The set of values that a user-defined Allocate procedure needs to accept for the Alignment parameter. How the standard storage pool is chosen, and how storage is allocated by standard storage pools.
Implementation Advice
23An implementation should document any cases in which it dynamically allocates heap storage for a purpose other than the evaluation of an allocator.
Any cases in which heap storage is dynamically allocated other than as part of the evaluation of an allocator should be documented.
This is “” because the term “heap storage” is not formally definable; therefore, it is not testable whether the implementation obeys this advice.
A default (implementation-provided) storage pool for an access-to-constant type should not have overhead to support deallocation of individual objects.
A default storage pool for an access-to-constant type should not have overhead to support deallocation of individual objects.
Unchecked_Deallocation is not defined for such types. If the access-to-constant type is library-level, then no deallocation (other than at partition completion) will ever be necessary, so if the size needed by an allocator of the type is known at link-time, then the allocation should be performed statically. If, in addition, the initial value of the designated object is known at compile time, the object can be allocated to read-only memory.
If the Storage_Size for an access type is specified, the storage pool should consist of a contiguous block of memory, possibly allocated on the stack. The pool should contain approximately this number of storage elements. These storage elements should be reserved at the place of the Storage_Size clause, so that allocators cannot raise Storage_Error due to running out of pool space until the appropriate number of storage elements has been used up. This approximate (possibly rounded-up) value should be used as a maximum; the implementation should not increase the size of the pool on the fly. If the Storage_Size for an access type is specified as zero, then the pool should not take up any storage space, and any allocator for the type should raise Storage_Error.
Note that most of this is approximate, and so cannot be (portably) tested. That's why we make it an Implementation Note. There is no particular number of allocations that is guaranteed to succeed, and there is no particular number of allocations that is guaranteed to fail.
The storage pool used for an allocator of an anonymous access type should be determined as follows:
- If the
allocatoris defining a coextension (see 3.10.2) of an object being created by an outerallocator, then the storage pool used for the outerallocatorshould also be used for the coextension; 25.2/2 - For other access discriminants and access parameters, the storage pool should be created at the point of the
allocator, and be reclaimed when the allocated object becomes inaccessible; 25.3/3 - If the
allocatordefines the result of a function with an access result, the storage pool is determined as though theallocatorwere in place of the call of the function. If the call is the operand of a type conversion, the storage pool is that of the target access type of the conversion. If the call is itself defining the result of a function with an access result, this rule is applied recursively; 25.4/5 - Otherwise, a default storage pool should be created at the point where the anonymous access type is elaborated; such a storage pool may have no mechanism for the deallocation of individual objects.
Usually, a storage pool for an access discriminant or access parameter should be created at the point of an allocator, and be reclaimed when the designated object becomes inaccessible. For other anonymous access types, the pool should be created at the point where the type is elaborated and may have no mechanism for the deallocation of individual objects.
For access parameters and access discriminants, the "storage pool" for an anonymous access type would not normally exist as a separate entity. Instead, the designated object of the allocator would be allocated, in the case of an access parameter, as a local aliased variable at the call site, and in the case of an access discriminant, contiguous with the object containing the discriminant. This is similar to the way storage for aggregates is typically managed.
For other sorts of anonymous access types, this implementation is not possible in general, as the accessibility of the anonymous access type is that of its declaration, while the allocator could be more nested. In this case, a "real" storage pool is required. Note, however, that this storage pool need not support (separate) deallocation, as it is not possible to instantiate Unchecked_Deallocation with an anonymous access type. (If deallocation is needed, the object should be allocated for a named access type and converted.) Thus, deallocation only need happen when the anonymous access type itself goes out of scope; this is similar to the case of an access-to-constant type.
NOTE 1 A user-defined storage pool type can be obtained by extending the Root_Storage_Pool type, and overriding the primitive subprograms Allocate, Deallocate, and Storage_Size. A user-defined storage pool can then be obtained by declaring an object of the type extension. The user can override Initialize and Finalize if there is any desire for nontrivial initialization and finalization for a user-defined pool type. For example, Finalize can reclaim blocks of storage that are allocated separately from the pool object itself.
NOTE 2 The writer of the user-defined allocation and deallocation procedures, and users of allocators for the associated access type, are responsible for dealing with any interactions with tasking. In particular:
- If the
allocators are used in different tasks, they require mutual exclusion. 29 - If they are used inside protected objects, they cannot block.
- If they are used by interrupt handlers (see C.3, “Interrupt Support”), the mutual exclusion mechanism has to work properly in that context.
NOTE 3 The primitives Allocate, Deallocate, and Storage_Size are declared as abstract (see 3.9.3), and therefore they have to be overridden when a new (nonabstract) storage pool type is declared.
Note that the Storage_Pool attribute denotes an object, rather than a value, which is somewhat unusual for attributes.
The calls to Allocate, Deallocate, and Storage_Size are dispatching calls — this follows from the fact that the actual parameter for Pool is T'Storage_Pool, which is of type Root_Storage_Pool'Class. In many cases (including all cases in which Storage_Pool is not specified), the compiler can determine the tag statically. However, it is possible to construct cases where it cannot.
All access types in the same derivation class share the same pool, whether implementation defined or user defined. This is necessary because we allow type conversions among them (even if they are pool-specific), and we want pool-specific access values to always designate an element of the right pool.
If an access type has a standard storage pool, then the implementation doesn't actually have to follow the pool interface described here, since this would be semantically invisible. For example, the allocator could conceivably be implemented with inline code.
Examples
32To associate an access type with a storage pool object, the user first declares a pool object of some type derived from Root_Storage_Pool. Then, the user defines its Storage_Pool attribute, as follows:
Pool_Object : Some_Storage_Pool_Type;
34
type T is access Designated;
for T'Storage_Pool use Pool_Object;
Another access type can be added to an existing storage pool, via:
for T2'Storage_Pool use T'Storage_Pool;
The semantics of this is implementation defined for a standard storage pool.
For example, the implementation is allowed to choose a storage pool for T that takes advantage of the fact that T is of a certain size. If T2 is not of that size, then the above will probably not work.
As usual, a derivative of Root_Storage_Pool can define additional operations. For example, consider the Mark_Release_Pool_Type defined in 13.11.6, that has two additional operations, Mark and Release, the following is a possible use:
{8652/0041} type Mark_Release_Pool_Type
(Pool_Size : Storage_Elements.Storage_Count)
is new Subpools.Root_Storage_Pool_With_Subpools with private;
-- As defined in package MR_Pool, see 13.11.6
40
...
41/5
Our_Pool : Mark_Release_Pool_Type (Pool_Size => 2000);
My_Mark : Subpool_Handle; -- As declared in 13.11.6
42/3
type Acc is access ...;
for Acc'Storage_Pool use Our_Pool;
...
43/3
My_Mark := Mark(Our_Pool);
... -- Allocate objects using “new (My_Mark) Designated(...)”.
Release(My_Mark); -- Finalize objects and reclaim storage.
Extensions to Ada 83
User-defined storage pools are new to Ada 95.
Wording Changes from Ada 83
Ada 83 originally introduced the concept called a “collection”, which is similar to what we call a storage pool. All access types in the same derivation class share the same collection. Ada 95 introduces the storage pool, which is similar in that all access types in the same derivation class share the same storage pool, but other (unrelated) access types can also share the same storage pool, either by default, or as specified by the user. A collection is an amorphous grouping of objects (mainly used to describe finalization of access types); a storage pool is a more concrete concept — hence the different name.
RM83 states the erroneousness of reading or updating deallocated objects incorrectly by missing various cases.
Incompatibilities With Ada 95
Amendment Storage pools (and Storage_Size) are not defined for access-to-subprogram types. The original Ada 95 wording defined the attributes, but said nothing about their values. If a program uses attributes Storage_Pool or Storage_Size on an access-to-subprogram type, it will need to be corrected for Ada 2005. That's a good thing, as such a use is a bug — the concepts never were defined for such types.
Extensions to Ada 95
Amendment Added pragma Preelaborable_Initialization to type Root_Storage_Pool, so that extensions of it can be used to declare default-initialized objects in preelaborated units.
Wording Changes from Ada 95
Wording Changes from Ada 2005
Added the missing definition of the storage pool of an allocator for an anonymous access result type.
Clarified when an implementation is allowed to call Allocate and Deallocate, and the requirements on such calls.
Added wording to specify that the alignment for an allocator with a class-wide designated type comes from the specific type that is allocated.
Added wording to allow larger alignments for calls to Allocate made by allocators, up to Max_Alignment_For_Allocation. This eases implementation in some cases.
Extensions to Ada 2012
Package System.Storage_Pools now has Pure categorization, so it can be mentioned for any package. Note that this does not allow storage pool objects to be shared between partitions, as these necessarily must be variables; however, this does allow a storage pool type to be shared.
Wording Changes from Ada 2012
Corrigendum: Tightened up the description of the implementation-defined pool used when Storage_Size is specified. This is not intended to change any implementation.
Specified that the standard pool(s), and the pool(s) used to implement a specified Storage_Size, are nonblocking and support concurrent use. This was always true (which is why this is not documented as an incompatibility), but it never was explicitly stated before. In the past, the absence of wording defining something to be potentially blocking determined if blocking was not allowed. Similarly, the absence of a statement that allocation was not allowed in multiple tasks implied that it was allowed.
13.11.1 Storage Allocation Attributes
1/3[The Max_Size_In_Storage_Elements and Max_Alignment_For_Allocation attributes may be useful in writing user-defined pool types.]
Static Semantics
2/3For 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.
If S is an unconstrained array subtype, or an unconstrained subtype with discriminants, S'Max_Size_In_Storage_Elements might be very large.
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.
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.
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.
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
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
13.11.2 Unchecked Storage Deallocation
1[ 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
2The 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;
The aspect Convention implies that the attribute Access is not allowed for instances of Unchecked_Deallocation.
Legality Rules
3.1/3A 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.
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
4Given 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:
1.
- After executing Free(X), the value of X is null.
2.- Free(X), when X is already equal to null, has no effect.
3.- 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.
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
11It is a bounded error to free a discriminated, unterminated task object. The possible consequences are:
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.
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.
The storage might never be reclaimed.
An access value that designates a nonexistent object is called a dangling reference.
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.
[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.
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.
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).
If a dangling reference is assigned into an object, including being passed to a formal parameter, that object also contains a dangling reference afterwards.
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/3Evaluating 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.
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.
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
17For a standard storage pool, Free should actually reclaim the storage.
For a standard storage pool, an instance of Unchecked_Deallocation should actually reclaim the storage.
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.
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.
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.
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 1 The rules here that refer to Free apply to any instance of Unchecked_Deallocation.
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
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
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.
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.
Inconsistencies With Ada 2012
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.
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
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
2/3The form of a pragma Default_Storage_Pool is as follows:
pragma Default_Storage_Pool (storage_pool_indicator);
storage_pool_indicator ::= storage_pool_name | null | Standard
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/3The storage_pool_name is expected to be of type Root_Storage_Pool'Class.
Legality Rules
4/3The storage_pool_name shall denote a variable.
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.
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.
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.
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.]
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.
This is to prevent confusion in cases like this:
package Parent is
pragma Default_Storage_Pool(...);
...
end Parent;
4.c/3
pragma Default_Storage_Pool(...); -- Illegal!
package Parent.Child is
...
end Parent.Child;
where the Default_Storage_Pool on Parent.Child would not (if it were legal) override the one in Parent.
Static Semantics
5/4The language-defined aspect Default_Storage_Pool may be specified for a generic instance; it defines the default pool for access types within an instance. .
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.
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.
Aspect Description for Default_Storage_Pool: Default storage pool for a generic instance.
The effect of specifying the aspect Default_Storage_Pool on an instance of a language-defined generic unit is implementation-defined.
The effect of specifying aspect Default_Storage_Pool on an instance of a language-defined generic unit.
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:
- If the default pool is null, the Storage_Size attribute is defined by the language to be zero. [Therefore, an
allocatorfor such a type is illegal.] 6.2/4 - If the default pool is neither null nor Standard, the Storage_Pool attribute is that pool.
Otherwise (including when the default pool is specified as Standard), the standard storage pool is used for the type as described in 13.11.
Default_Storage_Pool is the only way to specify the storage pool for an anonymous access type.
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.
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.
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.
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.
This paragraph was deleted.
Implementation Permissions
8/3An 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.
Wording Changes from Ada 83
Incompatibilities With Ada 2005
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
Wording Changes from Ada 2005
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
Wording Changes from Ada 2012
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
1/3This 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
2/3The 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/3
type Subpool_Handle is access all Root_Subpool'Class;
for Subpool_Handle'Storage_Size use 0;
7/3
function 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/3
function 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/3
procedure 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/3
overriding
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/3
overriding
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/3
private
... -- not specified by the language
end System.Storage_Pools.Subpools;
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.
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.]
We know that subpool handles designate subpool objects because the declaration of Subpool_Handle says so.
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.
Pool_of_Subpool and Set_Pool_of_Subpool are provided by the Ada implementation and typically will not be overridden by the pool implementer.
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.
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).
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/3If 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.
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/3When 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:
- the
nameused 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.
Program_Error is raised if either of these checks fail.
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.
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.
A call to Subpools.Allocate(P, Addr, Size, Align) does the following:
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)));
An allocator that allocates in a subpool raises Program_Error if the allocated object has task parts.
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.
Unless overridden, Default_Subpool_for_Pool propagates Program_Error.
Erroneous Execution
31.1/4If 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/3When 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.]
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.
- 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.
- 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.
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, can use it to define the Storage_Pool attribute of one or more access types, and then can invoke Create_Subpool to obtain subpool handles associated with the pool.
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).
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
Wording Changes from Ada 2012
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.
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
1/3A subpool may be explicitly deallocated using Unchecked_Deallocate_Subpool.
Static Semantics
2/3The 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;
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.
If Subpool is null, a call on Unchecked_Deallocate_Subpool has no effect. Otherwise, the subpool is finalized, and Subpool is set to null.
Finalization of a subpool has the following effects in the given order:
- This paragraph was deleted.
1.- Any of the objects allocated from the subpool that still exist are finalized in an arbitrary order;
2.- All of the objects allocated from the subpool cease to exist;
3.- The following [dispatching] call is then made:
Deallocate_Subpool(Pool_of_Subpool(Subpool).all, Subpool);
4.
- The subpool ceases to belong to any pool.
Finalization of a Root_Storage_Pool_With_Subpools object finalizes all subpools that belong to that pool that have not yet been finalized.
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.
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.
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.
If Unchecked_Deallocation is not called (the usual case), the object will be finalized when Unchecked_Deallocate_Subpool is called.
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
Wording Changes from Ada 2012
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.
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
1/3The following example is a simple but complete implementation of the classic Mark/Release pool using subpools:
with System.Storage_Pools.Subpools;
with System.Storage_Elements;
with Ada.Unchecked_Deallocate_Subpool;
package MR_Pool is
3/3
use System.Storage_Pools;
-- For uses of Subpools.
use System.Storage_Elements;
-- For uses of Storage_Count and Storage_Array.
4/3
-- Mark and Release work in a stack fashion, and allocations are not allowed
-- from a subpool other than the one at the top of the stack. This is also
-- the default pool.
5/3
subtype Subpool_Handle is Subpools.Subpool_Handle;
6/3
type Mark_Release_Pool_Type (Pool_Size : Storage_Count) is new
Subpools.Root_Storage_Pool_With_Subpools with private;
7/3
function Mark (Pool : in out Mark_Release_Pool_Type)
return not null Subpool_Handle;
8/3
procedure Release (Subpool : in out Subpool_Handle) renames
Ada.Unchecked_Deallocate_Subpool;
9/3
private
10/3
type MR_Subpool is new Subpools.Root_Subpool with record
Start : Storage_Count;
end record;
subtype Subpool_Indexes is Positive range 1 .. 10;
type Subpool_Array is array (Subpool_Indexes) of aliased MR_Subpool;
11/4
type Mark_Release_Pool_Type (Pool_Size : Storage_Count) is new
Subpools.Root_Storage_Pool_With_Subpools with record
Storage : Storage_Array (0 .. Pool_Size);
Next_Allocation : Storage_Count := 0;
Markers : Subpool_Array;
Current_Pool : Subpool_Indexes := 1;
end record;
12/3
overriding
function Create_Subpool (Pool : in out Mark_Release_Pool_Type)
return not null Subpool_Handle;
13/3
function Mark (Pool : in out Mark_Release_Pool_Type)
return not null Subpool_Handle renames Create_Subpool;
14/3
overriding
procedure Allocate_From_Subpool (
Pool : in out Mark_Release_Pool_Type;
Storage_Address : out System.Address;
Size_In_Storage_Elements : in Storage_Count;
Alignment : in Storage_Count;
Subpool : not null Subpool_Handle);
15/3
overriding
procedure Deallocate_Subpool (
Pool : in out Mark_Release_Pool_Type;
Subpool : in out Subpool_Handle);
16/3
overriding
function Default_Subpool_for_Pool (Pool : in out Mark_Release_Pool_Type)
return not null Subpool_Handle;
17/3
overriding
procedure Initialize (Pool : in out Mark_Release_Pool_Type);
18/3
-- We don't need Finalize.
19/3
end MR_Pool;
20/3
package body MR_Pool is
21/3
use type Subpool_Handle;
22/3
procedure Initialize (Pool : in out Mark_Release_Pool_Type) is
-- Initialize the first default subpool.
begin
Pool.Markers(1).Start := 1;
Subpools.Set_Pool_of_Subpool
(Pool.Markers(1)'Unchecked_Access, Pool);
end Initialize;
23/3
function Create_Subpool (Pool : in out Mark_Release_Pool_Type)
return not null Subpool_Handle is
-- Mark the current allocation location.
begin
if Pool.Current_Pool = Subpool_Indexes'Last then
raise Storage_Error; -- No more subpools.
end if;
Pool.Current_Pool := Pool.Current_Pool + 1; -- Move to the next subpool
24/3
return Result : constant not null Subpool_Handle :=
Pool.Markers(Pool.Current_Pool)'Unchecked_Access
do
Pool.Markers(Pool.Current_Pool).Start := Pool.Next_Allocation;
Subpools.Set_Pool_of_Subpool (Result, Pool);
end return;
end Create_Subpool;
25/3
procedure Deallocate_Subpool (
Pool : in out Mark_Release_Pool_Type;
Subpool : in out Subpool_Handle) is
begin
if Subpool /= Pool.Markers(Pool.Current_Pool)'Unchecked_Access then
raise Program_Error; -- Only the last marked subpool can be released.
end if;
if Pool.Current_Pool /= 1 then
Pool.Next_Allocation := Pool.Markers(Pool.Current_Pool).Start;
Pool.Current_Pool := Pool.Current_Pool - 1; -- Move to the previous subpool
else -- Reinitialize the default subpool:
Pool.Next_Allocation := 1;
Subpools.Set_Pool_of_Subpool
(Pool.Markers(1)'Unchecked_Access, Pool);
end if;
end Deallocate_Subpool;
26/3
function Default_Subpool_for_Pool (Pool : in out Mark_Release_Pool_Type)
return not null Subpool_Handle is
begin
return Pool.Markers(Pool.Current_Pool)'Unchecked_Access;
end Default_Subpool_for_Pool;
27/3
procedure Allocate_From_Subpool (
Pool : in out Mark_Release_Pool_Type;
Storage_Address : out System.Address;
Size_In_Storage_Elements : in Storage_Count;
Alignment : in Storage_Count;
Subpool : not null Subpool_Handle) is
begin
if Subpool /= Pool.Markers(Pool.Current_Pool)'Unchecked_Access then
raise Program_Error; -- Only the last marked subpool can be used for allocations.
end if;
28/4
-- Check for the maximum supported alignment, which is the alignment of the storage area:
if Alignment > Pool.Storage'Alignment then
raise Program_Error;
end if;
-- Correct the alignment if necessary:
Pool.Next_Allocation := Pool.Next_Allocation +
((-Pool.Next_Allocation) mod Alignment);
if Pool.Next_Allocation + Size_In_Storage_Elements >
Pool.Pool_Size then
raise Storage_Error; -- Out of space.
end if;
Storage_Address := Pool.Storage (Pool.Next_Allocation)'Address;
Pool.Next_Allocation :=
Pool.Next_Allocation + Size_In_Storage_Elements;
end Allocate_From_Subpool;
29/3
end MR_Pool;