13.11 Storage Management
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.
Legality Rules
If Storage_Pool is specified for a given access type,
Storage_Size shall not be specified for it.
Static Semantics
The following language-defined
library package exists:
with Ada.Finalization;
with System.Storage_Elements;
package System.Storage_Pools
with Pure, Nonblocking => False
is
type Root_Storage_Pool
is
abstract new Ada.Finalization.Limited_Controlled
with private
with Preelaborable_Initialization;
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;
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;
function Storage_Size(Pool : Root_Storage_Pool)
return Storage_Elements.Storage_Count
is abstract;
private
... -- not specified by the language
end System.Storage_Pools;
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.
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
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.
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 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 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.
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.
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.
Erroneous Execution
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.
Implementation Requirements
The 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
allocator
of type
T;
During the execution of a return statement for
a function whose result is built-in-place in the result of an
allocator
of type
T;
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.
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.
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.
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.
Documentation Requirements
An 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.
Implementation Advice
An implementation should document any cases in which
it dynamically allocates heap storage for a purpose other than the evaluation
of an
allocator.
A default (implementation-provided) storage pool
for an access-to-constant type should not have overhead to support deallocation
of individual objects.
The storage pool used
for an
allocator
of an anonymous access type should be determined as follows:
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;
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;
If the
allocator
defines the result of a function with an access result, the storage pool
is determined as though the
allocator
were 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;
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.
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.
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.
Examples
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:
Pool_Object : Some_Storage_Pool_Type;
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.
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:
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
...
Our_Pool : Mark_Release_Pool_Type (Pool_Size => 2000);
My_Mark : Subpool_Handle; --
As declared in 13.11.6type Acc is access ...;
for Acc'Storage_Pool use Our_Pool;
...
My_Mark := Mark(Our_Pool);
... -- Allocate objects using “new (My_Mark) Designated(...)”.
Release(My_Mark); -- Finalize objects and reclaim storage.
Ada 2005 and 2012 Editions sponsored in part by Ada-Europe
