casacore
ObjectPool.h
Go to the documentation of this file.
1 //# ObjectPool.h: A parameterized stack of re-usable objects
2 //# Copyright (C) 2001,2002
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef CASA_OBJECTPOOL_H
29 #define CASA_OBJECTPOOL_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/casa/Containers/PoolStack.h>
34 #include <casacore/casa/Containers/SimOrdMap.h>
35 #include <casacore/casa/OS/Mutex.h>
36 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 //# Forward declarations
40 
41 // <summary>
42 // A parameterized stack of re-usable objects
43 // </summary>
44 //
45 // <use visibility=export>
46 //
47 // <reviewed reviewer="Ger van Diepen" date="2001/07/04" tests="tObjectPool.cc" demos="">
48 // </reviewed>
49 //
50 // <prerequisite>
51 // <li> <linkto class=PoolStack>PoolStack</linkto>
52 // </prerequisite>
53 //
54 // <synopsis>
55 // An ObjectPool contains a set of pre-allocated Objects of the type
56 // <src>T</src>. A Map based on the <src>Key</src> values contains
57 // a stack of objects for each key value.
58 //
59 // As an example, a <src><Vector<Double>, uInt></src> ObjectPool contains
60 // a <src>SimpleOrderedMap<uInt,PoolStack<Vector<Double>,uInt>* ></src>
61 // map. Each Stack will contain a stack of <src>Vector<Double></src>
62 // objects, with a length of the key value each.
63 //
64 // When an object is asked for with the <src>get</src> method, the
65 // correct stack is found using the parameter key. If no entry in the map
66 // exists, a new stack is created. If the relevant stack is empty, new elements
67 // are added to the stack.
68 // </synopsis>
69 //
70 // <example>
71 // <srcblock>
72 // // Create a pool of vectors
73 // ObjectPool<Vector<Double>, uInt> pool;
74 // // Get a pointer to a pre-defined vector of length 5
75 // Vector<Double> *el5(pool.get(5));
76 // // and one of length 10
77 // Vector<Double> *el10(pool.get(10));
78 // ...
79 // // Release the objects for re-use
80 // pool.release(el5, 5);
81 // pool.release(el10, 10);
82 // </srcblock>
83 // </example>
84 //
85 // <motivation>
86 // To improve the speed for the auto differentiating class.
87 // </motivation>
88 //
89 // <templating arg=T>
90 // <li> the class T must have a constructor with a Key argument
91 // </templating>
92 //
93 // <templating arg=Key>
94 // <li> the class Key must be sortable to be used as a key in the Map
95 // </templating>
96 //
97 // <todo asof="2001/06/07">
98 // <li> Nothing at the moment
99 // </todo>
100 
101 template <class T, class Key> class ObjectPool {
102  public:
103  //# Constructors
104  // Create the pool
105  ObjectPool();
106  // Delete the pool
107  ~ObjectPool();
108 
109  //# Member functions
110  // Get a pointer to an object in the pool with the specified parameter. The
111  // object is detached from the stack, and has to be returned with the
112  // <src>release</src> method. The object should not be deleted by caller.
113  // <group>
114  T *get(const Key key=Key()) { return getStack(key).get(); };
115  // </group>
116 
117  // Get the object stack for the given key
118  PoolStack<T, Key> &getStack(const Key key);
119 
120  // Release an object obtained from the pool through <src>get</src> for
121  // re-use.
122  void release(T *obj, const Key key=Key());
123 
124  // Get the number of object stacks in the pool
125  uInt nelements() const { return map_p.ndefined(); };
126 
127  // Decimate the stacks by deleting all unused objects.
128  // <group>
129  void clearStacks();
130  void clearStack(const Key key=Key());
131  // </group>
132 
133  // Decimate the stacks and remove any map entry that is completely unused
134  void clear();
135 
136 private:
137  //# Data
138  // The default key and stack, and the last referenced one (for caching
139  // purposes)
140  // <group>
141  Key defKey_p;
146  // </group>
147 
148  // The pool map
150 
151  //# Constructors
152  // Copy and assignment constructors and assignment (not implemented)
153  // <group>
154  ObjectPool(const ObjectPool<T, Key> &other);
156  // </group>
157 
158  //# Member functions
159  // Do the actual clearing of the stack (without a lock).
160  void doClearStack(const Key key);
161 };
162 
163 
164 } //# NAMESPACE CASACORE - END
165 
166 #ifndef CASACORE_NO_AUTO_TEMPLATES
167 #include <casacore/casa/Containers/ObjectPool.tcc>
168 #endif //# CASACORE_NO_AUTO_TEMPLATES
169 #endif
void clearStacks()
Decimate the stacks by deleting all unused objects.
Key defKey_p
The default key and stack, and the last referenced one (for caching purposes)
Definition: ObjectPool.h:141
void doClearStack(const Key key)
Do the actual clearing of the stack (without a lock).
~ObjectPool()
Delete the pool.
uInt nelements() const
Get the number of object stacks in the pool.
Definition: ObjectPool.h:125
void release(T *obj, const Key key=Key())
Release an object obtained from the pool through get for re-use.
void clear()
Decimate the stacks and remove any map entry that is completely unused.
Simple map with keys ordered.
Definition: SimOrdMap.h:69
PoolStack< T, Key > * defStack_p
Definition: ObjectPool.h:142
A parameterized stack of re-usable objects.
Definition: ObjectPool.h:101
void clearStack(const Key key=Key())
PoolStack< T, Key > & getStack(const Key key)
Get the object stack for the given key.
PoolStack< T, Key > * cacheStack_p
Definition: ObjectPool.h:144
Wrapper around a pthreads mutex.
Definition: Mutex.h:49
A parameterized stack of re-usable objects.
Definition: PoolStack.h:100
ObjectPool< T, Key > & operator=(const ObjectPool< T, Key > &other)
this file contains all the compiler specific defines
Definition: mainpage.dox:28
SimpleOrderedMap< Key, PoolStack< T, Key > *> map_p
The pool map.
Definition: ObjectPool.h:149
unsigned int uInt
Definition: aipstype.h:48
ObjectPool()
Create the pool.