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

alloc_type.hpp defines several type-safe data structures

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





1     COMMENT (*)
2     BLANK (-)
3     *
4     *
5     *
6     *
7     *
8     *
9     -
10    *
11    -
12    Header guard
13    Header guard
14    -
15    Include allocation function header
16    -
17    *
18    *
19    *
20    *
21    *
22    *
23    *
24    *
25    *
26    Set up a class template with type and length parameters
27    BLOCK START - SmallStackSafeStackAlloc is a struct (public class)
28    If we're not using a NDS/Novell architecture (likely)
29    *
30    Declare the data array with local scope (on the stack)
31    Otherwise, we're using NDS and the stack is too small, so...
32    *
33    Declare a data pointer
34    *
35    Declare a size variable for length
36    -
37    *
38    Class constructor initializes data with MallocT and given length
39    -
40    *
41    Define destructor 
42    BLOCK START - SmallStackSafeStackAlloc Destructor
43    Free the allocated data pointer
44    BLOCK END - SmallStackSafeStackAlloc Destructor
45    End check for NDS
46    -
47    *
48    *
49    *
50    *
51    Overloads the dereference operator (*)
52    BLOCK START - * operator overload
53    Return the data pointer
54    BLOCK END - * operator overload
55    -
56    *
57    *
58    *
59    *
60    Overloads the member access operator (->)
61    BLOCK START - SmallStackSafeStackAlloc -> operator overload
62    Returns the data pointer
63    BLOCK END - SmallStackSafeStackAlloc -> operator overload
64    -
65    *
66    *
67    *
68    *
69    *
70    Declares EndOf
71    BLOCK START - SmallStackSafeStackAlloc::EndOf with no arguments
72    If this is not NDS (likely)
73    Return the 'endof' of the data. endof 
74    Otherwise this is NDS so..
75    Simply return a pointer to the last element of the heap array
76    End check for NDS
77    BLOCK END - SmallStackSafeStackAlloc::EndOf
78    BLOCK END - SmallStackSafeStackAlloc
79    -
80    *
81    *
82    *
83    *
84    *
85    *
86    *
87    *
88    Set up a class template a type parameter
89    BLOCK START - ReusableBuffer, manages access to a raw data pointer
90    Declare a pointer to a data buffer of the input type
91    Declare a size variable for the number of type elements
92    *
93    *
94    *
95    *
96    Constructor initialized data buffer to NULL with no item count
97    *
98    Destructor frees the data buffer
99    -
100   *
101   *
102   *
103   *
104   *
105   *
106   *
107   Defines Allocate() with one argument: the count of type elements
108   BLOCK START - ReusableBuffer::Allocate, creates the buffer, freeing prior
      usage
109   If the buffer is too small for the desired use...
110   Free the previously used buffer
111   MallocT (malloc) a new buffer
112   Update the element count
113   End check for mismatched count
114   Return a pointer to the buffer
115   BLOCK END - ReusableBuffer::Allocate
116   -
117   *
118   *
119   *
120   *
121   *
122   *
123   *
124   Defines ZeroAllocate with one argument: the number of elements
125   BLOCK START - ReusableBuffer::ZeroAllocate, returns a calloc'd buffer
126   If the current buffer isn't large enough...
127   Free the old buffer
128   calloc a new buffer with the number of elements (count * sizeof)
129   Update the count
130   Otherwise the buffer is already large enough so...
131   Set the desired memory range to zero
132   End check for buffer size check
133   Return a pointer to the buffer
134   BLOCK END - ReusableBuffer::ZeroAllocate
135   -
136   *
137   *
138   *
139   *
140   Defines ReusableBuffer::GetBuffer
141   BLOCK START - ReusableBuffer::GetBuffer
142   Return the pointer to the buffer
143   BLOCK END - ReusableBuffer::GetBuffer
144   BLOCK END - ReusableBuffer
145   -
146   *
147   *
148   *
149   *
150   Defines ZeroedMemoryAllocator
151   BLOCK START - ZeroedMemoryAllocator, type-safe base class for allocating
      zeroed memory.
152   Begin the class public members (which is everything)
153   Empty constructor
154   Virtual destructor (may be overloaded by concrete class)
155   -
156   *
157   *
158   *
159   *
160   *
161   Overload ZeroedMemoryAllocator 'new' operator to use type-specific calloc
162   -
163   *
164   *
165   *
166   *
167   *
168   Overload ZeroedMemoryAllocator 'new[]' operator to use type-specific calloc
169   -
170   *
171   *
172   *
173   *
174   Overload ZeroedMemoryAllocator 'delete' to free itself
175   -
176   *
177   *
178   *
179   *
180   Overload ZeroedMemoryAllocator 'delete[]' to free itself
181   BLOCK END - ZeroedMemoryAllocator
182   -
183   *
184   *
185   *
186   *
187   Set up a class template with a type parameter
188   Define AutoFreePtr
189   BLOCK START - AutoFreePtr, a smart pointer implementation
190   Declare the underlying object pointer to manage
191   -
192   Begins the public member section (everything)
193   Defines a constructor with an argument taking an existing pointer
194   Defines a destructor to free the managed pointer
195   *
196   *
197   *
198   *
199   *
200   Defines AutoFreePtr::Assign with one argument: a pointer
201   BLOCK START - AutoFreePtr::Assign, assigns a new pointer to manage
202   Frees whatever might be at the given pointer
203   Reassigns the pointer under management
204   BLOCK END AutoFreePtr::Assign
205   -
206   *
207   Overloads AutoFreePtr -> operator to return the managed pointer
208   *
209   Overloads AutoFreePtr -> operator to return the managed pointer as const
210   -
211   *
212   Overloads AutoFreePtr dereference operator to return the pointer
213   *
214   Overloads AutoFreePtr deference operatoor to return the pointer as const
215   BLOCK END - AutoFreePtr
216   -
217   Header guard end