Singleton Pattern: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		# Introduction
2	2
3	3		Considered one of the simplest patterns, it probably is the most discussed pattern: the singleton. What is so difficult to this pattern? Well, no matter the language in which you implement it, you have to do some counter intuitive things to reap all the benefits of the pattern. Every programming language has it's own quirks with this pattern, FreePascal is no exception. As a result, any implementation may lead to discussion and the choices you make for the implementation will be against the principles of another programmer. The implementation of this pattern is never ideal, the approaches provided in this article included. Yet, I hope this article is useful for you.
4	4
5	5		## What You Will Learn
6	6
7	7		- The benefits of the Singleton pattern and why to avoid it
8	8		- Global variables and class variables in FreePascal
9	9		- How to hide the constructor and keep it private
10	10
11	11		## Acknowledgement
12	12
13	13		I didn't think up the examples and the arguments. I found the examples in forum discussions and their archives. This article is a overview of the discussion about singletons and a collection of the usable examples I found.
14	14
15	15		- [Making a Singleton class](http://community.freepascal.org:10000/bboards/message?message_id=234708&forum_id=24097)
16	16		- [Implementing a true Singleton - Can we decrease the visibility of a method?](http://lists.freepascal.org/lists/fpc-pascal/2006-December/012826.html)
17	17		- [Warning: Constructor should be public](http://www.mail-archive.com/fpc-devel@lists.freepascal.org/msg13833.html)
18	18		- [Compiler Warning: Constructor should be public](http://www.mail-archive.com/fpc-pascal@lists.freepascal.org/msg18257.html)
19	19		- TDockManager
20	20		- Printers4Lazarus package
21	21
22	22		# The Pattern
23	23
24	24		## The diagram
25	25
26	26		![The Singleton pattern](/wiki-images/5/56/250pxSingleton.png)\
27	27		The Singleton pattern is described in the above image. The Singleton class defines a private class variable that holds the Singleton instance. The class method GetInstance creates that instance once and only once and returns it to the client. The constructor method 'Singleton()' is private and thus not visible to the client. The Design Patterns book lists the following benefits:
28	28
29	29		- Controlled access to sole instance
30	30		- Reduced namespace
31	31		- Permits refinement of operations and representation
32	32		- Permits variable number of instances (extend the class to allow a controlled number of instances if designer wants to allow such a situation)
33	33		- More flexible than class operations
34	34
35	35		## The Singleton Client
36	36
37	37		The following program would be typical use of a singleton.
38	38
39	39		``` pascal
40	40		program TrueSingleton;
41	41
42	42		{$mode objfpc}{$H+}
43	43
44	44		uses
45	45		{$IFDEF UNIX}{$IFDEF UseCThreads}
46	46		cthreads,
47	47		{$ENDIF}{$ENDIF}
48	48		Classes, Singleton2
49	49		{ you can add units after this };
50	50
51	51		{$R TrueSingleton.res}
52	52		var
53	53		s1, s2: TSingleton;
54	54
55	55		begin
56	56		s1:= TSingleton.GetInstance;
57	57		s1.name := 'one';
58	58		writeln('name of s1: '+s1.name);
59	59
60	60		s2:= TSingleton.GetInstance;
61	61		s2.name := 'two';
62	62
63	63		writeln('name of s1: '+s1.name);
64	64		writeln('name of s2: '+s2.name);
65	65		//writeln('name of singleton: ' + Singleton.name);
66	66		readln;
67	67		end.
68	68		```
69	69
70	70		That is, if the singleton would work according to the pattern. The GetInstance method is a class method that returns the only available instance. We will help our user, the programmer, if the constructor Create would not show up in the code completion at all. This helps our users to remember that they should use GetInstance. A problem here however is that FreePascal, in contrast to other languages, doesn't require a specific name as constructor. Init is just as good a name for a constructor as Create is.
71	71
72	72		The correct output will look like this:
73	73
74		-	~~<code>`name of s1: one`\~~
	74	+	`name of s1: one`\
75	75		`name of s1: two`\
76		-	~~`name of s2: two`</code>~~
	76	+	`name of s2: two`
77	77
78	78		When the correct output is produced, `Singleton.GetInstance` will return the singleton instance and the name of both `s1` and `s2` will always be the same. The wrong output will look like this:
79	79
80		-	~~<code>`name of s1: one`\~~
81	80		`name of s1: one`\
82		-	~~`name of s2: two`</code>~~
	81	+	`name of s1: one`\
	82	+	`name of s2: two`
83	83
84	84		When the wrong output is produced, a second instance is created that has its own name.
85	85
86	86		## Nice Pattern, Don't Use It
87	87
88	88		Or at least think it over before you use it. There are many reasons to not use a singleton. Really, there are more reasons not to use a singleton than there are reasons to use a singleton. See the [Drawbacks and Reference sections](https://en.wikipedia.org/w/index.php?title=Singleton_pattern&oldid=397293289#Drawbacks) of an old version of the WikiPedia article discussing singletons. The main reasons:
89	89
90	90		- Difficult to test. Because of its nature, singletons are hard to replace for testing.
91	91		- Singletons make dependencies unclear. Although the singleton comes from another unit, you cannot see in the interface of your object that the singleton is used. Well, the uses section gives a clue, but that doesn't say where exactly it is used.
92	92
93	93		Singletons are commonly used for shared resources or 'engines':
94	94
95	95		- Printers
96	96		- Databases
97	97		- Loggers
98	98
99	99		To avoid the use of too many singletons, try to avoid them and use only one in your whole application. For example, you may want to create a toolbox (aka [[http://martinfowler.com/eaaCatalog/registry.html Registry]]) for your application. Now the toolbox knows the printer, database or logger and your code queries the toolbox for instances. Your code depends on the toolbox and the toolbox depends on the resources that can be queried. This reduces the dependencies from a lot of singleton to only one singleton.
100	100
101	101		Another idea is to use [[http://www.theserverside.com/news/1321158/A-beginners-guide-to-Dependency-Injection Dependency Injection]]. If an object 'B' needs another object 'A' to function properly, then hand the object 'A' to the constructor of the class 'B'. This at least makes clear that the class B depends on A in the interface.
102	102
103	103		To improve testing of your code, you may want to have your singletons implement an interface. The GetInstance method or function may then return an instance that conforms to the interface. Depending on whatever (compilation directives etc.) the GetInstance method can return the 'real' object or a mock-up.
104	104
105	105		In the rest of this article I discuss how to create a singleton.
106	106
107	107		# Going Global
108	108
109	109		## In Your (Inter)Face
110	110
111	111		In Free Pascal it is quite common to define a global variable for the Singleton pattern. All through the source code of FreePascal and Lazarus you will find examples of this. The idea is to create an instance at initialization of the unit file and then use it when needed. The client programmer should just know that there is a global instance and that that global instance should be used. Every programmer writes and reads full documentation, so usually this is no problem.
112	112
113	113		``` pascal
114	114		unit GlobalVariableSingleton;
115	115
116	116		{$mode objfpc}{$H+}
117	117
118	118		interface
119	119
120	120		type
121	121		TSingleton = class
122	122		name: String;
123	123		constructor create;
124	124		end;
125	125
126	126		var
127	127		Singleton: TSingleton = nil;
128	128
129	129		implementation
130	130		{* Something happens out here *}
131	131
132	132		initialization
133	133		Singleton := TSingleton.Create;
134	134
135	135		end.
136	136		```
137	137
138	138		When this unit is loaded, the singleton is instantiated and can be used. The initialization takes place when the program is started, so the singleton is always present. This violates the reduction of namespace, the namespace is polluted by a global variable that is waiting for use. Even if the programmer is not interested in the instance, but is only interested in other functionality in your unit, the instance is created and will use memory. On the other hand, we wanted to have a singleton so that we would use it right? There is no probability involved, we will use the instance. So, why not create the instance when we startup the application? With the above definition of a global variable the instantiation is not controlled. Any programmer can still instantiate the TSingleton. This can be improved with documentation and a constructor that warns against instantiation after the global variable is created. Something like the following:
139	139
140	140		``` pascal
141	141		constructor TSingleton.Create;
142	142		begin
143	143		If Assigned(Singleton) then
144	144		Raise Exception.Create('Please use the global variable Singleton');
145	145		inherited Create;
146	146		end;
147	147		```
148	148
149	149		However, such a constructor only warns at run time and doesn't help at design time. An alternative to the if statement could be an assert. With an assert the detection would be moved to test time, which – as you know - we all do and happens far before run time. However, an assert doesn't even help at run time since the asserts are not linked in for the run time application. I agree, it does seem to happen that not all code is always tested. In the given constructor the program at least breaks due to an unhandled exception. The programmer of your client will probably work around that annoyance with a `try ... except` statement. Even though programmers can work around the issue, their code doesn't work so why should they? The global variable is not a singleton at design time, the constructor will still show up. However, it will certainly be a singleton at run time. The typical client code is:
150	150
151	151		``` pascal
152	152		program TrueSingleton;
153	153
154	154		{$mode objfpc}{$H+}
155	155
156	156		uses
157	157		{$IFDEF UNIX}{$IFDEF UseCThreads}
158	158		cthreads,
159	159		{$ENDIF}{$ENDIF}
160	160		Classes, GlobalVariableSingleton
161	161		{ you can add units after this };
162	162
163	163		{$R TrueSingleton.res}
164	164		var
165	165		s1, s2: TSingleton;
166	166
167	167		begin
168	168		s1:= Singleton;
169	169		s1.name := 'one';
170	170		writeln('name of s1: '+s1.name);
171	171
172	172		s2:= Singleton;
173	173		s2.name := 'two';
174	174
175	175		writeln('name of s1: '+s1.name);
176	176		writeln('name of s2: '+s2.name);
177	177		//writeln('name of singleton: ' + Singleton.name);
178	178		readln;
179	179		end.
180	180		```
181	181
182	182		Of course, instead of assigning the global variable to a local variable you can also use the global variable directly.
183	183
184	184		## Up Your Implementation
185	185
186	186		Notice how in the GlobalVariableSingleton unit the global variable is defined in the interface section. This is what makes the variable Singleton a global variable. If you put the variable in the implementation section, the variable will only be available for code in the implementation section. As such, a variable defined in the implementation section acts similar to a class or package variable. The implementation variable can be used by all the code in the unit but not outside that unit. The interface variable is public, can be used inside and outside the unit. This is used in the following code.
187	187
188	188		``` pascal
189	189		unit GlobalFunctionSingleton;
190	190
191	191		{$mode objfpc}{$H+}
192	192
193	193		interface
194	194
195	195		uses
196	196		Classes, SysUtils;
197	197		type
198	198		TSingleton = class
199	199		public
200	200		name : String;
201	201		constructor Create;
202	202		end;
203	203
204	204		function GetSingleton : TSingleton;
205	205
206	206		implementation
207	207		var
208	208		Singleton : TSingleton = nil;
209	209
210	210		constructor TSingleton.Create;
211	211		begin
212	212		assert(Singleton=nil, 'illegal recreation of Singleton.');
213	213		inherited Create;
214	214		Singleton := self;
215	215		end;
216	216
217	217		function GetSingleton : TSingleton;
218	218		Begin
219	219		If(Singleton = nil) then
220	220		raise Exception.Create('Singleton not created during initialization.');
221	221		Result := Singleton;
222	222		end;
223	223
224	224		initialization
225	225		Singleton := TSingleton.Create;
226	226		end.
227	227		```
228	228
229	229		In this case, the singleton instance is not a global variable (it is defined in the implementation section) and cannot be used outside the implementation section. The GetSingleton function however can be used outside the unit. But in contrast to the pattern diagram, it is not a class method but a good old global function. The advantage over the previous implementation is that the GetSingleton function can contain more functionality than just returning the one instance. For example, the function could be used to hand out instances from a pool of singletons. The client code is as follows:
230	230
231	231		``` pascal
232	232		program TrueSingleton;
233	233
234	234		{$mode objfpc}{$H+}
235	235
236	236		uses
237	237		{$IFDEF UNIX}{$IFDEF UseCThreads}
238	238		cthreads,
239	239		{$ENDIF}{$ENDIF}
240	240		Classes, GlobalFunctionSingleton
241	241		{ you can add units after this };
242	242
243	243		{$R TrueSingleton.res}
244	244		var
245	245		s1, s2: TSingleton;
246	246
247	247		begin
248	248		s1:= GetSingleton;
249	249		s1.name := 'one';
250	250		writeln('name of s1: '+s1.name);
251	251
252	252		s2:= GetSingleton;
253	253		s2.name := 'two';
254	254
255	255		writeln('name of s1: '+s1.name);
256	256		writeln('name of s2: '+s2.name);
257	257		//writeln('name of singleton: ' + Singleton.name);
258	258		readln;
259	259		end.
260	260		```
261	261
262	262		It works, but I have not seen this applied in any source code.
263	263
264	264		# Classy Implementation
265	265
266	266		## Simple Singleton
267	267
268	268		The following code presents a very simple singleton.
269	269
270	270		``` pascal
271	271		unit Singleton1;
272	272
273	273		{$mode objfpc}{$H+}
274	274
275	275		interface
276	276
277	277		type
278	278		TSingleton = class
279	279		name: String;
280	280		constructor create;
281	281		end;
282	282
283	283		implementation
284	284
285	285		var
286	286		Singleton: TSingleton = nil;
287	287
288	288		constructor TSingleton.Create;
289	289		begin
290	290		if not(assigned(Singleton)) then begin
291	291		inherited;
292	292		(... do initializations ...)
293	293		Singleton := self;
294	294		end else begin
295	295		self := Singleton;
296	296		end;
297	297		end;
298	298
299	299		end.
300	300		```
301	301
302	302		In the Singleton1 unit, notice the following:
303	303
304	304		- The Singleton variable is defined in the implementation section. This makes the variable invisible outside the unit.
305	305		- A public constructor is used.
306	306
307	307		Free Pascal doesn't allow for class variables and class properties. Only procedures and functions can be modified with the class keyword. Defining the 'static' variable in the implementation section is the closest we can get to a static variable. At initialization this variable is set to nil, so no memory is used yet. Although this implementation works, the `self := Singleton;` bugs me. I didn't try it, but I assume this allows for memory leaks. Even if it doesn't allow for memory leaks, it just doesn't look right.
308	308
309	309		## Why It Is Different In Pascal
310	310
311	311		Then why not implement the singleton just like it is shown in the Pattern diagram? Well, here we go:
312	312
313	313		``` pascal
314	314		unit Singleton2;
315	315
316	316		{$mode objfpc}{$H+}
317	317
318	318		interface
319	319
320	320		uses
321	321		Classes, SysUtils;
322	322
323	323		type
324	324		TSingleton = class
325	325		private
326	326		constructor Create;
327	327		public
328	328		name: String;
329	329		class function GetInstance : TSingleton;
330	330		end;
331	331
332	332		implementation
333	333		var
334	334		Singleton : TSingleton = nil;
335	335
336	336		constructor TSingleton.Create;
337	337		begin
338	338		inherited Create;
339	339		end;
340	340
341	341		class function TSingleton.GetInstance : TSingleton;
342	342		begin
343	343		if Singleton = nil then
344	344		Singleton := TSingleton.Create;
345	345		Result := Singleton;
346	346		end;
347	347
348	348		end.
349	349		```
350	350
351	351		The problem with the Singleton2 unit is that the program will work with the following client code:
352	352
353	353		``` pascal
354	354		program TrueSingleton;
355	355
356	356		{$mode objfpc}{$H+}
357	357
358	358		uses
359	359		{$IFDEF UNIX}{$IFDEF UseCThreads}
360	360		cthreads,
361	361		{$ENDIF}{$ENDIF}
362	362		Classes, Singleton2
363	363		{ you can add units after this };
364	364
365	365		{$R TrueSingleton.res}
366	366		var
367	367		s1, s2: TSingleton;
368	368
369	369		begin
370	370		s1:= TSingleton.Create;
371	371		s1.name := 'one';
372	372		writeln('name of s1: '+s1.name);
373	373
374	374		s2:= TSingleton.Create;
375	375		s2.name := 'two';
376	376
377	377		writeln('name of s1: '+s1.name);
378	378		writeln('name of s2: '+s2.name);
379	379		//writeln('name of singleton: ' + Singleton.name);
380	380		readln;
381	381		end.
382	382		```
383	383
384	384		It is difficult to see the problem. In the Singleton2 unit we made the constructor private. Run the client code, and the compiler complains about the constructor not being public, but after that the program works and shows that the code doesn't work as a singleton. Two different instances will be created. We learn from this that although we reduced the visibility of the constructor, the TObject.Create constructor is still visible.
385	385
386	386		## The 'constructor should be public' Singleton
387	387
388	388		A small change makes a big difference:
389	389
390	390		``` pascal
391	391		unit Singleton3;
392	392
393	393		{$mode objfpc}{$H+}
394	394
395	395		interface
396	396
397	397		uses
398	398		Classes, SysUtils;
399	399
400	400		type
401	401		TSingleton = class
402	402		private
403	403		constructor Init;
404	404		public
405	405		name: String;
406	406		class function Create: TSingleton;
407	407		end;
408	408
409	409		implementation
410	410		var
411	411		Singleton : TSingleton = nil;
412	412
413	413		constructor TSingleton.Init;
414	414		begin
415	415		inherited Create;
416	416		end;
417	417
418	418		class function TSingleton.Create: TSingleton;
419	419		begin
420	420		if Singleton = nil then
421	421		Singleton := TSingleton.Init;
422	422		Result := Singleton;
423	423		end;
424	424
425	425		end.
426	426		```
427	427
428	428		The Init constructor provides us with the constructor we need to avoid illegally hiding the TObject constructor. The Init constructor is also private. The Create function hides the TObject.Create constructor. This code works. Using the above we have controlled access to the singleton. We also do not pollute the namespace with global variables. We can create additional methods as much as we want. Also, if we declare an array of singletons in the implementation section we can provide additional, but limited instances of the singleton. And, we do not need additional static methods other than the Create function. All benefits of the singleton pattern are thus achieved. Typical client code now needs to look like the following:
429	429
430	430		``` pascal
431	431		program TrueSingleton;
432	432
433	433		{$mode objfpc}{$H+}
434	434
435	435		uses
436	436		{$IFDEF UNIX}{$IFDEF UseCThreads}
437	437		cthreads,
438	438		{$ENDIF}{$ENDIF}
439	439		Classes, Singleton3
440	440		{ you can add units after this };
441	441
442	442		{$R TrueSingleton.res}
443	443		var
444	444		s1, s2: TSingleton;
445	445
446	446		begin
447	447		s1:= TSingleton.Create;
448	448		s1.name := 'one';
449	449		writeln('name of s1: '+s1.name);
450	450
451	451		s2:= TSingleton.Create;
452	452		s2.name := 'two';
453	453
454	454		writeln('name of s1: '+s1.name);
455	455		writeln('name of s2: '+s2.name);
456	456		//writeln('name of singleton: ' + Singleton.name);
457	457		readln;
458	458		end.
459	459		```
460	460
461	461		Notice how this program uses the Create method, not the GetInstance method. But, look at the class definition again. Create is not a constructor it is a class method that returns the singleton instance. Init is the constructor.
462	462
463	463		## Hide That For Me
464	464
465	465		When compiling, the compiler warns that the constructor is not public. So, now you are warned. You can choose to ignore the warning, because the code is really what you want. You can also suppress the warning. The message code for the 'Constructor should be public' warning is 3018. To suppress the warning add `-vm3018` to the command line of the compiler. In Lazarus you can deselect the message {From the Project menu, choose Project Options. Then, in the Options for Project: dialog, open the Compiler Options branch in the navigation pane and click Messages. Now deselect '(W)Constructor should be public' in the compiler messages list.}
466	466
467	467		# Discussion Of The Options
468	468
469	469		In this part we will pay attention to some of the discussions.
470	470
471	471		## Reducing the visibility of the constructor
472	472
473	473		Of course there is a reason why a constructor should be public. The Free Pascal compiler thus gives a warning when the constructor is made private. However, why does FreePascal give the warning? Other programming languages allow private constructors without a problem. Apart from that it is bad Pascal programming behavior, I don't know the answer. Maybe, since it is a warning, the reasoning may be that if the constructor is not public, then there is no way to create the object and what is the use of a class if you cannot make an object out of it? To sum things up, the argument is as follows:
474	474
475	475		`The reason you can't lower the visibility of the constructor or any`\
476	476		`method for that matter... A class interface (implementation section) ,`\
477	477		`even for TObject as in your example, is a contract of how you can use`\
478	478		`that class and what is available to you. By lowering the visibility`\
479	479		`of a method or constructor in a descendant class, you are breaking the`\
480	480		`contract previously defined. This is a BIG no-no, hence the reason it`\
481	481		`is not allowed.`
482	482
483	483		## Design Time Help vs. Run Time Breaking
484	484
485	485		The following arguments may lead you to choose the Singleton3 unit as example implementation:
486	486
487	487		- The Singleton3 provides design time guidance. Possible alternatives that are more in the spirit of Pascal give run time break downs, or at best testing time messages. Design time guidance is preferred in my opinion.
488	488		- If you want to avoid multiple instantiation of the class, then why not provide design time help to the client programmer.
489	489		- In other programming languages it is not bad programming behavior, so FreePascal must have a very good reason to avoid it.
490	490		- Reducing the visibility of any method of a class should not be allowed except for the constructor.
491	491
492	492		## The pattern is not followed
493	493
494	494		Yes, the pattern is not closely followed. The constructor is called Init while in FreePascal there is the convention to call the constructor Create. Then on top of that name Create is used for the static function instead of the name GetInstance. The following arguments are in favor of the most likable implementation:
495	495
496	496		- The intent of the pattern is followed and the benefits achieved.
497	497		- The code is quite nice and well behaved. There are no run-time breaks built in and there are no doubtful constructs in the code.
498	498		- Some compromises had to be made to make the singleton work in FreePascal.
499	499
500	500		## The implementations have a problem with multi-threading and synchronization
501	501
502	502		I never saw a good discussion about this, but in discussions about singletons in various programming languages programmers go far to make their singleton multi-threaded and synchronized and a number of other things. The singleton implementations given in this article are not optimized for that.
503	503
504	504		## The singleton class implementation has a problem with platform independence
505	505
506	506		A singleton can never have descendants. What should happen when a descendant class calls inherited Create? Also it would be quite wrong to make the singleton descend from anything else but TObject. Now consider platform independence. Look at FreePascal sources where a global variable is used for a printer or whatever central resource. These global variables are by no exception made in the platform specific units, the shared functionality is written in a platform independent unit. Consider how this should be done with a singleton class. (I'll wait here until you find out that a hierarchy of singletons will inevitably cause a mess and will not allow for platform independent code.) Now that you are convinced we can easily say that the singleton class cannot be used with shared functionality, repeating singleton functionality for all platform implementations will cause a maintenance mess.
507	507
508	508		# Conclusion
509	509
510	510		Yes, singletons are possible! Even in FreePascal. But, singletons are not a very good idea in platform independent FreePascal code. Whether you use a class or a global variable, there is no perfect implementation of a singleton.
511	511
512	512		---
513	513		From the Free Pascal wiki, page "Singleton Pattern", as it stood on 2020-05-08 after a change by Kai Burghardt, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
514	514		Category: Design Patterns
515	515		Category: FPC
516	516		Category: Pascal
517	517		Category: Tutorials

Back to history