libjava/classpath/tools/gnu/classpath/tools/gjdoc/TemporaryStore.java

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