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

pool_func.hpp defines memory pool accessor and maintenance methods

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





1     COMMENT (*)
2     BLANK (-)
3     *
4     *
5     *
6     *
7     *
8     *
9     -
10    *
11    -
12    Header guard
13    Header guard
14    -
15    Inclues the OpenTTD allocation function header
16    Inclues the OpenTTD memory function header
17    Inclues the OpenTTD memory pool type header
18    -
19    *
20    *
21    *
22    *
23    Defines a macro DEFINE_POOL_METHODS to generate better-looking method
      signatures of appropriate type
24    Sets up the signature template
25    Defines the specific class template type
26    -
27    *
28    *
29    *
30    *
31    Defines Pool::Pool constructor with an initializer list including
32    The PoolBase constructor
33    The name as input 
34    A default size of 0
35    The first element is free
36    It's also unused
37    There are no items in the new pool
38    Check if we're verifying memory pools  
39    If so, we initialize checked item count to 0
40    End check for pool checks
41    We're not currently cleaning the pool
42    There is no data yet
43    There is no cache yet
44    BLOCK START / END - NOP
45    -
46    *
47    *
48    *
49    *
50    *
51    *
52    Defines Pool::ResizeFor with one argument: an input index to size to
53    BLOCK START - Pool:ResizeFor, resizes a pool up to the input index
54    Check that the pool is smaller than the input index requested
55    Check that the request index isn't larger than the max pool size
56    -
57    Initialize a size variable to the smaller of the index or max allowable
      size
58    -
59    Call the type-safe realloc function and save the pointer
60    Zeroize the new data chunk
61    -
62    Return the updated size of the object
63    BLOCK END - Pool::ResizeFor
64    -
65    *
66    *
67    *
68    *
69    Defines Pool::FindFirstFree with no arguments
70    BLOCK START - Pool::FindFirstFree, returns a free data index
71    From the last known free index...
72    -
73    Loop through all valid indicies
74    If the index is not allocated, return it
75    End loop through indicies
76    -
77    If we haven't gone to the end of the array (we're at first unused)
78    So return it since it must be valid
79    End check for end of data
80    - (If we're here, then we at the end of the pool)
81    Check that we're at the end of the pool
82    Check that the first_unused agrees
83    -
84    Check that we have room to allocate
85    Grow the array
86    Return the now-valid index
87    End check for room to grow
88    -
89    If'we re still in this function, the memory pool is at max size
90    -
91    Return max size condition
92    BLOCK END - Pool::FindFirstFree
93    -
94    *
95    *
96    *
97    *
98    *
99    *
100   *
101   Defines Pool::AllocateItem with two arguments: a size and index
102   BLOCK START - Pool::AllocateItem, creates an item in the pool
103   Verify that the index is not in use
104   -
105   Push the unused index to the next if it isn't already further
106   Increment the memory pool object count
107   -
108   Declare a local pointer to an upcoming new object
109   If the this pool has a valid cache allocated
110   Verify the item sizes match
111   Store the currently cached item
112   Update the cache to the next item
113   If we need to zeroize new items...
114   *
115   *
116   Zeroize the new object data
117   End check for zeroed data
118   Otherwise the cache isn't in use so if we need to zeroize..
119   Allocate a new item with zeroed data
120   Finally, the cache isn't in use and we don't need zeroed objects
121   Just allocate the object with the type-safe malloc
122   End check for cache state
123   Tie the new object in to the pool data vector
124   Recast the index
125   Return the pointer to the new object
126   BLOCK END - Pool::AllocateItem
127   -
128   *
129   *
130   *
131   *
132   *
133   *
134   Defines Pool::GetNew with one argument: a size
135   BLOCK START - Pool::GetNew, allocates a new item
136   Finds the first free index
137   -
138   If we're checking the pool
139   Then the check counter needs a valid value
140   Decrement the value
141   End check for pool state
142   If no free space could be found...
143   Fail with error message
144   End check for no space
145   -
146   Increment the first index (TODO: Trace the correctness of first_free in
      fragmented pools)
147   Return the allocated item
148   BLOCK END - Pool::GetNew
149   -
150   *
151   *
152   *
153   *
154   *
155   *
156   *
157   Defines Pool::GetNew with two arguments: a size and a known index
158   BLOCK START - Pool::GetNew, allocates a new item with a given index
159   If the memory pool is already at max size...
160   Fail out with error message
161   End check for max size
162   -
163   If the memory pool needs more space for this index, resize it
164   -
165   If the given index already has a valid object
166   Fail out with error message
167   End check for index in use
168   -
169   Return the newly allocated object
170   BLOCK END - Pool::GetNew
171   -
172   *
173   *
174   *
175   *
176   *
177   *
178   Defines Pool::FreeItem with one argument: the index to free
179   BLOCK START - Pool::FreeItem, deallocates item in the pool
180   Checks that the provided index is within the pool
181   Checks that the index points to a valid item
182   If this pool is caching items...
183   Save the item we're about to delete
184   Point it to the end of the cache
185   Update the cache with the item we're about to delete
186   Otherwise we're not caching anything...
187   So just free it
188   End check for caching state
189   Clear the data array
190   Update first_free if this is now the lowest free item
191   Decrement the item counter
192   If the pool isn't currently being cleaned, then destroy the item
193   BLOCK END - Pool::FreeItem
194   -
195   *
196   Defines Pool::CleanPool with no arguments
197   BLOCK START - Pool::CleanPool, destroys all items in the pool
198   Mark the pool or cleaning in progress
199   Loop through all pool items until the first known free spot
200   Delete the items
201   End loop through all items
202   Check that the item count is zero
203   Free the data pointer
204   Zeroies all pool metadata fields
205   Point data to NULL
206   We're done cleaning, clear the flag
207   -
208   If this pool has a cache...
209   Loop through the cache list
210   Get the cache item
211   Update the cache to the next in the list
212   Free the cached item
213   Repeat loop for all cached items
214   End check for caching
215   BLOCK END - Pool::CleanPool
216   -
217   Remove the pool method definition (redefined for each pool type)
218   -
219   *
220   *
221   *
222   *
223   *
224   Defines macro to instantiate pool methods (requires local scope)
225   Defines Pooltype::GetNew() --1 arg signature
226   Defines Pooltype::GetNew() --2 arg signature
227   Defines Pooltype::FreeItem()
228   Defines Pooltype::CleanPool()
229   -
230   Header guard end