Contents Index Previous Next
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
[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 type. The user may define new pool types, and may override
the choice of pool for an access 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
type Root_Storage_Pool is
abstract new Ada.Finalization.Limited_Controlled with private;
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/1
{
8652/0009}
For every access subtype S, the following
representation attributes are
defined:
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}
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
Implementation defined: The
manner of choosing a storage pool for an access type when Storage_Pool
is not specified for the type.
17.b
Implementation defined: Whether
or not the implementation provides user-accessible names for the standard
pool type(s).
17.c
Ramification: 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
Implementation defined: The
meaning of Storage_Size.
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
Implementation defined: Implementation-defined
aspects of 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
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
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
A storage pool for an anonymous access type should
be created at the point of an allocator for the type, and be reclaimed
when the designated object becomes inaccessible.
25.a
Implementation Note: Normally
the "storage pool" for an anonymous access type would not 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.
26
23 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
24 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
25 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}
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.
Contents Index Previous Next Legal