File : s-finmas.ads
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT COMPILER COMPONENTS --
4 -- --
5 -- S Y S T E M . F I N A L I Z A T I O N _ M A S T E R S --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 2011-2015, Free Software Foundation, Inc. --
10 -- --
11 -- GNAT is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 3, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. --
17 -- --
18 -- --
19 -- --
20 -- --
21 -- --
22 -- You should have received a copy of the GNU General Public License and --
23 -- a copy of the GCC Runtime Library Exception along with this program; --
24 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
25 -- <http://www.gnu.org/licenses/>. --
26 -- --
27 -- GNAT was originally developed by the GNAT team at New York University. --
28 -- Extensive contributions were provided by Ada Core Technologies Inc. --
29 -- --
30 ------------------------------------------------------------------------------
31
32 with Ada.Finalization;
33 with System.Storage_Elements;
34 with System.Storage_Pools;
35
36 pragma Compiler_Unit_Warning;
37
38 package System.Finalization_Masters is
39 pragma Preelaborate;
40
41 -- A reference to primitive Finalize_Address. The expander generates an
42 -- implementation of this procedure for each controlled and class-wide
43 -- type. Since controlled objects are simply viewed as addresses once
44 -- allocated through a master, Finalize_Address provides a backward
45 -- indirection from an address to a type-specific context.
46
47 type Finalize_Address_Ptr is access procedure (Obj : System.Address);
48
49 -- Heterogeneous collection type structure
50
51 type FM_Node is private;
52 type FM_Node_Ptr is access all FM_Node;
53 pragma No_Strict_Aliasing (FM_Node_Ptr);
54
55 -- A reference to any derivation from Root_Storage_Pool. Since this type
56 -- may not be used to allocate objects, its storage size is zero.
57
58 type Any_Storage_Pool_Ptr is
59 access System.Storage_Pools.Root_Storage_Pool'Class;
60 for Any_Storage_Pool_Ptr'Storage_Size use 0;
61
62 -- Finalization master type structure. A unique master is associated with
63 -- each access-to-controlled or access-to-class-wide type. Masters also act
64 -- as components of subpools. By default, a master contains objects of the
65 -- same designated type but it may also accomodate heterogeneous objects.
66
67 type Finalization_Master is
68 new Ada.Finalization.Limited_Controlled with private;
69
70 -- A reference to a finalization master. Since this type may not be used
71 -- to allocate objects, its storage size is zero.
72
73 type Finalization_Master_Ptr is access all Finalization_Master;
74 for Finalization_Master_Ptr'Storage_Size use 0;
75
76 procedure Attach (N : not null FM_Node_Ptr; L : not null FM_Node_Ptr);
77 -- Compiler interface, do not call from withing the run-time. Prepend a
78 -- node to a specific finalization master.
79
80 procedure Attach_Unprotected
81 (N : not null FM_Node_Ptr;
82 L : not null FM_Node_Ptr);
83 -- Prepend a node to a specific finalization master
84
85 procedure Delete_Finalize_Address_Unprotected (Obj : System.Address);
86 -- Destroy the relation pair object - Finalize_Address from the internal
87 -- hash table.
88
89 procedure Detach (N : not null FM_Node_Ptr);
90 -- Compiler interface, do not call from within the run-time. Remove a node
91 -- from an arbitrary finalization master.
92
93 procedure Detach_Unprotected (N : not null FM_Node_Ptr);
94 -- Remove a node from an arbitrary finalization master
95
96 overriding procedure Finalize (Master : in out Finalization_Master);
97 -- Lock the master to prevent allocations during finalization. Iterate over
98 -- the list of allocated controlled objects, finalizing each one by calling
99 -- its specific Finalize_Address. In the end, deallocate the dummy head.
100
101 function Finalize_Address
102 (Master : Finalization_Master) return Finalize_Address_Ptr;
103 -- Return a reference to the TSS primitive Finalize_Address associated with
104 -- a master.
105
106 function Finalize_Address_Unprotected
107 (Obj : System.Address) return Finalize_Address_Ptr;
108 -- Retrieve the Finalize_Address primitive associated with a particular
109 -- object.
110
111 function Finalization_Started (Master : Finalization_Master) return Boolean;
112 -- Return the finalization status of a master
113
114 function Header_Size return System.Storage_Elements.Storage_Count;
115 -- Return the size of type FM_Node as Storage_Count
116
117 function Is_Homogeneous (Master : Finalization_Master) return Boolean;
118 -- Return the behavior flag of a master
119
120 function Objects (Master : Finalization_Master) return FM_Node_Ptr;
121 -- Return the header of the doubly-linked list of controlled objects
122
123 procedure Print_Master (Master : Finalization_Master);
124 -- Debug routine, outputs the contents of a master
125
126 procedure Set_Finalize_Address
127 (Master : in out Finalization_Master;
128 Fin_Addr_Ptr : Finalize_Address_Ptr);
129 -- Compiler interface, do not call from within the run-time. Set the clean
130 -- up routine of a finalization master
131
132 procedure Set_Finalize_Address_Unprotected
133 (Master : in out Finalization_Master;
134 Fin_Addr_Ptr : Finalize_Address_Ptr);
135 -- Set the clean up routine of a finalization master
136
137 procedure Set_Heterogeneous_Finalize_Address_Unprotected
138 (Obj : System.Address;
139 Fin_Addr_Ptr : Finalize_Address_Ptr);
140 -- Add a relation pair object - Finalize_Address to the internal hash
141 -- table. This is done in the context of allocation on a heterogeneous
142 -- finalization master where a single master services multiple anonymous
143 -- access-to-controlled types.
144
145 procedure Set_Is_Heterogeneous (Master : in out Finalization_Master);
146 -- Mark the master as being a heterogeneous collection of objects
147
148 private
149 -- Heterogeneous collection type structure
150
151 type FM_Node is record
152 Prev : FM_Node_Ptr := null;
153 Next : FM_Node_Ptr := null;
154 end record;
155
156 -- Finalization master type structure. A unique master is associated with
157 -- each access-to-controlled or access-to-class-wide type. Masters also act
158 -- as components of subpools. By default, a master contains objects of the
159 -- same designated type but it may also accomodate heterogeneous objects.
160
161 type Finalization_Master is
162 new Ada.Finalization.Limited_Controlled with
163 record
164 Is_Homogeneous : Boolean := True;
165 -- A flag which controls the behavior of the master. A value of False
166 -- denotes a heterogeneous collection.
167
168 Base_Pool : Any_Storage_Pool_Ptr := null;
169 -- A reference to the pool which this finalization master services. This
170 -- field is used in conjunction with the build-in-place machinery.
171
172 Objects : aliased FM_Node;
173 -- A doubly linked list which contains the headers of all controlled
174 -- objects allocated in a [sub]pool.
175
176 Finalize_Address : Finalize_Address_Ptr := null;
177 -- A reference to the routine reponsible for object finalization. This
178 -- is used only when the master is in homogeneous mode.
179
180 Finalization_Started : Boolean := False;
181 -- A flag used to detect allocations which occur during the finalization
182 -- of a master. The allocations must raise Program_Error. This scenario
183 -- may arise in a multitask environment.
184 end record;
185
186 -- Since RTSfind cannot contain names of the form RE_"+", the following
187 -- routine serves as a wrapper around System.Storage_Elements."+".
188
189 function Add_Offset_To_Address
190 (Addr : System.Address;
191 Offset : System.Storage_Elements.Storage_Offset) return System.Address;
192
193 function Base_Pool
194 (Master : Finalization_Master) return Any_Storage_Pool_Ptr;
195 -- Return a reference to the underlying storage pool on which the master
196 -- operates.
197
198 overriding procedure Initialize (Master : in out Finalization_Master);
199 -- Initialize the dummy head of a finalization master
200
201 procedure Set_Base_Pool
202 (Master : in out Finalization_Master;
203 Pool_Ptr : Any_Storage_Pool_Ptr);
204 -- Set the underlying pool of a finalization master
205
206 end System.Finalization_Masters;