Singleton Pattern: what changed

Revision 2 to 3. 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		-	~~`name of s1: one`\~~
75		-	~~`name of s1: two`\~~
76		-	~~`name of s2: two`~~
	74	+	```text
	75	+	name of s1: one
	76	+	name of s1: two
	77	+	name of s2: two
	78	+	```
77	79
78	80		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	81
80		-	~~`name of s1: one`\~~
81		-	~~`name of s1: one`\~~
82		-	~~`name of s2: two`~~
	82	+	```text
	83	+	name of s1: one
	84	+	name of s1: one
	85	+	name of s2: two
	86	+	```
83	87
84	88		When the wrong output is produced, a second instance is created that has its own name.
85	89
86	90		## Nice Pattern, Don't Use It
87	91
88	92		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	93
90	94		- Difficult to test. Because of its nature, singletons are hard to replace for testing.
91	95		- 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	96
93	97		Singletons are commonly used for shared resources or 'engines':
94	98
95	99		- Printers
96	100		- Databases
97	101		- Loggers
98	102
99	103		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	104
101	105		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	106
103	107		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	108
105	109		In the rest of this article I discuss how to create a singleton.
106	110
107	111		# Going Global
108	112
109	113		## In Your (Inter)Face
110	114
111	115		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	116
113	117		``` pascal
114	118		unit GlobalVariableSingleton;
115	119
116	120		{$mode objfpc}{$H+}
117	121
118	122		interface
119	123
120	124		type
121	125		TSingleton = class
122	126		name: String;
123	127		constructor create;
124	128		end;
125	129
126	130		var
127	131		Singleton: TSingleton = nil;
128	132
129	133		implementation
130	134		{* Something happens out here *}
131	135
132	136		initialization
133	137		Singleton := TSingleton.Create;
134	138
135	139		end.
136	140		```
137	141
138	142		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	143
140	144		``` pascal
141	145		constructor TSingleton.Create;
142	146		begin
143	147		If Assigned(Singleton) then
144	148		Raise Exception.Create('Please use the global variable Singleton');
145	149		inherited Create;
146	150		end;
147	151		```
148	152
149	153		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	154
151	155		``` pascal
152	156		program TrueSingleton;
153	157
154	158		{$mode objfpc}{$H+}
155	159
156	160		uses
157	161		{$IFDEF UNIX}{$IFDEF UseCThreads}
158	162		cthreads,
159	163		{$ENDIF}{$ENDIF}
160	164		Classes, GlobalVariableSingleton
161	165		{ you can add units after this };
162	166
163	167		{$R TrueSingleton.res}
164	168		var
165	169		s1, s2: TSingleton;
166	170
167	171		begin
168	172		s1:= Singleton;
169	173		s1.name := 'one';
170	174		writeln('name of s1: '+s1.name);
171	175
172	176		s2:= Singleton;
173	177		s2.name := 'two';
174	178
175	179		writeln('name of s1: '+s1.name);
176	180		writeln('name of s2: '+s2.name);
177	181		//writeln('name of singleton: ' + Singleton.name);
178	182		readln;
179	183		end.
180	184		```
181	185
182	186		Of course, instead of assigning the global variable to a local variable you can also use the global variable directly.
183	187
184	188		## Up Your Implementation
185	189
186	190		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	191
188	192		``` pascal
189	193		unit GlobalFunctionSingleton;
190	194
191	195		{$mode objfpc}{$H+}
192	196
193	197		interface
194	198
195	199		uses
196	200		Classes, SysUtils;
197	201		type
198	202		TSingleton = class
199	203		public
200	204		name : String;
201	205		constructor Create;
202	206		end;
203	207
204	208		function GetSingleton : TSingleton;
205	209
206	210		implementation
207	211		var
208	212		Singleton : TSingleton = nil;
209	213
210	214		constructor TSingleton.Create;
211	215		begin
212	216		assert(Singleton=nil, 'illegal recreation of Singleton.');
213	217		inherited Create;
214	218		Singleton := self;
215	219		end;
216	220
217	221		function GetSingleton : TSingleton;
218	222		Begin
219	223		If(Singleton = nil) then
220	224		raise Exception.Create('Singleton not created during initialization.');
221	225		Result := Singleton;
222	226		end;
223	227
224	228		initialization
225	229		Singleton := TSingleton.Create;
226	230		end.
227	231		```
228	232
229	233		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	234
231	235		``` pascal
232	236		program TrueSingleton;
233	237
234	238		{$mode objfpc}{$H+}
235	239
236	240		uses
237	241		{$IFDEF UNIX}{$IFDEF UseCThreads}
238	242		cthreads,
239	243		{$ENDIF}{$ENDIF}
240	244		Classes, GlobalFunctionSingleton
241	245		{ you can add units after this };
242	246
243	247		{$R TrueSingleton.res}
244	248		var
245	249		s1, s2: TSingleton;
246	250
247	251		begin
248	252		s1:= GetSingleton;
249	253		s1.name := 'one';
250	254		writeln('name of s1: '+s1.name);
251	255
252	256		s2:= GetSingleton;
253	257		s2.name := 'two';
254	258
255	259		writeln('name of s1: '+s1.name);
256	260		writeln('name of s2: '+s2.name);
257	261		//writeln('name of singleton: ' + Singleton.name);
258	262		readln;
259	263		end.
260	264		```
261	265
262	266		It works, but I have not seen this applied in any source code.
263	267
264	268		# Classy Implementation
265	269
266	270		## Simple Singleton
267	271
268	272		The following code presents a very simple singleton.
269	273
270	274		``` pascal
271	275		unit Singleton1;
272	276
273	277		{$mode objfpc}{$H+}
274	278
275	279		interface
276	280
277	281		type
278	282		TSingleton = class
279	283		name: String;
280	284		constructor create;
281	285		end;
282	286
283	287		implementation
284	288
285	289		var
286	290		Singleton: TSingleton = nil;
287	291
288	292		constructor TSingleton.Create;
289	293		begin
290	294		if not(assigned(Singleton)) then begin
291	295		inherited;
292	296		(... do initializations ...)
293	297		Singleton := self;
294	298		end else begin
295	299		self := Singleton;
296	300		end;
297	301		end;
298	302
299	303		end.
300	304		```
301	305
302	306		In the Singleton1 unit, notice the following:
303	307
304	308		- The Singleton variable is defined in the implementation section. This makes the variable invisible outside the unit.
305	309		- A public constructor is used.
306	310
307	311		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	312
309	313		## Why It Is Different In Pascal
310	314
311	315		Then why not implement the singleton just like it is shown in the Pattern diagram? Well, here we go:
312	316
313	317		``` pascal
314	318		unit Singleton2;
315	319
316	320		{$mode objfpc}{$H+}
317	321
318	322		interface
319	323
320	324		uses
321	325		Classes, SysUtils;
322	326
323	327		type
324	328		TSingleton = class
325	329		private
326	330		constructor Create;
327	331		public
328	332		name: String;
329	333		class function GetInstance : TSingleton;
330	334		end;
331	335
332	336		implementation
333	337		var
334	338		Singleton : TSingleton = nil;
335	339
336	340		constructor TSingleton.Create;
337	341		begin
338	342		inherited Create;
339	343		end;
340	344
341	345		class function TSingleton.GetInstance : TSingleton;
342	346		begin
343	347		if Singleton = nil then
344	348		Singleton := TSingleton.Create;
345	349		Result := Singleton;
346	350		end;
347	351
348	352		end.
349	353		```
350	354
351	355		The problem with the Singleton2 unit is that the program will work with the following client code:
352	356
353	357		``` pascal
354	358		program TrueSingleton;
355	359
356	360		{$mode objfpc}{$H+}
357	361
358	362		uses
359	363		{$IFDEF UNIX}{$IFDEF UseCThreads}
360	364		cthreads,
361	365		{$ENDIF}{$ENDIF}
362	366		Classes, Singleton2
363	367		{ you can add units after this };
364	368
365	369		{$R TrueSingleton.res}
366	370		var
367	371		s1, s2: TSingleton;
368	372
369	373		begin
370	374		s1:= TSingleton.Create;
371	375		s1.name := 'one';
372	376		writeln('name of s1: '+s1.name);
373	377
374	378		s2:= TSingleton.Create;
375	379		s2.name := 'two';
376	380
377	381		writeln('name of s1: '+s1.name);
378	382		writeln('name of s2: '+s2.name);
379	383		//writeln('name of singleton: ' + Singleton.name);
380	384		readln;
381	385		end.
382	386		```
383	387
384	388		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	389
386	390		## The 'constructor should be public' Singleton
387	391
388	392		A small change makes a big difference:
389	393
390	394		``` pascal
391	395		unit Singleton3;
392	396
393	397		{$mode objfpc}{$H+}
394	398
395	399		interface
396	400
397	401		uses
398	402		Classes, SysUtils;
399	403
400	404		type
401	405		TSingleton = class
402	406		private
403	407		constructor Init;
404	408		public
405	409		name: String;
406	410		class function Create: TSingleton;
407	411		end;
408	412
409	413		implementation
410	414		var
411	415		Singleton : TSingleton = nil;
412	416
413	417		constructor TSingleton.Init;
414	418		begin
415	419		inherited Create;
416	420		end;
417	421
418	422		class function TSingleton.Create: TSingleton;
419	423		begin
420	424		if Singleton = nil then
421	425		Singleton := TSingleton.Init;
422	426		Result := Singleton;
423	427		end;
424	428
425	429		end.
426	430		```
427	431
428	432		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	433
430	434		``` pascal
431	435		program TrueSingleton;
432	436
433	437		{$mode objfpc}{$H+}
434	438
435	439		uses
436	440		{$IFDEF UNIX}{$IFDEF UseCThreads}
437	441		cthreads,
438	442		{$ENDIF}{$ENDIF}
439	443		Classes, Singleton3
440	444		{ you can add units after this };
441	445
442	446		{$R TrueSingleton.res}
443	447		var
444	448		s1, s2: TSingleton;
445	449
446	450		begin
447	451		s1:= TSingleton.Create;
448	452		s1.name := 'one';
449	453		writeln('name of s1: '+s1.name);
450	454
451	455		s2:= TSingleton.Create;
452	456		s2.name := 'two';
453	457
454	458		writeln('name of s1: '+s1.name);
455	459		writeln('name of s2: '+s2.name);
456	460		//writeln('name of singleton: ' + Singleton.name);
457	461		readln;
458	462		end.
459	463		```
460	464
461	465		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	466
463	467		## Hide That For Me
464	468
465	469		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	470
467	471		# Discussion Of The Options
468	472
469	473		In this part we will pay attention to some of the discussions.
470	474
471	475		## Reducing the visibility of the constructor
472	476
473	477		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	478
475		-	~~`The reason you can't lower the visibility of the constructor or any`\~~
476		-	~~`method for that matter... A class interface (implementation section) ,`\~~
477		-	~~`even for TObject as in your example, is a contract of how you can use`\~~
478		-	~~`that class and what is available to you. By lowering the visibility`\~~
479		-	~~`of a method or constructor in a descendant class, you are breaking the`\~~
480		-	~~`contract previously defined. This is a BIG no-no, hence the reason it`\~~
481		-	~~`is not allowed.`~~
	479	+	``` pascal
	480	+	The reason you can't lower the visibility of the constructor or any
	481	+	method for that matter... A class interface (implementation section) ,
	482	+	even for TObject as in your example, is a contract of how you can use
	483	+	that class and what is available to you. By lowering the visibility
	484	+	of a method or constructor in a descendant class, you are breaking the
	485	+	contract previously defined. This is a BIG no-no, hence the reason it
	486	+	is not allowed.
	487	+	```
482	488
483	489		## Design Time Help vs. Run Time Breaking
484	490
485	491		The following arguments may lead you to choose the Singleton3 unit as example implementation:
486	492
487	493		- 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	494		- If you want to avoid multiple instantiation of the class, then why not provide design time help to the client programmer.
489	495		- In other programming languages it is not bad programming behavior, so FreePascal must have a very good reason to avoid it.
490	496		- Reducing the visibility of any method of a class should not be allowed except for the constructor.
491	497
492	498		## The pattern is not followed
493	499
494	500		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	501
496	502		- The intent of the pattern is followed and the benefits achieved.
497	503		- 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	504		- Some compromises had to be made to make the singleton work in FreePascal.
499	505
500	506		## The implementations have a problem with multi-threading and synchronization
501	507
502	508		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	509
504	510		## The singleton class implementation has a problem with platform independence
505	511
506	512		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	513
508	514		# Conclusion
509	515
510	516		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	517
512	518		---
513	519		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	520		Category: Design Patterns
515	521		Category: FPC
516	522		Category: Pascal
517	523		Category: Tutorials

Back to history