Decoded: OpenTTD (2003) v1.8 (2018)
Source file: pool_type.hpp
Line-by-line code walkthrough by MaiZure

pool_type.hpp defines memory pool classes and methods

Original code:
https://github.com/MaiZure/OpenTTD-1.8/blob/master/src/core/pool_type.hpp





1     COMMENT (*)
2     BLANK (-)
3     *
4     *
5     *
6     *
7     *
8     *
9     -
10    *
11    -
12    Header guard
13    Header guard
14    -
15    Includes the OpenTTD SmallVector header
16    Includes the OpenTTD enum container header
17    -
18    *
19    Defines enumerator for PoolType with 6 options using 6 bits
20    No bits means no pool
21    First beat means normal pool
22    Second bit means network client pool
23    Third bit means network server pool
24    Fourth bit means long-term data across many games
25    All bits means all pool types
26    End of PoolType enum
27    Initializes PoolType enum bitwise operators
28    *
29    *
30    *
31    *
32    BLOCK START - PoolBase, parent class of all memory pools
33    Declares enum for pool type
34    *
35    *
36    *
37    *
38    *
39    Defines PoolBase::GetPools()
40    BLOCK START - PoolBase::GetPools, Gets a pointer to the vector of all
      memory pools
41    If this is the first memory pool, then create the pool vector
42    Return the pointer -- either the one we created or one that already existed
43    BLOCK END - PoolBase::GetPools
44    -
45    Forward declaration of PoolBase::Clean (defined in pool_func.cpp)
46    -
47    *
48    *
49    *
50    *
51    Defines a PoolBase parameterized constructor using an input type
52    BLOCK START - PoolBase constructor
53    Adds the object to the global pool vector
54    BLOCK END - PoolBase constructor
55    -
56    Forward declares a virtual destructor
57    -
58    *
59    *
60    *
61    Pure virtual method to clean a memory pool. Must be implemented in a derived
      class
62    -
63    Start of the private section
64    *
65    *
66    *
67    *
68    Defines a simple copy constructor
69    BLOCK END - PoolBase class
70    -
71    *
72    *
73    *
74    *
75    *
76    *
77    *
78    *
79    *
80    *
81    *
82    Sets up a class template of 7 parameters, with the first four being mandatory:
      Item type, index type, the increment size, and the max size.
83    Define Pool, which inherits from PoolBase
84    *
85    Check that Tmax_size is countable with Tindex
86    -
87    Give max size a static storage location (globally reachable)
88    -
89    Declare a pool name string pointer
90    -
91    Declare a size field
92    Declare an index for the first free pool element
93    Declare an index for the first unused (all higher == free)
94    Declares a counter for number of items in the pool
95    If we're checking for assertions
96    Declare a counter for the items to check
97    End check for assertions
98    Declare a flag for pool cleanup in progress
99    -
100   Declare a pointer to the data items (items are pointers too)
101   -
102   Declare a parameterized constructor taking the name of the pool
103   Declare a virtual function for cleaning the pool. Defined by the eventual
      class template instantiation
104   -
105   *
106   *
107   *
108   *
109   *
110   *
111   Defines Pool::Get with one argument: the index to get
112   BLOCK START - Pool::Get, returns the pool item at the index
113   Check that this index is within the used portion of the Pool
114   Return the item at the index
115   BLOCK END - Pool::Get
116   -
117   *
118   *
119   *
120   *
121   *
122   Defines Pool::IsValidID with one argument: the index to check
123   BLOCK START - Pool::IsValidID
124   Returns true if the index is within the used range and isn't NULL
125   BLOCK END - Pool::IsValidID
126   -
127   *
128   *
129   *
130   *
131   *
132   Defines Pool::CanAllocate with one argument, the number of items
133   BLOCK START - Pool::CanAllocate
134   Checks if the number of items fits within the max size
135   If we're verifying Pool state
136   Update the checked value
137   End check for pool verification
138   Return the result of the allocation check limit
139   BLOCK END - Pool::CanAllocate
140   -
141   *
142   *
143   *
144   *
145   Sets up a nested class template with one argument, the type of pool.
146   BLOCK START - Pool::PoolItem class
147   Declare an index for the pool item
148   *
149   *
150   *
151   *
152   *
153   *
154   *
155   Defines an overloaded new operator with one argument
156   BLOCK START - new operator overload for Pool::PoolItem
157   Return a pointer to the allocated item
158   BLOCK END - new operator overload for Pool::PoolItem
159   -
160   *
161   *
162   *
163   *
164   *
165   Defines an overloaded delete operator for Pool::PoolItem
166   BLOCK START - delete operator overload for Pool::PoolItem
167   If the item pointer is NULL, there's nothing to do
168   Get the item at the pointer
169   Verify the item exists in the pool
170   Free the item from the pool
171   BLOCK END - delete operator overload for Pool::PoolItem
172   -
173   *
174   *
175   *
176   *
177   *
178   *
179   *
180   *
181   Defines an overloaded new operator with two arguments: size and index
182   BLOCK START - new operator overload for Pool::PoolItem
183   Returns a pointer to the newly allocated item
184   BLOCK END - new operator overload for Pool::PoolItem
185   -
186   *
187   *
188   *
189   *
190   *
191   *
192   *
193   *
194   Defines an overloaded new operator with two arguments: size and void pointer
195   BLOCK START - new operator overload for Pool::PoolItem
196   Loop from the first index to the last one used
197   *
198   *
199   *
200   *
201   *
202   *
203   Check that the it's true that the input pointer has been assigned
204   Repeat loop for all indices
205   Return the pointer
206   BLOCK END - new operator overload for Pool::PoolItem
207   -
208   -
209   *
210   -
211   *
212   *
213   *
214   *
215   *
216   Defines Pool::PoolItem::CanAllocateItem with 1 argument, number of items
217   BLOCK START - Pool::PoolItem::CanAllocateItem, verifies possible allocation
218   Returns true or false based on the Pool result
219   BLOCK END - Pool::PoolItem::CanAllocateItem
220   -
221   *
222   *
223   *
224   *
225   Defines Pool::PoolItem::CleaningPool with no arguments
226   BLOCK START - Pool::PoolItem::CleaningPool
227   Returns true or false based on the Pool status flag
228   BLOCK END -- Pool::PoolItem::CleaningPool
229   -
230   *
231   *
232   *
233   *
234   *
235   Defines Pool::PoolItem::IsValidID with 1 argument, the index to check
236   BLOCK START - Pool::PoolItem::IsValidID
237   Returns true or false based on the pool index check
238   BLOCK END - Pool::PoolItem::IsValidID
239   -
240   *
241   *
242   *
243   *
244   *
245   *
246   Defines Pool::PoolItem::Get with 1 argument, the index to get
247   BLOCK START - Pool::PoolItem::Get
248   Returns a pointer to the item at the index
249   BLOCK END - Pool::PoolItem::Get
250   -
251   *
252   *
253   *
254   *
255   *
256   *
257   Defines Pool::PoolItem::GetIfValid with 1 argument, the index to get
258   BLOCK START - Pool::PoolItem::GetIfValid
259   Returns a pointer to the item if it's valid
260   BLOCK END - Pool::PoolItem::GetIfValid
261   -
262   *
263   *
264   *
265   *
266   *
267   Defines Pool::PoolItem::GetPoolSize with no arguments
268   BLOCK START - Pool::PoolItem::GetPoolSize
269   Returns the first_unused pool field (the highest allocated index)
270   BLOCK END - Pool::PoolItem::GetPoolSize
271   -
272   *
273   *
274   *
275   *
276   Defines Pool::PoolItem::GetNumItems with no arguments
277   BLOCK START - Pool::PoolItem::GetNumItems
278   Returns the pool item count
279   BLOCK END - Pool::PoolItem::GetNumItems
280   -
281   *
282   *
283   *
284   *
285   *
286   *
287   *
288   Forward declares a PostDestructor option with an index argument
289   BLOCK END - Pool::PoolItem class
290   -
291   Start of Pool private section
292   Define a constant to signal when a pool is full (max uint)
293   *
294   *
295   *
296   *
297   *
298   BLOCK START - Pool::AllocCache for item reuse
299   *
300   Declare a pointer to the next in the list
301   BLOCK END - Pool::AllocCache
302   -
303   *
304   Declares a pointer to the allocation cache
305   -
306   Declares AllocateItem defined in pool_func.hpp
307   Declares ResizeFor defined in pool_func.hpp
308   Declares FindFirstFree defined in pool_func.hpp
309   -
310   Declares GetNew defined in pool_func.hpp
311   Declares GetNew defined in pool_func.hpp
312   -
313   Declares FreeItem defined in pool_func.hpp
314   BLOCK END - Pool
315   -
316   Defines FOR_ALL_ITEMS_FROM macro to iterator over all items in a given
      memory pool. Needs local scope
317   Begin the loop
318   If the type matches, perform a function specified after the macro
319   -
320   Defines FOR_ALL_ITEMS macro in terms of the previous macro. Needs to be
      local scope thus a macro
321   -
322   Header guard end