Programs bigger than one file
Wirth's original Pascal had no modules: a program was one file, and that was one of the main complaints against it as a language for real work. UCSD Pascal and then Turbo Pascal 4 (1987) added units, and they have been the backbone of every Pascal program since. A unit has an interface, the part other code may use, and an implementation, the part that is nobody else's business. It is compiled separately, so large programs build quickly, and its private parts can change without touching its users.
The second half of this lesson is about memory. Pascal has always had pointers, typed so that the compiler knows what each one points to, and a heap from which you allocate with New and to which you return memory with Dispose. Object Pascal then added types that manage their own memory: strings, dynamic arrays and interfaces are freed automatically when nothing refers to them any more. Knowing which is which is essential, because the rest (objects of classes, and anything you allocate yourself) is your responsibility.
The anatomy of a unit
Definition— Unit
A separately compiled module, in a file whose name matches the unit's name. Its interface section declares what other units and programs may use; its implementation section contains the bodies of the interface's routines and any private declarations. Optional initialization and finalization sections run once, before the main program starts and after it ends.
A program lists the units it needs in its uses clause. The compiler looks for each unit's compiled form, a .ppu file (Free Pascal's equivalent of Delphi's .dcu), and if it is missing or older than the source file unitname.pas, compiles the source first. The search follows the unit path (-Fu on the command line, or the project options in Lazarus). Here is a small unit, saved as temperatures.pas:
unit Temperatures;
{$mode objfpc}{$H+}
interface { what other units and programs may use }
type
TCelsius = Double;
function ToFahrenheit(C: TCelsius): Double;
function Describe(C: TCelsius): string;
function ConversionCount: Integer;
implementation { how it is done: private to this unit }
uses
SysUtils;
const
Freezing = 0.0; { not in the interface, so invisible outside }
var
Conversions: Integer; { the unit's private state }
function ToFahrenheit(C: TCelsius): Double;
begin
Inc(Conversions);
Result := C * 9 / 5 + 32;
end;
function Describe(C: TCelsius): string;
begin
if C <= Freezing then
Result := Format('%.1f °C (freezing)', [C])
else
Result := Format('%.1f °C = %.1f °F', [C, ToFahrenheit(C)]);
end;
function ConversionCount: Integer;
begin
Result := Conversions;
end;
initialization { runs once, before the main program starts }
Conversions := 0;
end.and a program that uses it, saved as main.pas in the same directory:
program Weather;
{$mode objfpc}{$H+}
uses
Temperatures;
begin
WriteLn(Describe(21.5));
WriteLn(Describe(-4));
WriteLn(Temperatures.ToFahrenheit(100):0:1); { a qualified name }
WriteLn('Conversions: ', ConversionCount);
end.fpc main.pas compiled both files, leaving temperatures.ppu and temperatures.o beside the sources, and the program printed:
21.5 °C = 70.7 °F
-4.0 °C (freezing)
212.0
Conversions: 2The counter is 2 because Describe(-4) takes the freezing branch without converting. Everything in the implementation section is private: a program that tries to use Freezing fails with Error: Identifier not found "Freezing". The variable Conversions is also private, and clients read it through the function ConversionCount, so no client can reset it by accident. If two units have a routine of the same name, qualify it with the unit name, as in Temperatures.ToFahrenheit; otherwise the unit listed last in uses wins.
Some rules worth knowing:
- Units listed in the interface
usesclause are needed by the interface itself; those only needed by the code go in the implementationusesclause. Two units may use each other only if at least one of the references is in an implementation section. - The
Systemunit is used implicitly by every program. Other standard units you will use constantly areSysUtils(strings, files, exceptions, dates),Classes(lists, streams,TStringList),Math,StrUtils,DateUtils, andGenerics.Collectionsfor generic containers. - Delphi's library uses dotted unit names, such as
System.SysUtilsandVcl.Forms; Free Pascal 3.2's library uses the short names, and code shared between the two often lists units conditionally. - In this course, every complete, tested program is a single file, so the units it defines are written into the program itself. In real projects, every non-trivial type or group of routines gets its own unit.
Pointers and the heap
Definition— Typed pointer
A value of type ^T is the address of a value of type T, or nil. @X gives the address of a variable, P^ is the value P points to, New(P) allocates a fresh T on the heap and sets P to its address, and Dispose(P) returns that memory.
program Pointers;
{$mode objfpc}{$H+}
type
PNode = ^TNode; { may be declared before TNode: pointers allow it }
TNode = record
Value: string;
Next: PNode;
end;
const
Cities: array[1..3] of string = ('Lagos', 'Quito', 'Hanoi');
var
X: Integer;
P, Q: PInteger; { PInteger = ^Integer, declared in the System unit }
Top, Node: PNode;
Name: string;
procedure Push(var Stack: PNode; const V: string);
var
N: PNode;
begin
New(N); { allocate a TNode on the heap }
N^.Value := V;
N^.Next := Stack;
Stack := N;
end;
function Pop(var Stack: PNode): string;
var
N: PNode;
begin
N := Stack;
Result := N^.Value;
Stack := N^.Next;
Dispose(N); { give the memory back }
end;
begin
X := 41;
P := @X; { @ takes an address }
P^ := P^ + 1; { ^ after a pointer follows it }
WriteLn('X = ', X);
New(Q); { an Integer of our own on the heap }
Q^ := 7;
P := Q; { two pointers, one Integer }
P^ := P^ * 6;
WriteLn('Q^ = ', Q^);
Dispose(Q);
Q := nil; { Q no longer points anywhere; P is now dangling! }
Top := nil;
for Name in Cities do
Push(Top, Name);
Node := Top;
Write('Stack from the top:');
while Assigned(Node) do { Assigned(Node) means Node <> nil }
begin
Write(' ', Node^.Value);
Node := Node^.Next;
end;
WriteLn;
while Top <> nil do
WriteLn('popped ', Pop(Top));
end.It prints:
X = 42
Q^ = 42
Stack from the top: Hanoi Quito Lagos
popped Hanoi
popped Quito
popped LagosFollow the pointers:
P := @XmakesPpoint at the variableX, soP^ := P^ + 1changesX.New(Q)allocates anIntegeron the heap. AfterP := Q, both pointers refer to it, so changingP^changesQ^.- After
Dispose(Q), the memory is gone, butPstill holds its old address.Pis now a dangling pointer: usingP^would read or overwrite memory that may belong to something else. SettingQ := nilprotectsQ, notP. This is the central danger of manual memory management, in Pascal as in C. PNode = ^TNodeis declared beforeTNodeexists. Pascal allows this one forward reference, and only within the sametypesection, precisely so that records can point to records of their own type.PushandPopbuild a linked stack: each node holds a value and a pointer to the node below.Popdisposes of each node it removes, so when the stack is empty, every node allocated byNewhas been returned.
A tree, and proving that nothing leaked
Recursive structures and pointers go together. This program builds a binary search tree of words, counting repeats, prints it in alphabetical order, and then frees it. To check its own memory management, it compares the heap in use before building the tree and after freeing it, using GetFPCHeapStatus from the System unit.
program Tree;
{$mode objfpc}{$H+}
type
PTreeNode = ^TTreeNode;
TTreeNode = record
Word: string;
Count: Integer;
Left, Right: PTreeNode;
end;
{ Insert Word into the tree rooted at Root, or count it again if present. }
procedure Insert(var Root: PTreeNode; const Word: string);
begin
if Root = nil then
begin
New(Root);
Root^.Word := Word;
Root^.Count := 1;
Root^.Left := nil;
Root^.Right := nil;
end
else if Word < Root^.Word then
Insert(Root^.Left, Word)
else if Word > Root^.Word then
Insert(Root^.Right, Word)
else
Inc(Root^.Count);
end;
{ Visit left subtree, node, right subtree: alphabetical order. }
procedure PrintInOrder(Root: PTreeNode);
begin
if Root = nil then
Exit;
PrintInOrder(Root^.Left);
WriteLn(Root^.Word:8, Root^.Count:3);
PrintInOrder(Root^.Right);
end;
function Depth(Root: PTreeNode): Integer;
var
L, R: Integer;
begin
if Root = nil then
Exit(0);
L := Depth(Root^.Left);
R := Depth(Root^.Right);
if L > R then Result := L + 1 else Result := R + 1;
end;
{ Free children before the node itself: after Dispose, Root^ must not be used. }
procedure FreeTree(var Root: PTreeNode);
begin
if Root = nil then
Exit;
FreeTree(Root^.Left);
FreeTree(Root^.Right);
Dispose(Root); { also releases the node's string }
Root := nil;
end;
const
Words: array[1..10] of string =
('mango', 'kiwi', 'papaya', 'kiwi', 'banana', 'lime', 'mango', 'date', 'kiwi', 'yam');
var
Root: PTreeNode;
W: string;
Before: PtrUInt;
begin
Before := GetFPCHeapStatus.CurrHeapUsed;
Root := nil;
for W in Words do
Insert(Root, W);
PrintInOrder(Root);
WriteLn('Depth: ', Depth(Root));
WriteLn('Heap in use grew: ', GetFPCHeapStatus.CurrHeapUsed > Before);
FreeTree(Root);
WriteLn('Heap back where it started: ', GetFPCHeapStatus.CurrHeapUsed = Before);
end.It prints:
banana 1
date 1
kiwi 3
lime 1
mango 2
papaya 1
yam 1
Depth: 4
Heap in use grew: TRUE
Heap back where it started: TRUEInsert takes the root as a var parameter: when it reaches an empty place (nil), it allocates a node and stores its address in the parent's Left or Right field, which is exactly the variable it was passed. PrintInOrder visits the left subtree, the node and the right subtree, which for a search tree gives sorted order. FreeTree must free the children before the node, because after Dispose(Root) the fields Root^.Left and Root^.Right must no longer be read.
Replace FreeTree(Root) with Root := nil and the last line becomes Heap back where it started: FALSE: setting a pointer to nil frees nothing, and the seven nodes are leaked. In a short program that hardly matters; in a server or a desktop application that runs for weeks, leaks accumulate until memory runs out.
Dispose also finalises the node's string field, releasing the string's memory. That is because Dispose knows the type of the record. The untyped routines GetMem and FreeMem, which allocate raw bytes, know nothing about managed fields; use them only for buffers of plain data, typically when talking to C libraries.
Memory management in practice
Professional Object Pascal code uses raw pointers much less than this lesson might suggest. In practice:
- Managed types handle themselves. Strings, dynamic arrays and interface references are reference-counted and freed automatically, even when stored in records and arrays. Most everyday data lives in them.
- Objects of classes are freed explicitly, with
Free, insidetry … finallyblocks (Lessons 6 and 7), or are owned by a container or a component that frees them. This covers most of what C programmers do with pointers. - Containers replace hand-made lists and trees.
TStringList,TFPGList,TList<T>andTDictionary<K, V>are tested, efficient and safe; write your own linked structures when you need something they do not offer, or to learn. - Raw pointers remain for interfacing with C (
PChar,PByte, pointer arithmetic withInc(P)), for performance-critical code, and for low-level work.
To find memory bugs, compile with -gh, which links Free Pascal's heaptrc unit: it records every allocation and can report the blocks that were never freed, with the place they were allocated if you also compile with -gl. Lazarus has check boxes for both in its project options. On Linux, Valgrind finds leaks and uses of freed memory as well. A good habit is to set a pointer to nil after freeing what it points to (FreeAndNil does this for objects) and to test with Assigned before use, so that mistakes fail loudly rather than silently.
Common misunderstandings
Misconception
"Dispose(P) sets P to nil." It returns the memory and leaves P holding a stale address. Set it to nil yourself, and remember that other pointers to the same memory are now dangling too.
Misconception
"Setting a pointer to nil frees the memory." It only forgets the address. Without Dispose (or Free, for objects), the memory stays allocated until the program ends: a leak.
Misconception
"Strings and dynamic arrays inside records leak when the record is disposed." Dispose on a typed pointer finalises the record's managed fields. Only untyped FreeMem skips them, which is why it should not be used for records that contain strings.
Misconception
"A unit is like a C header file." A unit is compiled once into a .ppu that records its interface exactly; users are checked against it, and the compiler recompiles what depends on a changed interface. There is no textual inclusion and no separate header to keep in step.
Exercises
All outputs below were checked by compiling and running the code with Free Pascal 3.2.2.
1. Units, pointers and memory
Warm-upHumanIn the Temperatures unit, why is the constant Freezing declared in the implementation section rather than the interface?
2. Units, pointers and memory
CoreComputationalA program using the Temperatures unit calls Describe(30), then Describe(0), then ToFahrenheit(10), and prints ConversionCount. What number is printed?
3. Units, pointers and memory
Warm-upComputationalX is an Integer and P a PInteger. What does this print?
X := 5;
P := @X;
P^ := P^ * 3;
WriteLn(X);
4. Units, pointers and memory
CoreComputationalUsing the lesson's Push and Pop, starting from Top := nil, a program does: Push(Top, 'a'); Push(Top, 'b'); Push(Top, 'c'); Pop(Top); Pop(Top); Push(Top, 'd'); and then prints the values from the top down, separated by spaces. What does it print?
5. Units, pointers and memory
StretchComputationalIn the tree program, the word list is replaced by the same words in alphabetical order: banana, date, kiwi, kiwi, kiwi, lime, mango, mango, papaya, yam. What depth does the program report now?
6. Units, pointers and memory
CoreHumanAfter P := Q; Dispose(Q); Q := nil;, what is true of P?
7. Units, pointers and memory
CoreComputationalIn the tree program, FreeTree(Root); is replaced by Root := nil;. What does the last line print, and why?
Further reading and resources
- Free Pascal Reference Guide: Programs, units, blocksThe structure of units, the uses clause, and initialization and finalization sections.
- Free Pascal Programmer's Guide: memory issuesHow the heap manager works, and the heaptrc unit for tracing leaks.
- Free Pascal User's Guide: compiling unitsSearch paths, .ppu files and how fpc decides what to recompile.