1 |
779 |
jeremybenn |
/* gnu.classpath.tools.gjdoc.TemporaryStore
|
2 |
|
|
Copyright (C) 2001 Free Software Foundation, Inc.
|
3 |
|
|
|
4 |
|
|
This file is part of GNU Classpath.
|
5 |
|
|
|
6 |
|
|
GNU Classpath is free software; you can redistribute it and/or modify
|
7 |
|
|
it under the terms of the GNU General Public License as published by
|
8 |
|
|
the Free Software Foundation; either version 2, or (at your option)
|
9 |
|
|
any later version.
|
10 |
|
|
|
11 |
|
|
GNU Classpath is distributed in the hope that it will be useful, but
|
12 |
|
|
WITHOUT ANY WARRANTY; without even the implied warranty of
|
13 |
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
14 |
|
|
General Public License for more details.
|
15 |
|
|
|
16 |
|
|
You should have received a copy of the GNU General Public License
|
17 |
|
|
along with GNU Classpath; see the file COPYING. If not, write to the
|
18 |
|
|
Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
|
19 |
|
|
02111-1307 USA.
|
20 |
|
|
|
21 |
|
|
Linking this library statically or dynamically with other modules is
|
22 |
|
|
making a combined work based on this library. Thus, the terms and
|
23 |
|
|
conditions of the GNU General Public License cover the whole
|
24 |
|
|
combination.
|
25 |
|
|
|
26 |
|
|
As a special exception, the copyright holders of this library give you
|
27 |
|
|
permission to link this library with independent modules to produce an
|
28 |
|
|
executable, regardless of the license terms of these independent
|
29 |
|
|
modules, and to copy and distribute the resulting executable under
|
30 |
|
|
terms of your choice, provided that you also meet, for each linked
|
31 |
|
|
independent module, the terms and conditions of the license of that
|
32 |
|
|
module. An independent module is a module which is not derived from
|
33 |
|
|
or based on this library. If you modify this library, you may extend
|
34 |
|
|
this exception to your version of the library, but you are not
|
35 |
|
|
obligated to do so. If you do not wish to do so, delete this
|
36 |
|
|
exception statement from your version. */
|
37 |
|
|
|
38 |
|
|
package gnu.classpath.tools.gjdoc;
|
39 |
|
|
|
40 |
|
|
/**
|
41 |
|
|
* Useful for passing big objects that are no longer needed by the
|
42 |
|
|
* calling method, reducing memory usage. <p/>
|
43 |
|
|
*
|
44 |
|
|
* Consider the following problem:
|
45 |
|
|
* <pre>
|
46 |
|
|
* public class A {
|
47 |
|
|
* public static void foo() {
|
48 |
|
|
* long[] hugeArray = new long[1000000]; // takes around 8 MB
|
49 |
|
|
* // ... fill hugeArray with some information ...
|
50 |
|
|
* bar(hugeArray);
|
51 |
|
|
* // ... hugeArray is no more required at this point
|
52 |
|
|
* }
|
53 |
|
|
* public static void bar(long[] arr) {
|
54 |
|
|
* // ... process contents of arr ...
|
55 |
|
|
* arr = null;
|
56 |
|
|
* System.gc(); // NOTE: will not collect arr!
|
57 |
|
|
* // ... do something memory-intensive where arr is not needed
|
58 |
|
|
* }
|
59 |
|
|
* }
|
60 |
|
|
* </pre>
|
61 |
|
|
*
|
62 |
|
|
* In method <code>bar()</code>, the array cannot be garbage
|
63 |
|
|
* collected because the local variable <code>hugeArray</code> in
|
64 |
|
|
* method <code>foo()</code> still holds a reference to the array.
|
65 |
|
|
* <p/>
|
66 |
|
|
*
|
67 |
|
|
* When calling <code>bar(new long[1000000]);</code> in
|
68 |
|
|
* <code>arr</code> the array <i>can</i> be collected in
|
69 |
|
|
* <code>bar()</code>, but that way it can't be initialized in
|
70 |
|
|
* <code>foo()</code>. A local variable is needed for
|
71 |
|
|
* initialization, but the variable can't be cleared before it is
|
72 |
|
|
* passed to <code>bar()</code>! <p/>
|
73 |
|
|
*
|
74 |
|
|
* <code>TemporaryStore</code> is the solution for this
|
75 |
|
|
* dilemma. The modified method <code>foo()</code> which uses a
|
76 |
|
|
* <code>TemporaryStore</code> object would look like this:
|
77 |
|
|
*
|
78 |
|
|
* <pre>
|
79 |
|
|
* public static void foo() {
|
80 |
|
|
* long[] hugeArray = new long[1000000]; // takes around 7 MB
|
81 |
|
|
* // ... fill hugeArray with some very important information ...
|
82 |
|
|
* TemporaryStore tstore = new TemporaryStore(hugeArray);
|
83 |
|
|
* hugeArray = null;
|
84 |
|
|
* bar((long[])tstore.getAndClear());
|
85 |
|
|
* }
|
86 |
|
|
* </pre>
|
87 |
|
|
*
|
88 |
|
|
* When control flow is transferred to <code>bar()</code>,
|
89 |
|
|
* <code>foo()</code> will hold no more references to the array
|
90 |
|
|
* and so it can be garbage collected in <code>bar()</code>.
|
91 |
|
|
*
|
92 |
|
|
*/
|
93 |
|
|
public class TemporaryStore {
|
94 |
|
|
|
95 |
|
|
private Object storedObject;
|
96 |
|
|
|
97 |
|
|
/**
|
98 |
|
|
* Temporarily store the given object for passing it to a
|
99 |
|
|
* different method. <p/>
|
100 |
|
|
*
|
101 |
|
|
* The method constructing a new TemporaryStore object should
|
102 |
|
|
* clear all other references to the stored object, so that
|
103 |
|
|
* this TemporaryStore is the only object referencing it.
|
104 |
|
|
*
|
105 |
|
|
* @param storedObject the object to store temporarily
|
106 |
|
|
*
|
107 |
|
|
*/
|
108 |
|
|
public TemporaryStore(Object storedObject) {
|
109 |
|
|
this.storedObject = storedObject;
|
110 |
|
|
}
|
111 |
|
|
|
112 |
|
|
/**
|
113 |
|
|
* Return the stored object after clearing the reference to it.
|
114 |
|
|
* <p/>
|
115 |
|
|
*
|
116 |
|
|
* When the user of this class followed the recommendations in
|
117 |
|
|
* the documentation of @link{TemporaryStore(Object)}, the
|
118 |
|
|
* returned reference will be the only reference to the stored
|
119 |
|
|
* object after this method returns. If the returned reference
|
120 |
|
|
* is passed in a method call, the called method will hold the
|
121 |
|
|
* only reference to the stored object and can release it by
|
122 |
|
|
* nulling the corresponding parameter.
|
123 |
|
|
*
|
124 |
|
|
* @return the object which was passed to the constructor.
|
125 |
|
|
*
|
126 |
|
|
*/
|
127 |
|
|
public Object getAndClear() {
|
128 |
|
|
Object rc = this.storedObject;
|
129 |
|
|
this.storedObject = null;
|
130 |
|
|
return rc;
|
131 |
|
|
}
|
132 |
|
|
}
|