13.11 Storage Management
1
[
{user-defined storage
management} {storage
management (user-defined)} {user-defined
heap management} {heap
management (user-defined)} 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.]
2/2
{
AI95-00435-01}
[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.]
2.a
Ramification: 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.
Legality Rules
3
If Storage_Pool is specified for a given access type,
Storage_Size shall not be specified for it.
3.a
Reason: 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 non-first 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
4
The following language-defined
library package exists:
5
with Ada.Finalization;
with System.Storage_Elements;
package System.Storage_Pools
is
pragma Preelaborate(System.Storage_Pools);
6/2
{
AI95-00161-01}
type Root_Storage_Pool
is
abstract new Ada.Finalization.Limited_Controlled
with private;
pragma Preelaborable_Initialization(Root_Storage_Pool);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;
10.a
Reason: The Alignment parameter is provided
to Deallocate because some allocation strategies require it. If it is
not needed, it can be ignored.
11
{storage pool type}
{pool type}
A
storage pool type (or
pool type)
is a descendant of Root_Storage_Pool.
{storage
pool element} {pool
element} {element
(of a storage pool)} The
elements
of a storage pool are the objects allocated in the pool by
allocators.
11.a
Discussion: 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.
12/2
13
S'Storage_Pool
Denotes the storage pool of the
type of S. The type of this attribute is Root_Storage_Pool'Class.
14
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.
14.a
Ramification: Storage_Size is also defined
for task subtypes and objects — see
13.3.
14.b
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.
15
{specifiable (of
Storage_Size for a non-derived access-to-object type) [partial]}
{specifiable (of
Storage_Pool for a non-derived access-to-object type) [partial]}
{Storage_Pool clause}
{Storage_Size clause}
Storage_Size or Storage_Pool may be specified for
a non-derived access-to-object type via an
attribute_definition_clause;
the
name in a Storage_Pool clause shall denote
a variable.
16
An
allocator of type T
allocates storage from T's storage pool. If the storage pool is a user-defined
object, then the storage is allocated by calling Allocate, passing T'Storage_Pool
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. The Alignment parameter is D'Alignment.
{contiguous representation [partial]}
{discontiguous representation
[partial]} The result returned in the Storage_Address
parameter is used by the
allocator 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
allocator.]
16.a
Ramification: 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.
16.b
Note that the implementation does not turn other
exceptions into Storage_Error.
16.b.1/1
{
8652/0111}
{
AI95-00103-01}
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.) 17
{standard storage
pool} 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.
{Storage_Check
[partial]} {check,
language-defined (Storage_Check)} {Storage_Error
(raised by failure of run-time check)} 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).
17.a/2
This paragraph
was deleted.Implementation defined:
The manner of choosing a storage pool
for an access type when Storage_Pool is not specified for the type.
17.a.1/2
Discussion: The
manner of choosing a storage pool is covered by a Documentation Requirement
below, so it is not summarized here.
17.b
Implementation defined: Whether or not
the implementation provides user-accessible names for the standard pool
type(s).
17.c/2
Ramification: {
AI95-00230-01}
An anonymous access type has no 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.
17.d
{
contiguous representation [partial]}
{
discontiguous representation [partial]}
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).
18
If Storage_Size is specified for an access type,
then the Storage_Size of this pool is at least that requested, and the
storage for the pool is reclaimed when the master containing the declaration
of the access type is left.
{Storage_Error
(raised by failure of run-time check)} If
the implementation cannot satisfy the request, Storage_Error is raised
at the point of the
attribute_definition_clause.
If neither Storage_Pool nor Storage_Size are specified, then the meaning
of Storage_Size is implementation defined.
18.a/2
Implementation defined: The meaning of
Storage_Size when neither the Storage_Size nor
the Storage_Pool is specified for an access type.
18.b
Ramification: 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.
18.c
The expression in a Storage_Size clause need
not be static.
18.d
The reclamation happens after the master is
finalized.
18.e
Implementation Note: 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.
19
If Storage_Pool is specified for an access type,
then the specified pool is used.
20
{unspecified
[partial]} 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.
20.a
Ramification: 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
21
{erroneous execution
(cause) [partial]} If 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.
Documentation Requirements
22
An implementation shall document the set of values
that a user-defined Allocate procedure needs 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.
22.a/2
This paragraph
was deleted.Implementation defined:
Implementation-defined aspects of storage
pools.
22.b/2
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
23
An implementation should document any cases in which
it dynamically allocates heap storage for a purpose other than the evaluation
of an allocator.
23.a.1/2
Implementation Advice:
Any cases in which heap storage is dynamically
allocated other than as part of the evaluation of an allocator
should be documented.
23.a
Reason: This is “Implementation
Advice” because the term “heap storage” is not formally
definable; therefore, it is not testable whether the implementation obeys
this advice.
24
A default (implementation-provided) storage pool
for an access-to-constant type should not have overhead to support deallocation
of individual objects.
24.a.1/2
Implementation Advice:
A default storage pool for an access-to-constant
type should not have overhead to support deallocation of individual objects.
24.a
Ramification: 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.
24.b
Implementation Note: 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.
24.c
Ramification: 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.
25/2
{
AI95-00230-01}
The A
storage pool
used for
an
allocator of an anonymous access type
should be
determined as follows: created
at the point of an allocator for the type, and be reclaimed when the
designated object becomes inaccessible;25.1/2
- {AI95-00230-01}
{AI95-00416-01}
If the allocator is
defining a coextension (see 3.10.2) of an
object being created by an outer allocator,
then the storage pool used for the outer allocator
should also be used for the coextension;
25.2/2
- {AI95-00230-01}
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/2
- {AI95-00230-01}
Otherwise, a default storage pool should be created
at the point where the anonymous access type is elaborated; such a storage
pool need not support deallocation of individual objects.
25.a.1/2
Implementation Advice:
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 need
not support deallocation of individual objects.
25.a/2
Implementation Note: {
AI95-00230-01}
For access parameters and access discriminants, Normally
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.
25.b/2
{
AI95-00230-01}
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. 26
25 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 need for non-trivial initialization and finalization for a user-defined
pool type. For example, Finalize might reclaim blocks of storage that
are allocated separately from the pool object itself.
27
26 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:
28
- If the allocators
are used in different tasks, they require mutual exclusion.
29
- If they are used inside protected
objects, they cannot block.
30
- If they are used by interrupt
handlers (see C.3, “Interrupt
Support”), the mutual exclusion mechanism has to work properly
in that context.
31
27 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 (non-abstract) storage
pool type is declared.
31.a
Ramification: Note that the Storage_Pool
attribute denotes an object, rather than a value, which is somewhat unusual
for attributes.
31.b
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.
31.c
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.
31.d
Implementation Note: 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
32
To 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:
33
Pool_Object : Some_Storage_Pool_Type;
34
type T is access Designated;
for T'Storage_Pool use Pool_Object;
35
Another access type may
be added to an existing storage pool, via:
36
for T2'Storage_Pool use T'Storage_Pool;
37
The semantics of this is implementation defined for
a standard storage pool.
37.a
Reason: 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.
38
As usual, a derivative
of Root_Storage_Pool may define additional operations. For example, presuming
that Mark_Release_Pool_Type has two additional operations, Mark and Release,
the following is a possible use:
39/1
{
8652/0041}
{
AI95-00066-01}
type Mark_Release_Pool_Type
(Pool_Size : Storage_Elements.Storage_Count;
Block_Size : Storage_Elements.Storage_Count)
is new Root_Storage_Pool
with limited private;
40
...
41
MR_Pool : Mark_Release_Pool_Type (Pool_Size => 2000,
Block_Size => 100);
42
type Acc is access ...;
for Acc'Storage_Pool use MR_Pool;
...
43
Mark(MR_Pool);
... -- Allocate objects using “new Designated(...)”.
Release(MR_Pool); -- Reclaim the storage.
Extensions to Ada 83
43.a
{
extensions to Ada 83}
User-defined
storage pools are new to Ada 95.
Wording Changes from Ada 83
43.b
Ada 83 had a concept called a “collection,”
which is similar to what we call a storage pool. All access types in
the same derivation class shared the same collection. In Ada 95, 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 was an amorphous
collection of objects; a storage pool is a more concrete concept —
hence the different name.
43.c
RM83 states the erroneousness of reading or
updating deallocated objects incorrectly by missing various cases.
Incompatibilities With Ada 95
43.d/2
{
AI95-00435-01}
{incompatibilities with Ada 95} Amendment
Correction: 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
43.e/2
{
AI95-00161-01}
{extensions to Ada 95} Amendment
Correction: 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
43.f/2
43.g/2
{
AI95-00230-01}
{
AI95-00416-01}
Added wording to clarify that an allocator
for a coextension nested inside an outer allocator
shares the pool with the outer allocator.
Sponsored by Ada-Europe