casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
PoolStack.h
Go to the documentation of this file.
00001 //# PoolStack.h: A parameterized stack of re-usable objects
00002 //# Copyright (C) 2001,2002,2004
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: PoolStack.h 21051 2011-04-20 11:46:29Z gervandiepen $
00027 
00028 #ifndef CASA_POOLSTACK_H
00029 #define CASA_POOLSTACK_H
00030 
00031 //# Includes
00032 #include <casa/aips.h>
00033 #include <casa/Containers/Block.h>
00034 
00035 namespace casa { //# NAMESPACE CASA - BEGIN
00036 
00037 //# Forward declarations
00038 
00039 // <summary>
00040 // A parameterized stack of re-usable objects
00041 // </summary>
00042 //
00043 // <use visibility=export>
00044 //
00045 // <reviewed reviewer="Ger van Diepen" date="2001/07/03" tests="tPoolStack.cc" demos="">
00046 // </reviewed>
00047 //
00048 // <prerequisite>
00049 // <li>
00050 // </prerequisite>
00051 //
00052 // <synopsis>
00053 // A PoolStack contains a set of pre-allocated Objects of the type
00054 // <src>T</src>, with a parameter <src>Key</src> (e.g. an object could be
00055 // a <src>Vector</src> of <src>T Double</src> with an <src>uInt Key</src>).
00056 // The stack is a very simple stack, without the
00057 // linking/unlinking of a normal Stack implementation.
00058 // This lightweight implementation was especially designed for use
00059 // with the <linkto class=ObjectPool>ObjectPool</linkto>
00060 // class, but can be used independently.
00061 //
00062 // Objects can be obtained with the <src>get()</src> method, and
00063 // returned for re-use with <src>release()</src>.
00064 //
00065 // Objects are not initialised when popped. The user should never delete the
00066 // object returned by get; but return it to the pool.
00067 //
00068 // PoolStack is not thread-safe, but ObjectPool is.
00069 // </synopsis>
00070 //
00071 // <example>
00072 // <srcblock>
00073 //   // Create a pool of length 5 vectors
00074 //   PoolStack<Vector<Double>, uInt> pool5(5);
00075 //   // Get an element
00076 //   Vector<Double> *elem(pool5.get());
00077 //   // Use it
00078 //   (*elem)(2) = 27;
00079 //   // Release it
00080 //   pool5.release(elem);
00081 // </srcblock>
00082 // </example>
00083 //
00084 // <motivation>
00085 // To improve the speed for the auto differentiating class.
00086 // </motivation>
00087 //
00088 // <templating arg=T>
00089 //  <li> the class T must have a constructor with a Key argument
00090 // </templating>
00091 //
00092 // <templating arg=Key>
00093 //  <li> the class Key must be usable as a constructor argument for T
00094 // </templating>
00095 //
00096 // <todo asof="2001/06/07">
00097 // <li> Nothing I know of
00098 // </todo>
00099 
00100 template <class T, class Key> class PoolStack {
00101  public:
00102   //# Constants
00103   // Number of default stack entries.
00104   static const uInt NDEF=8;
00105   //# Constructors
00106   // Create the stack with the default Key
00107   PoolStack();
00108   // Create the stack for the specified key
00109   explicit PoolStack(const Key &key);
00110   // Delete the stack
00111   ~PoolStack();
00112 
00113   //# Member functions
00114   // Get a pointer to an object in the stack. The stack will be extended if
00115   // no objects left. Extension is done with the NDEF number of elements.
00116   // Different extension can be done manually with the addElements() method.
00117   T *get() { if (!top_p) addElements(NDEF); T *tmp = stack_p[--top_p];
00118   stack_p[top_p] = 0; return tmp; };
00119 
00120   // Return an object to the stack for re-use
00121   void release(T *obj) {if (obj) stack_p[top_p++] = obj; };
00122 
00123   // Add n elements
00124   void addElements(const uInt n);
00125 
00126   // Decimate the stack by getting rid of all unused elements in it
00127   void clear();
00128 
00129   // Test if stack empty
00130   Bool empty() { return top_p == 0; };
00131 
00132   // Return the key belonging to the stack
00133   const Key &key() const { return key_p; } 
00134   // return the stack extend (for debugging use and checking mainly)
00135   uInt nelements() const { return stack_p.nelements(); };
00136 
00137 private:
00138   //# Data
00139   // Current pointer to top-of-stack
00140   uInt top_p;
00141   // The stack
00142   PtrBlock<T*> stack_p;
00143   // The key belonging to this stack
00144   Key key_p;
00145 
00146   //# Constructors
00147   // Copy and assignment constructors and assignment (not implemented)
00148   // <group>
00149   PoolStack(const PoolStack<T, Key> &other);
00150   PoolStack<T, Key> &operator=(const PoolStack<T, Key> &other);
00151   // </group>
00152 
00153   //# Member functions
00154 };
00155 
00156 
00157 } //# NAMESPACE CASA - END
00158 
00159 #ifndef CASACORE_NO_AUTO_TEMPLATES
00160 #include <casa/Containers/PoolStack.tcc>
00161 #endif //# CASACORE_NO_AUTO_TEMPLATES
00162 #endif