1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>AARM95 - Pragma Controlled</TITLE>
<META NAME="Author" CONTENT="JTC1/SC22/WG9/ARG, by Randall Brukardt, ARG Editor">
<META NAME="GENERATOR" CONTENT="Arm_Form.Exe, Ada Reference Manual generator">
<STYLE type="text/css">
DIV.paranum {position: absolute; font-family: Arial, Helvetica, sans-serif; left: 0.5 em; top: auto}
TT {font-family: "Courier New", monospace}
DT {display: compact}
DIV.Normal {font-family: "Times New Roman", Times, serif; margin-bottom: 0.6em}
DIV.Wide {font-family: "Times New Roman", Times, serif; margin-top: 0.6em; margin-bottom: 0.6em}
DIV.Annotations {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-bottom: 0.6em}
DIV.WideAnnotations {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-top: 0.6em; margin-bottom: 0.6em}
DIV.Index {font-family: "Times New Roman", Times, serif}
DIV.SyntaxSummary {font-family: "Times New Roman", Times, serif; margin-left: 2.0em; margin-bottom: 0.4em}
DIV.Notes {font-family: "Times New Roman", Times, serif; margin-left: 2.0em; margin-bottom: 0.6em}
DIV.NotesHeader {font-family: "Times New Roman", Times, serif; margin-left: 2.0em}
DIV.SyntaxIndented {font-family: "Times New Roman", Times, serif; margin-left: 2.0em; margin-bottom: 0.4em}
DIV.Indented {font-family: "Times New Roman", Times, serif; margin-left: 6.0em; margin-bottom: 0.6em}
DIV.CodeIndented {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-bottom: 0.6em}
DIV.SmallIndented {font-family: "Times New Roman", Times, serif; margin-left: 10.0em; margin-bottom: 0.6em}
DIV.SmallCodeIndented {font-family: "Times New Roman", Times, serif; margin-left: 8.0em; margin-bottom: 0.6em}
DIV.Examples {font-family: "Courier New", monospace; margin-left: 2.0em; margin-bottom: 0.6em}
DIV.SmallExamples {font-family: "Courier New", monospace; font-size: 80%; margin-left: 7.5em; margin-bottom: 0.6em}
DIV.IndentedExamples {font-family: "Courier New", monospace; margin-left: 8.0em; margin-bottom: 0.6em}
DIV.SmallIndentedExamples {font-family: "Courier New", monospace; font-size: 80%; margin-left: 15.0em; margin-bottom: 0.6em}
UL.Bulleted {font-family: "Times New Roman", Times, serif; margin-left: 2.0em; margin-right: 2.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.SmallBulleted {font-family: "Times New Roman", Times, serif; margin-left: 6.0em; margin-right: 6.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.NestedBulleted {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-right: 4.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.SmallNestedBulleted {font-family: "Times New Roman", Times, serif; margin-left: 8.0em; margin-right: 8.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.IndentedBulleted {font-family: "Times New Roman", Times, serif; margin-left: 8.0em; margin-right: 8.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.CodeIndentedBulleted {font-family: "Times New Roman", Times, serif; margin-left: 6.0em; margin-right: 6.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.CodeIndentedNestedBulleted {font-family: "Times New Roman", Times, serif; margin-left: 8.0em; margin-right: 8.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.SyntaxIndentedBulleted {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-right: 4.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.NotesBulleted {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-right: 4.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.NotesNestedBulleted {font-family: "Times New Roman", Times, serif; margin-left: 6.0em; margin-right: 6.0em; margin-top: 0em; margin-bottom: 0.5em}
DL.Hanging {font-family: "Times New Roman", Times, serif; margin-top: 0em; margin-bottom: 0.6em}
DD.Hanging {margin-left: 6.0em}
DL.IndentedHanging {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-top: 0em; margin-bottom: 0.6em}
DD.IndentedHanging {margin-left: 2.0em}
DL.HangingInBulleted {font-family: "Times New Roman", Times, serif; margin-left: 2.0em; margin-right: 2.0em; margin-top: 0em; margin-bottom: 0.5em}
DD.HangingInBulleted {margin-left: 4.0em}
DL.SmallHanging {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-top: 0em; margin-bottom: 0.6em}
DD.SmallHanging {margin-left: 7.5em}
DL.SmallIndentedHanging {font-family: "Times New Roman", Times, serif; margin-left: 8.0em; margin-top: 0em; margin-bottom: 0.6em}
DD.SmallIndentedHanging {margin-left: 2.0em}
DL.SmallHangingInBulleted {font-family: "Times New Roman", Times, serif; margin-left: 6.0em; margin-right: 6.0em; margin-top: 0em; margin-bottom: 0.5em}
DD.SmallHangingInBulleted {margin-left: 5.0em}
DL.Enumerated {font-family: "Times New Roman", Times, serif; margin-right: 0.0em; margin-top: 0em; margin-bottom: 0.5em}
DD.Enumerated {margin-left: 2.0em}
DL.SmallEnumerated {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-right: 4.0em; margin-top: 0em; margin-bottom: 0.5em}
DD.SmallEnumerated {margin-left: 2.5em}
DL.NestedEnumerated {font-family: "Times New Roman", Times, serif; margin-left: 2.0em; margin-right: 2.0em; margin-top: 0em; margin-bottom: 0.5em}
DL.SmallNestedEnumerated {font-family: "Times New Roman", Times, serif; margin-left: 6.0em; margin-right: 6.0em; margin-top: 0em; margin-bottom: 0.5em}
</STYLE>
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#FFFFF0" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
<P><A HREF="AA-TOC.html">Contents</A> <A HREF="AA-0-29.html">Index</A> <A HREF="AA-13-11-2.html">Previous</A> <A HREF="AA-13-12.html">Next</A></P>
<HR>
<H1> 13.11.3 Pragma Controlled</H1>
<DIV Class="Paranum"><FONT SIZE=-2>1</FONT></DIV>
<DIV Class="Normal"> [Pragma Controlled is used to prevent any automatic
reclamation of storage (garbage collection) for the objects created by
<FONT FACE="Arial, Helvetica">allocator</FONT>s of a given access type.]
</DIV>
<H4 ALIGN=CENTER>Syntax</H4>
<DIV Class="Paranum"><FONT SIZE=-2>2</FONT></DIV>
<DIV Class="SyntaxIndented" Style="margin-bottom: 0.2em">The form of
a <FONT FACE="Arial, Helvetica">pragma</FONT> Controlled is as follows:
</DIV>
<DIV Class="Paranum"><FONT SIZE=-2>3</FONT></DIV>
<DIV Class="SyntaxIndented"> <B>pragma</B> <A NAME="I4684"></A>Controlled(<I>first_subtype_</I><A NAME="I4685"></A><FONT FACE="Arial, Helvetica">local_name</FONT>);
</DIV>
<DIV Class="Paranum"><FONT SIZE=-2>3.a</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Discussion: </B>Not to be confused
with type Finalization.Controlled. </FONT></DIV>
<H4 ALIGN=CENTER>Legality Rules</H4>
<DIV Class="Paranum"><FONT SIZE=-2>4</FONT></DIV>
<DIV Class="Normal"> The <I>first_subtype_</I><FONT FACE="Arial, Helvetica">local_name</FONT>
of a <FONT FACE="Arial, Helvetica">pragma</FONT> Controlled shall denote
a non-derived access subtype. </DIV>
<H4 ALIGN=CENTER>Static Semantics</H4>
<DIV Class="Paranum"><FONT SIZE=-2>5</FONT></DIV>
<DIV Class="Normal"> <A NAME="I4686"></A><A NAME="I4687"></A>A <FONT FACE="Arial, Helvetica">pragma</FONT>
Controlled is a representation pragma <A NAME="I4688"></A><A NAME="I4689"></A>that
specifies the <I>controlled</I> aspect of representation.</DIV>
<DIV Class="Paranum"><FONT SIZE=-2>6</FONT></DIV>
<DIV Class="Normal"> <A NAME="I4690"></A><I>Garbage collection</I>
is a process that automatically reclaims storage, or moves objects to
a different address, while the objects still exist. </DIV>
<DIV Class="Paranum"><FONT SIZE=-2>6.a</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Ramification: </B>Storage reclamation
upon leaving a master is not considered garbage collection.</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>6.b</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1>Note that garbage collection includes
compaction of a pool (``moved to a different Address''), even if storage
reclamation is not done. </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>6.c</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Reason: </B>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 <FONT FACE="Arial, Helvetica">pragma</FONT>
Controlled should turn off both flavors of garbage collection. </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>6.d</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Implementation Note: </B>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 <A HREF="AA-7-6.html">7.6</A>), then it should
provide a means for deferring garbage collection of those controlled
objects. </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>6.e</FONT></DIV>
<DIV Class="Annotations" Style="margin-bottom: 0.4em"><FONT SIZE=-1><B>Reason:
</B>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: </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>6.f</FONT></DIV>
<DIV Class="SmallExamples"><TT><B>with</B> Ada.Finalization;<BR>
<B>package</B> P <B>is</B></TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>6.g</FONT></DIV>
<DIV Class="SmallExamples"><TT> <B>type</B> My_Controlled <B>is</B><BR>
<B>new</B> Ada.Finalization.Limited_Controlled <B>with</B> <B>private</B>;<BR>
<B>procedure</B> Finalize(Object : <B>in</B> <B>out</B> My_Controlled);<BR>
<B>type</B> My_Controlled_Access <B>is</B> <B>access</B> My_Controlled;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>6.h</FONT></DIV>
<DIV Class="SmallExamples"><TT> <B>procedure</B> Non_Reentrant;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>6.i</FONT></DIV>
<DIV Class="SmallExamples"><TT><B>private</B><BR>
...<BR>
<B>end</B> P;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>6.j</FONT></DIV>
<DIV Class="SmallExamples"><TT><B>package</B> <B>body</B> P <B>is</B><BR>
X : Integer := 0;<BR>
A : <B>array</B>(Integer <B>range</B> 1..10) <B>of</B> Integer;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>6.k</FONT></DIV>
<DIV Class="SmallExamples"><TT> <B>procedure</B> Non_Reentrant <B>is</B><BR>
<B>begin</B><BR>
X := X + 1;<BR>
--<I> If the system decides to do a garbage collection here,</I><BR>
--<I> then we're in trouble, because it will call Finalize on</I><BR>
--<I> the collected objects; we essentially have two threads</I><BR>
--<I> of control erroneously accessing shared variables.</I><BR>
--<I> The garbage collector behaves like a separate thread</I><BR>
--<I> of control, even though the user hasn't declared</I><BR>
--<I> any tasks.</I><BR>
A(X) := ...;<BR>
<B>end</B> Non_Reentrant;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>6.l</FONT></DIV>
<DIV Class="SmallExamples"><TT> <B>procedure</B> Finalize(Object : <B>in</B> <B>out</B> My_Controlled) <B>is</B><BR>
<B>begin</B><BR>
Non_Reentrant;<BR>
<B>end</B> Finalize;<BR>
<B>end</B> P;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>6.m</FONT></DIV>
<DIV Class="SmallExamples"><TT><B>with</B> P; <B>use</B> P;<BR>
<B>procedure</B> Main <B>is</B><BR>
<B>begin</B><BR>
... <B>new</B> My_Controlled ... --<I> allocate some objects</I><BR>
... <I> forget the pointers to some of them, so they become garbage</I><BR>
Non_Reentrant;<BR>
<B>end</B> Main;<BR>
</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>6.n</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1>It is the user's responsibility
to protect against this sort of thing, and the implementation's responsibility
to provide the necessary operations.</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>6.o</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1>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. </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>7</FONT></DIV>
<DIV Class="Normal"> If a <FONT FACE="Arial, Helvetica">pragma</FONT>
Controlled is specified for an access type with a standard storage pool,
then garbage collection is not performed for objects in that pool. </DIV>
<DIV Class="Paranum"><FONT SIZE=-2>7.a</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Ramification: </B>If Controlled
is not specified, the implementation may, but need not, perform garbage
collection. If Storage_Pool is specified, then a <FONT FACE="Arial, Helvetica">pragma</FONT>
Controlled for that type is ignored. </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>7.b</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Reason: </B>Controlled means
that implementation-provided garbage collection is turned off; if the
Storage_Pool is specified, the pool controls whether garbage collection
is done. </FONT></DIV>
<H4 ALIGN=CENTER>Implementation Permissions</H4>
<DIV Class="Paranum"><FONT SIZE=-2>8</FONT></DIV>
<DIV Class="Normal"> An implementation need not support garbage collection,
in which case, a pragma Controlled has no effect. </DIV>
<H4 ALIGN=CENTER>Wording Changes from Ada 83</H4>
<DIV Class="Paranum"><FONT SIZE=-2>8.a</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1>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 <A HREF="AA-13-11.html">13.11</A>),
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.
</FONT></DIV>
<HR>
<P><A HREF="AA-TOC.html">Contents</A> <A HREF="AA-0-29.html">Index</A> <A HREF="AA-13-11-2.html">Previous</A> <A HREF="AA-13-12.html">Next</A> <A HREF="AA-TTL.html">Legal</A></P>
</BODY>
</HTML>
|
