Decoded: Sopwith (1984) by David L. Clark
Source file: SWOBJECT.C
Beginner friendly, line-by-line code walkthrough by MaiZure

SWOBJECT.C is our low level object allocator that manages the pool created at
initialization. 

Original code:
http://davidlclark.com/page/sopwith-source-code

Original code with line numbers
http://www.maizure.org/projects/decoded-sopwith/SWOBJECT_linenum.txt


NOTE ON THE SOPWITH OBJECT ALLOCATOR
Effectively, this is just a quick and dirty linked list with a static allotment
of 100 objects. A series of global pointers reference the top of the lists and
we just move objects between free and allocated by changing the object pointers.
This is basically a stack that we can scan

objtop is the head of our allocated object list
objbot is the last object already allocated
objfree is a pointer to an unused object

Every object has a 'next' and a 'prev' pointer that we can traverse and change
if necessary

1     COMMENT
2     COMMENT
3     BLANK
4     COMMENT
5     COMMENT
6     COMMENT
7     COMMENT
8     COMMENT
9     COMMENT
10    COMMENT
11    COMMENT
12    COMMENT
13    COMMENT
14    BLANK
15    COMMENT
16    BLANK
17    COMMENT
18    COMMENT
19    COMMENT
20    COMMENT
21    COMMENT
22    COMMENT
23    COMMENT
24    Include the main game header (sw.h)
25    BLANK
26    BLANK
27    BLANK
28    Import a pointer our master list of objects from SWMAIN
29    Import the pointers to the top and bottom of the list
30    Import the pointer to the free list
31    Import pointers to the objects to be freed
32    Import pointer to the object with the highest allocation
33    BLANK
34    BLANK
35    BLANK

ALLOCATE AN OBJECT
36    Declare and define allocobj with no arguments
37    BLOCK START - allocobj, which allocates a free object from our list
38    Declare a local object pointer
39    BLANK
40    If we have no free objects..
41    Return a null pointer
42    BLANK
43    We have something free so return the first free object in the list
44    Change the free pointer to the newly found object's next object (could
      be NULL and we're out of free objects)
45    BLANK
46    Our new object from our free list has no next object
47    Its previous object should be at the tail of the allocated list (could
      be NULL if this is the first object)
48    BLANK
49    If the list tail actually exists...
50    Then it now needs to point to our new object
51    Otherwise...
52    The tail doesn't exist and this object is actually at the top
53    BLANK
54    This object has no sound...interesting thing to include in an allocator
55    Don't mark the object for drawing or deletion
56    If this object has a memory address greater than the greatest known..
57    It is now the greatest known allocated object.
58    Set the object as the bottom of the allocated list and return state
59    BLOCK END - allocobj
60    BLANK
61    BLANK
62    BLANK

DEALLOCATE AN OBJECT
63    Declare and define deallobj with one argument
64    Argument is a pointer to the object to deallocate
65    BLOCK START - deallobj, which deallocates the given object
66    Declares two local object pointers
67    BLANK
68    Point to the input object
69    If the object to be destroyed has a predecessor (it isn't the first obj)
70    Then the precessor needs to point to the destroyed object's successor,
      which could be NULL
71    Otherwise, this is the top object...
72    So the global top point needs to point to the successor (possibly NULL)
73    BLANK
74    If there is a successor...
75    Then it needs to skip the now deleted object and point to its previous.
76    Otherwise, there is no successor..
77    So the bottom of the allocated list now needs to point to the previous
78    BLANK
79    Remove the dangling reference (for when the object is reused later)
80    If another object has been deleted before...
81    That deleted object needs to point to this deleted object
82    Otherwise...
83    This object has now been deleted
84    BLANK
85    Let's do that again, just because!
86    BLANK
87    BLANK
88    BLOCK END - deallobj
89    EOF˙