Chombo + EB  3.0
Pool.H
Go to the documentation of this file.
1 #ifdef CH_LANG_CC
2 /*
3  * _______ __
4  * / ___/ / ___ __ _ / / ___
5  * / /__/ _ \/ _ \/ V \/ _ \/ _ \
6  * \___/_//_/\___/_/_/_/_.__/\___/
7  * Please refer to Copyright.txt, in Chombo's root directory.
8  */
9 #endif
10 
11 #ifndef _POOL_H_
12 #define _POOL_H_
13 
14 #include <cstdlib>
15 #include <list>
16 
17 #include "Vector.H"
18 #include "BaseNamespaceHeader.H"
19 
20 class Pool;
21 typedef std::list<Pool*> PoolList;
22 
23 /// Pool is a class to optimize memory allocation.
24 /**
25  Pool is a class to optimize memory allocation. It is specialized to
26  allocate fixed size chunks of memory specified by ptrSize in the
27  constructor. Its operation is analogous to malloc, not new. It
28  does not initialize the memory in any way. The constructor can
29  optionally specify an initial pool size, and memory alignment. The
30  pool size will grow as needed by calling ::new. The pool size never
31  shrinks. Memory will be reclaimed at ~Pool(). The units of poolSize
32  are number-of-ptrSize-chunks. The units of alignment are bytes.
33 
34  Pool can only be used for objects of fixed size. Typically used in
35  situations where a class or struct is being constantly constructed and
36  deleted. Objects returned by value from functions, elements in a database,
37  etc. Pool's tend to be allocated statically.
38 
39  (from Copier.cpp)
40  \code
41 
42  // static data member s_motionIemPool getting constructed
43  Pool Copier::s_motionItemPool(sizeof(MotionItem), "Copier::MotionItem");
44 
45  // note the use of a 'placement new'
46  MotionItem* item = new (s_motionItemPool.getPtr()) MotionItem(fromdi, todi, box);
47 
48  // if your object does requires it's destructor to be called.
49  item->~MotionItem();
50 
51  // then return the memory chunk to your pool
52  s_motionItemPool.returnPtr(item)
53 
54  \endcode
55 
56 Technical note
57  In the event of multi-threading Chombo, we will have to make
58  pool access serialized (locks, single thread access, etc) or implement a
59  fast lock-free version, or go back to new/delete and let the OS be clever
60  again about memory management.
61 
62 */
63 class Pool
64 {
65 public:
66  ///
67  /**
68  @param a_ptrSize Size of fixed memory allocations needed
69 
70  @param a_poolSize Size of allocations (a_ptrSize*a_poolSize) made
71  of the operating system. This controls the granularity of the
72  Pool allocations. Smaller values result in less wasted memory,
73  at the cost of more calls to the operating system for heap memory.
74 
75  @param a_name optional name for this Pool. Used in reporting memory
76  by the memory tracking system in Chombo.
77  */
78  Pool(int a_ptrSize,
79  const char* a_name = "unnamed",
80  int a_poolSize = 100,
81  int a_alignment = sizeof(int),
82  bool a_allowUnalignedAlloc = false);
83 
84  ///
85  ~Pool();
86 
87  /// request a section of memory of ptrSize_ contiguous bytes.
88  void* getPtr();
89 
90  /// return memory previous acquired with the getPtr() function.
91  void returnPtr(void* a_ptr);
92 
93  /// report how much memory this Pool is currently using.
94  /**
95  memUsage for a Pool only grows until Pool destruction. The Pool
96  object has no knowledge of what pieces of memory it has parcelled out
97  to a user, so it keeps it all available. The user is responsible for
98  not leaking Pool memory.
99  */
100  long memUsage() const;
101 
102  /**
103  undocumented function, call this at own risk. You must
104  be absolutely positive that you have returned all the
105  ptr's you've asked for, or you can have major seg faults.
106  */
107  void clear();
108 
109  // not for public consumption. used in memory tracking code.
111  char m_name_[64];
112 
113 
114 protected:
115 
116 
117 private:
118  ///
120 
121  ///
123 
124  ///
126 
127  ///
129 
130  bool m_allowUnalignedAlloc; ///< T - Allows unaligned allocations
131  ///< (> sizof(double) if it is not
132  ///< known how to allocate aligned
133  ///< memory
134  ///< F - Otherwise abort
135 
136  ///
137  void* m_next_;
138 
139  ///
140  void* getMoreMemory();
141 
142  void* getMore();
143 
144  ///
145  /// Not implemented. Compiler will not let you copy a Pool
146  Pool(const Pool& a_rhs);
147 
148  /// Not implemented. Compiler will not let you copy a Pool
149  const Pool& operator = (const Pool& a_rhs);
150 
151  static void clearAllPools();
152 
153  friend void dumpmemoryatexit();
154 };
155 
156 // Stroustrup (S. 11.5.1) says a declaration in the global scope is needed
157 void dumpmemoryatexit();
158 
159 #include "BaseNamespaceFooter.H"
160 #endif
void * getMore()
int m_ptrSize_
Definition: Pool.H:122
long memUsage() const
report how much memory this Pool is currently using.
void * m_next_
Definition: Pool.H:137
char m_name_[64]
Definition: Pool.H:111
const Pool & operator=(const Pool &a_rhs)
Not implemented. Compiler will not let you copy a Pool.
void clear()
void returnPtr(void *a_ptr)
return memory previous acquired with the getPtr() function.
Vector< char * > m_pool_
Definition: Pool.H:119
friend void dumpmemoryatexit()
static PoolList * m_poolList_
Definition: Pool.H:110
bool m_allowUnalignedAlloc
Definition: Pool.H:130
void * getPtr()
request a section of memory of ptrSize_ contiguous bytes.
int m_alignment_
Definition: Pool.H:128
int m_poolSize_
Definition: Pool.H:125
Pool is a class to optimize memory allocation.
Definition: Pool.H:63
void dumpmemoryatexit()
std::list< Pool * > PoolList
Definition: Pool.H:20
static void clearAllPools()
Pool(int a_ptrSize, const char *a_name="unnamed", int a_poolSize=100, int a_alignment=sizeof(int), bool a_allowUnalignedAlloc=false)
void * getMoreMemory()