[Home] [Prev] [Next] [Index]

13.11 Storage Management

13.11 Storage Management

1
[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
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.

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
For every access subtype S, the following 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
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. 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.

17
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).

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
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. 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 AI-00557, AI-00558, and AI-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
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
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.

NOTES

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
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
User-defined storage pools are new to Ada 9X.

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 9X, 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.

13.11.1 The Max_Size_In_Storage_Elements Attribute

1
[The Max_Size_In_Storage_Elements attribute is useful in writing user-defined pool types.]

Static Semantics

2
For every subtype S, the following attribute is defined:

3
S'Max_Size_In_Storage_Elements Denotes the maximum value for Size_In_Storage_Elements that will be requested via Allocate for an access type whose designated subtype is S. The value of this attribute is of type universal_integer.

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

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

2
The following language-defined generic library procedure exists:

3
generic
   type Object(<>) is limited private;
   type Name   is access  Object;

procedure Ada.Unchecked_Deallocation(X : in out Name);
pragma Convention(Intrinsic, Ada.Unchecked_Deallocation);
pragma Preelaborate(Ada.Unchecked_Deallocation);

3.a
Reason: The pragma Convention implies that the attribute Access is not allowed for instances of Unchecked_Deallocation.

Dynamic Semantics

4
Given an instance of Unchecked_Deallocation declared as follows:

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

6
Procedure Free has the following effect:

7 1.
After executing Free(X), the value of X is null.

8 2.
Free(X), when X is already equal to null, has no effect.

9 3.
Free(X), when X is not equal to null first performs finalization, as described in 7.6. It then deallocates the storage occupied by the object designated by X. If the storage pool is a user-defined object, then the storage is deallocated by calling Deallocate, passing access_to_variable_subtype_name'Storage_Pool as the Pool parameter. Storage_Address is the value returned in the Storage_Address parameter of the corresponding Allocate call. Size_In_Storage_Elements and Alignment are the same values passed to the corresponding Allocate call. There is one exception: if the object being freed contains tasks, the object might not be deallocated.

9.a
Ramification: Free calls only the specified Deallocate procedure to do deallocation. For any given object deallocation, the number of calls to Free (usually one) will be equal to the number of Allocate calls it took to allocate the object. 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 Free might deallocate x and then y, or it might deallocate y and then x.

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

Bounded (Run-Time) Errors

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

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

12 ·
No exception is raised.

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

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

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

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

15.a
Ramification: The storage might never be reclaimed.

Erroneous Execution

16
Evaluating a name that denotes a nonexistent object 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.

Implementation Advice

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

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

NOTES

18 26
The rules here that refer to Free apply to any instance of Unchecked_Deallocation.

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

13.11.3 Pragma Controlled

1
[Pragma Controlled is used to prevent any automatic reclamation of storage (garbage collection) for the objects created by allocators of a given access type.]

Syntax

2
The form of a pragma Controlled is as follows:

3
pragma Controlled(first_subtype_local_name);

3.a
Discussion:  Not to be confused with type Finalization.Controlled.

Legality Rules

4
The first_subtype_local_name of a pragma Controlled shall denote a non-derived access subtype.

Static Semantics

5
A pragma Controlled is a representation pragma that specifies the controlled aspect of representation.

6
Garbage collection is a process that automatically reclaims storage, or moves objects to a different address, while the objects still exist.

6.a
Ramification: Storage reclamation upon leaving a master is not considered garbage collection.

6.b
Note that garbage collection includes compaction of a pool ("moved to a different Address"), even if storage reclamation is not done.

6.c
Reason: Programs that will be damaged by automatic storage reclamation are just as likely to be damaged by having objects moved to different locations in memory. A pragma Controlled should turn off both flavors of garbage collection.

6.d
Implementation Note: If garbage collection reclaims the storage of a controlled object, it should first finalize it. Finalization is not done when moving an object; any self-relative pointers will have to be updated by the garbage collector. If an implementation provides garbage collection for a storage pool containing controlled objects (see 7.6), then it should provide a means for deferring garbage collection of those controlled objects.

6.e
Reason: This allows the manager of a resource released by a Finalize operation to defer garbage collection during its critical regions; it is up to the author of the Finalize operation to do so. Garbage collection, at least in some systems, can happen asynchronously with respect to normal user code. Note that it is not enough to defer garbage collection during Initialize, Adjust, and Finalize, because the resource in question might be used in other situations as well. For example:

6.f
with Ada.Finalization;
package P is

6.g
    type My_Controlled is
        new Ada.Finalization.Limited_Controlled with private;
    procedure Finalize(Object : in out My_Controlled);
    type My_Controlled_Access is access My_Controlled;

6.h
    procedure Non_Reentrant;

6.i
private
    ...
end P;

6.j
package body P is
    X : Integer := 0;
    A : array(Integer range 1..10) of Integer;

6.k
    procedure Non_Reentrant is
    begin
        X := X + 1;
        --If the system decides to do a garbage collection here,
        --then we're in trouble, because it will call Finalize on
        --the collected objects; we essentially have two threads
        --of control erroneously accessing shared variables.
        --The garbage collector behaves like a separate thread
        --of control, even though the user hasn't declared
        --any tasks.
        A(X) := ...;
    end Non_Reentrant;

6.l
    procedure Finalize(Object : in out My_Controlled) is
    begin
        Non_Reentrant;
    end Finalize;
end P;

6.m
with P; use P;
procedure Main is
begin
    ... new My_Controlled ... --allocate some objects
    ... forget the pointers to some of them, so they become garbage
    Non_Reentrant;
end Main;

6.n
It is the user's responsibility to protect against this sort of thing, and the implementation's responsibility to provide the necessary operations.

6.o
We do not give these operations names, nor explain their exact semantics, because different implementations of garbage collection might have different needs, and because garbage collection is not supported by most Ada implementations, so portability is not important here. Another reason not to turn off garbage collection during each entire Finalize operation is that it would create a serial bottleneck; it might be only part of the Finalize operation that conflicts with some other resource. It is the intention that the mechanisms provided be finer-grained than pragma Controlled.

7
If a pragma Controlled is specified for an access type with a standard storage pool, then garbage collection is not performed for objects in that pool.

7.a
Ramification: If Controlled is not specified, the implementation may, but need not, perform garbage collection. If Storage_Pool is specified, then a pragma Controlled for that type is ignored.

7.b
Reason: Controlled means that implementation-provided garbage collection is turned off; if the Storage_Pool is specified, the pool controls whether garbage collection is done.

Implementation Permissions

8
An implementation need not support garbage collection, in which case, a pragma Controlled has no effect.

Wording Changes From Ada 83

8.a
Ada 83 used the term "automatic storage reclamation" to refer to what is known traditionally as "garbage collection". Because of the existence of storage pools (see 13.11), we need to distinguish this from the storage reclamation that might happen upon leaving a master. Therefore, we now use the term "garbage collection" in its normal computer-science sense. This has the additional advantage of making our terminology more accessible to people outside the Ada world.



[Home] [Prev] [Next] [Index]

documentation@rational.com
Copyright © 1993-1998, Rational Software Corporation.   All rights reserved.