casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
ObjectPool.h
Go to the documentation of this file.
00001 //# ObjectPool.h: A parameterized stack of re-usable objects
00002 //# Copyright (C) 2001,2002
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id: ObjectPool.h 21067 2011-05-06 13:58:12Z gervandiepen $
00027 
00028 #ifndef CASA_OBJECTPOOL_H
00029 #define CASA_OBJECTPOOL_H
00030 
00031 //# Includes
00032 #include <casa/aips.h>
00033 #include <casa/Containers/PoolStack.h>
00034 #include <casa/Containers/SimOrdMap.h>
00035 #include <casa/OS/Mutex.h>
00036 
00037 namespace casa { //# NAMESPACE CASA - BEGIN
00038 
00039 //# Forward declarations
00040 
00041 // <summary>
00042 // A parameterized stack of re-usable objects
00043 // </summary>
00044 //
00045 // <use visibility=export>
00046 //
00047 // <reviewed reviewer="Ger van Diepen" date="2001/07/04" tests="tObjectPool.cc" demos="">
00048 // </reviewed>
00049 //
00050 // <prerequisite>
00051 // <li> <linkto class=PoolStack>PoolStack</linkto>
00052 // </prerequisite>
00053 //
00054 // <synopsis>
00055 // An ObjectPool contains a set of pre-allocated Objects of the type
00056 // <src>T</src>. A Map based on the <src>Key</src> values contains
00057 // a stack of objects for each key value.
00058 // 
00059 // As an example, a <src><Vector<Double>, uInt></src> ObjectPool contains
00060 // a <src>SimpleOrderedMap<uInt,PoolStack<Vector<Double>,uInt>* ></src>
00061 // map. Each Stack will contain a stack of <src>Vector<Double></src>
00062 // objects, with a length of the key value each.
00063 //
00064 // When an object is asked for with the <src>get</src> method, the
00065 // correct stack is found using the parameter key. If no entry in the map
00066 // exists, a new stack is created. If the relevant stack is empty, new elements
00067 // are added to the stack.
00068 // </synopsis>
00069 //
00070 // <example>
00071 // <srcblock>
00072 //   // Create a pool of vectors
00073 //   ObjectPool<Vector<Double>, uInt> pool;
00074 //   // Get a pointer to a pre-defined vector of length 5
00075 //   Vector<Double> *el5(pool.get(5));
00076 //   // and one of length 10
00077 //   Vector<Double> *el10(pool.get(10));
00078 //   ... 
00079 //   // Release the objects for re-use
00080 //   pool.release(el5, 5);
00081 //   pool.release(el10, 10); 
00082 // </srcblock>
00083 // </example>
00084 //
00085 // <motivation>
00086 // To improve the speed for the auto differentiating class.
00087 // </motivation>
00088 //
00089 // <templating arg=T>
00090 //  <li> the class T must have a constructor with a Key argument
00091 // </templating>
00092 //
00093 // <templating arg=Key>
00094 //  <li> the class Key must be sortable to be used as a key in the Map
00095 // </templating>
00096 //
00097 // <todo asof="2001/06/07">
00098 // <li> Nothing at the moment
00099 // </todo>
00100 
00101 template <class T, class Key> class ObjectPool {
00102  public:
00103   //# Constructors
00104   // Create the pool
00105   ObjectPool();
00106   // Delete the pool
00107   ~ObjectPool();
00108 
00109   //# Member functions
00110   // Get a pointer to an object in the pool with the specified parameter. The
00111   // object is detached from the stack, and has to be returned with the 
00112   // <src>release</src> method. The object should not be deleted by caller.
00113   // <group>
00114   T *get(const Key key=Key()) { return getStack(key).get(); };
00115   // </group>
00116 
00117   // Get the object stack for the given key
00118   PoolStack<T, Key> &getStack(const Key key);
00119 
00120   // Release an object obtained from the pool through <src>get</src> for
00121   // re-use.
00122   void release(T *obj, const Key key=Key());
00123 
00124   // Get the number of object stacks in the pool
00125   uInt nelements() const { return map_p.ndefined(); };
00126 
00127   // Decimate the stacks by deleting all unused objects.
00128   // <group>
00129   void clearStacks();
00130   void clearStack(const Key key=Key());
00131   // </group>
00132 
00133   // Decimate the stacks and remove any map entry that is completely unused
00134   void clear();
00135 
00136 private:
00137   //# Data
00138   // The default key and stack, and the last referenced one (for caching
00139   // purposes)
00140   // <group>
00141   Key defKey_p;
00142   PoolStack<T, Key> *defStack_p;
00143   Key cacheKey_p;
00144   PoolStack<T, Key> *cacheStack_p;
00145   Mutex mutex_p;
00146   // </group>
00147 
00148   // The pool map
00149   SimpleOrderedMap<Key, PoolStack<T, Key>* > map_p;
00150 
00151   //# Constructors
00152   // Copy and assignment constructors and assignment (not implemented)
00153   // <group>
00154   ObjectPool(const ObjectPool<T, Key> &other);
00155   ObjectPool<T, Key> &operator=(const ObjectPool<T, Key> &other);
00156   // </group>
00157 
00158   //# Member functions
00159   // Do the actual clearing of the stack (without a lock).
00160   void doClearStack(const Key key);
00161 };
00162 
00163 
00164 } //# NAMESPACE CASA - END
00165 
00166 #ifndef CASACORE_NO_AUTO_TEMPLATES
00167 #include <casa/Containers/ObjectPool.tcc>
00168 #endif //# CASACORE_NO_AUTO_TEMPLATES
00169 #endif