Multithreaded Application Tutorial: what changed

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

Old	New		Line
1	1		## Overview
2	2
3	3		This page will try to explain how to write and debug a multi-threaded application with Free Pascal and Lazarus. A multi-threaded application is one that creates two or more threads of execution that work at the same time. If you are new to multi-threading, please read the paragraph "Do you need multi-threading?" to determine whether it is really required; this may save you many headaches.
4	4
5	5		One of the threads is called the Main Thread. The Main Thread is the one that is created by the Operating System once our application starts. The Main Thread must be the only thread that updates the components that interfaces with the user: otherwise, the application may hang.
6	6
7	7		The main idea is that the application can do some processing in background in a second thread while the user can continue working using the main thread.
8	8
9	9		Another use of threads is just to have a better responding application. If you create an application, and when the user presses a button the application starts processing a big job... and while processing, the screen stops responding, and gives the user the impression that the application is frozen, a poor or misleading impression will be created. If the big job runs in a second thread, the application keeps responding (almost) as if it were idle. In this case it is a good idea, before starting the thread, to disable the buttons of the form to avoid the user starting more than one thread for the job.
10	10
11	11		Another use of multi-threading may be a server application that is able to respond to many clients at the same time.
12	12
13	13		## Do you need multi-threading?
14	14
15	15		If you are new to multi-threading and you only want to make your application more responsive while your application performs moderately long-running tasks, then multi-threading may be more than is required. Multi-threaded applications are always more difficult to debug and they are often much more complex; in many cases you don't need multi-threading. A single thread is enough. If you can split up the time-consuming task into several smaller chunks, then instead you should use Application.ProcessMessages. This method allows the LCL to handle all waiting messages and returns. The central idea is to call Application.ProcessMessages at regular intervals during the execution of a long-running task to determine whether the user has clicked on something, or a progress indicator must be repainted, and so on.
16	16
17	17		For example: Reading a big file and process it. See examples/multithreading/singlethreadingexample1.lpi.
18	18
19	19		Multi-threading is only needed for
20	20
21	21		- blocking handles, like network communications
22	22		- using multiple processors simultaneously (SMP)
23	23		- algorithms and library calls that must be called through an API and as such cannot be split up into smaller parts.
24	24
25	25		If you want to use multi-threading to increase speed by using multiple processors simultaneously, check if your current program now uses all 100% resources of 1 core CPU (for example, your program can actively use input-output operations, e.g. writing to file; this takes a lot of time, but doesn't load CPU; in this case your program will not be faster with multiple threads). Also check if optimisation level is set to maximum (3). When switching optimisation level from 1 to 3, a program may become about 5 times faster.
26	26
27	27		## Units needed for a multi-threaded application
28	28
29	29		You don´t need any special unit for this to work with Windows. However with Linux, macOS and FreeBSD, you need the cthreads unit and it must be the first used unit of the project (the program source, usually the .lpr file)! In cases where several units like cthreads, cmem and cwstrings are recommended to be placed first, due to how the units work a sensible order is cmem, cthreads and then cwstrings.
30	30
31	31		So, your Lazarus application code should look like:
32	32
33	33		``` pascal
34	34		program MyMultiThreadedProgram;
35	35		{$mode objfpc}{$H+}
36	36		uses
37	37		{$ifdef unix}
38	38		cthreads,
39	39		cmem, // the c memory manager is on some systems much faster for multi-threading
40	40		{$endif}
41	41		Interfaces, // this includes the LCL widgetset
42	42		Forms
43	43		{ you can add units here },
44	44		```
45	45
46	46		If you forget this and you use TThread you will get this error on startup:
47	47
48		-	~~` This binary has no thread support compiled in.`\~~
49		-	~~` Recompile the application with a thread-driver in the program uses clause before other units using thread.`~~
	48	+	``` pascal
	49	+	This binary has no thread support compiled in.
	50	+	Recompile the application with a thread-driver in the program uses clause before other units using thread.
	51	+	```
50	52
51	53		> Note: If you get a Linker error about "mcount" not found. Then you use some unit that contains some multithreaded code and you need to add the cthreads unit or use [[smart linking]].
52	54
53	55		> Note: If you get the error: "Project raised exception class 'RunError(232)'" in procedure SYSTEM_NOTHREADERROR then your code requires threading and you need to add the cthreads unit.
54	56
55	57		## Pure FPC example
56	58
57	59		Below code gives a very simple example. Tested with FPC 3.0.4 on Win7.
58	60
59	61		``` pascal
60	62		Program ThreadTest;
61	63		{test multi threading capability }
62	64		{
63	65		OUTPUT
64	66		thread 1 started
65	67		thread 1 thri 0 Len(S)= 1
66	68		thread 1 thri 1 Len(S)= 2
67	69		thread 1 thri 2 Len(S)= 3
68	70		thread 1 thri 3 Len(S)= 4
69	71		thread 1 thri 4 Len(S)= 5
70	72		thread 1 thri 5 Len(S)= 6
71	73		thread 1 thri 6 Len(S)= 7
72	74		thread 1 thri 7 Len(S)= 8
73	75		thread 1 thri 8 Len(S)= 9
74	76		thread 1 thri 9 Len(S)= 10
75	77		thread 1 thri 10 Len(S)= 11
76	78		thread 1 thri 11 Len(S)= 12
77	79		thread 1 thri 12 Len(S)= 13
78	80		thread 1 thri 13 Len(S)= 14
79	81		thread 1 thri 14 Len(S)= 15
80	82		thread 2 started
81	83		thread 3 started
82	84		thread 1 thri 15 Len(S)= 16
83	85		thread 2 thri 0 Len(S)= 1
84	86		thread 3 thri 0 Len(S)= 1
85	87		thread 1 thri 16 Len(S)= 17
86	88		...
87	89		...
88	90		thread 5 thri 997 Len(S)= 998
89	91		thread 5 thri 998 Len(S)= 999
90	92		thread 5 thri 999 Len(S)= 1000
91	93		thread 5 finished
92	94		thread 10 thri 828 Len(S)= 829
93	95		thread 9 thri 675 Len(S)= 676
94	96		thread 4 thri 656 Len(S)= 657
95	97		thread 10 thri 829 Len(S)= 830
96	98		thread 9 thri 676 Len(S)= 677
97	99		thread 9 thri 677 Len(S)= 678
98	100		thread 10 thri 830 Len(S)= 831
99	101		thread 10 thri 831 Len(S)= 832
100	102		thread 10 thri 832 Len(S)= 833
101	103		thread 10 thri 833 Len(S)= 834
102	104		thread 10 thri 834 Len(S)= 835
103	105		thread 10 thri 835 Len(S)= 836
104	106		thread 10 thri 836 Len(S)= 837
105	107		thread 10 thri 837 Len(S)= 838
106	108		thread 10 thri 838 Len(S)= 839
107	109		thread 10 thri 839 Len(S)= 840
108	110		thread 9 thri 678 Len(S)= 679
109	111		...
110	112		...
111	113		thread 4 thri 994 Len(S)= 995
112	114		thread 4 thri 995 Len(S)= 996
113	115		thread 4 thri 996 Len(S)= 997
114	116		thread 4 thri 997 Len(S)= 998
115	117		thread 4 thri 998 Len(S)= 999
116	118		thread 4 thri 999 Len(S)= 1000
117	119		thread 4 finished
118	120		10
119	121
120	122		}
121	123
122	124		uses
123	125		{$ifdef unix}cthreads, {$endif} sysutils;
124	126
125	127		const
126	128		threadcount = 10;
127	129		stringlen = 1000;
128	130
129	131		var
130	132		finished : longint;
131	133
132	134		threadvar
133	135		thri : ptrint;
134	136
135	137		function f(p : pointer) : ptrint;
136	138		var
137	139		s : ansistring;
138	140		begin
139	141		Writeln('thread ',longint(p),' started');
140	142		thri:=0;
141	143		while (thri<stringlen) do begin
142	144		s:=s+'1'; { create a delay }
143	145		writeln('thread ',longint(p),' thri ',thri,' Len(S)= ',length(s));
144	146		inc(thri);
145	147		end;
146	148		Writeln('thread ',longint(p),' finished');
147	149		InterLockedIncrement(finished);
148	150		f:=0;
149	151		end;
150	152
151	153		var
152	154		i : longint;
153	155
154	156		Begin
155	157		finished:=0;
156	158		for i:=1 to threadcount do
157	159		BeginThread(@f,pointer(i));
158	160		while finished<threadcount do ;
159	161		Writeln(finished);
160	162		End.
161	163		```
162	164
163	165		## The TThread Class
164	166
165	167		The following example can be found in the examples/multithreading/ directory.
166	168
167	169		To create a multi-threaded application, the easiest way is to use the TThread Class. This class permits the creation of an additional thread (alongside the main thread) in a simple way. Normally you are required to override only 2 methods: the Create constructor, and the Execute method.
168	170
169	171		In the constructor, you will prepare the thread to run. You will set the initial values of the variables or properties you need. The original constructor of TThread requires a parameter called Suspended. As you might expect, setting Suspended = True will prevent the thread starting automatically after the creation. If Suspended = False, the thread will start running just after the creation. If the thread is created suspended, then it will run only after the Start method is called.
170	172
171	173		> Note: Method Resume is [deprecated since FPC 2.4.4](http://wiki.freepascal.org/User_Changes_2.4.4#TThread.Suspend_and_TThread.Resume_have_been_deprecated). It is replaced by Start.
172	174
173	175		As of FPC version 2.0.1 and later, TThread.Create also has an implicit parameter for Stack Size. You can now change the default stack size of each thread you create if you need it. Deep procedure call recursions in a thread are a good example. If you don't specify the stack size parameter, a default OS stack size is used.
174	176
175	177		In the overridden Execute method you will write the code that will run on the thread.
176	178
177	179		The TThread class has one important property: Terminated : boolean;
178	180
179	181		If the thread has a loop (and this is typical), the loop should be exited when Terminated is true (it is false by default). Within each pass, the value of Terminated must be checked, and if it is true then the loop should be exited as quickly as is appropriate, after any necessary cleanup. ~~Bear in mind that the Terminate method does not do anything by default: the .Execute method must explicitly implement support for it to quit its job.~~ The Terminate method only sets the Terminated property to True.
180	182
181	183		As we explained earlier, the thread should not interact with the visible components. Updates to visible components must be made within the context of the main thread.
182	184
183	185		To do this, a TThread method called Synchronize exists. Synchronize requires a method within the thread (that takes no parameters) as an argument. When you call that method through Synchronize(@MyMethod), the thread execution will be paused, the code of MyMethod will be called from the main thread, and then the thread execution will be resumed.
184	186
185	187		The exact working of Synchronize depends on the platform, but basically it does this:
186	188
187	189		- it posts a message onto the main message queue and goes to sleep
188	190		- eventually the main thread processes the message and calls MyMethod. This way MyMethod is called without context, that means not during a mouse down event or during paint event, but after.
189	191		- after the main thread executed MyMethod, it wakes the sleeping Thread and processes the next message
190	192		- the Thread then continues.
191	193
192	194		There is another important property of TThread: FreeOnTerminate. If this property is true, the thread object is automatically freed when the thread execution (.Execute method) stops. Otherwise the application will need to free it manually.
193	195
194	196		Example:
195	197
196	198		``` pascal
197	199		Type
198	200		TMyThread = class(TThread)
199	201		private
200	202		fStatusText : string;
201	203		procedure ShowStatus;
202	204		protected
203	205		procedure Execute; override;
204	206		public
205	207		Constructor Create(CreateSuspended : boolean);
206	208		end;
207	209		constructor TMyThread.Create(CreateSuspended : boolean);
208	210		begin
209	211		inherited Create(CreateSuspended);
210	212		FreeOnTerminate := True;
211	213		end;
212	214
213	215		procedure TMyThread.ShowStatus;
214	216		// this method is executed by the mainthread and can therefore access all GUI elements.
215	217		begin
216	218		Form1.Caption := fStatusText;
217	219		end;
218	220
219	221		procedure TMyThread.Execute;
220	222		var
221	223		newStatus : string;
222	224		begin
223	225		fStatusText := 'TMyThread Starting...';
224	226		Synchronize(@Showstatus);
225	227		fStatusText := 'TMyThread Running...';
226	228		while (not Terminated) and ([any condition required]) do
227	229		begin
228	230		...
229	231		[here goes the code of the main thread loop]
230	232		...
231	233		if NewStatus <> fStatusText then
232	234		begin
233	235		fStatusText := newStatus;
234	236		Synchronize(@Showstatus);
235	237		end;
236	238		end;
237	239		end;
238	240		```
239	241
240	242		In the application:
241	243
242	244		``` pascal
243	245		var
244	246		MyThread : TMyThread;
245	247		begin
246	248		MyThread := TMyThread.Create(True); // This way it doesn't start automatically
247	249		...
248	250		[Here the code initialises anything required before the threads starts executing]
249	251		...
250	252		MyThread.Start;
251	253		end;
252	254		```
253	255
254	256		If you want to make your application more flexible you can create an event for the thread; this way your synchronized method won't be tightly coupled with a specific form or class: you can attach listeners to the thread's event. Here is an example:
255	257
256	258		``` pascal
257	259		Type
258	260		TShowStatusEvent = procedure(Status: String) of Object;
259	261
260	262		TMyThread = class(TThread)
261	263		private
262	264		fStatusText : string;
263	265		FOnShowStatus: TShowStatusEvent;
264	266		procedure ShowStatus;
265	267		protected
266	268		procedure Execute; override;
267	269		public
268	270		Constructor Create(CreateSuspended : boolean);
269	271		property OnShowStatus: TShowStatusEvent read FOnShowStatus write FOnShowStatus;
270	272		end;
271	273
272	274		constructor TMyThread.Create(CreateSuspended : boolean);
273	275		begin
274	276		inherited Create(CreateSuspended);
275	277		FreeOnTerminate := True;
276	278		end;
277	279
278	280		procedure TMyThread.ShowStatus;
279	281		// this method is executed by the mainthread and can therefore access all GUI elements.
280	282		begin
281	283		if Assigned(FOnShowStatus) then
282	284		begin
283	285		FOnShowStatus(fStatusText);
284	286		end;
285	287		end;
286	288
287	289		procedure TMyThread.Execute;
288	290		var
289	291		newStatus : string;
290	292		begin
291	293		fStatusText := 'TMyThread Starting...';
292	294		Synchronize(@Showstatus);
293	295		fStatusText := 'TMyThread Running...';
294	296		while (not Terminated) and ([any condition required]) do
295	297		begin
296	298		...
297	299		[here goes the code of the main thread loop]
298	300		...
299	301		if NewStatus <> fStatusText then
300	302		begin
301	303		fStatusText := newStatus;
302	304		Synchronize(@Showstatus);
303	305		end;
304	306		end;
305	307		end;
306	308		```
307	309
308	310		In the application:
309	311
310	312		``` pascal
311	313		Type
312	314		TForm1 = class(TForm)
313	315		Button1: TButton;
314	316		Label1: TLabel;
315	317		procedure FormCreate(Sender: TObject);
316	318		procedure FormDestroy(Sender: TObject);
317	319		private
318	320		{ private declarations }
319	321		MyThread: TMyThread;
320	322		procedure ShowStatus(Status: string);
321	323		public
322	324		{ public declarations }
323	325		end;
324	326
325	327		procedure TForm1.FormCreate(Sender: TObject);
326	328		begin
327	329		inherited;
328	330		MyThread := TMyThread.Create(true);
329	331		MyThread.OnShowStatus := @ShowStatus;
330	332		end;
331	333
332	334		procedure TForm1.FormDestroy(Sender: TObject);
333	335		begin
334	336		MyThread.Terminate;
335	337
336	338		// FreeOnTerminate is true so we should not write:
337	339		// MyThread.Free;
338	340		inherited;
339	341		end;
340	342
341	343		procedure TForm1.Button1Click(Sender: TObject);
342	344		begin
343	345		MyThread.Start;
344	346		end;
345	347
346	348		procedure TForm1.ShowStatus(Status: string);
347	349		begin
348	350		Label1.Caption := Status;
349	351		end;
350	352		```
351	353
352	354		## Special things to take care of
353	355
354	356		### Stack checking under Windows
355	357
356	358		There is a potential headache in Windows with Threads if you use the -Ct (stack check) switch. For reasons not so clear the stack check will "trigger" on any TThread.Create if you use the default stack size. The only work-around for the moment is to simply not use -Ct switch. Note that it does NOT cause an exception in the main thread, but in the newly created one. This "looks" like if the thread was never started.
357	359
358	360		A good code to check for this and other exceptions which can occur in thread creation is:
359	361
360	362		``` pascal
361	363		MyThread := TThread.Create(False);
362	364
363	365		if Assigned(MyThread.FatalException) then
364	366		raise MyThread.FatalException;
365	367		```
366	368
367	369		This code will assure that any exception which occurred during thread creation will be raised in your main thread.
368	370
369	371		### GetDC function in Windows
370	372
371	373		The GetDC (and GetDCEx) function retrieves a handle to a device context (DC) for the client area of a specified window or for the entire screen. It can be used, for example, to [[Developing with Graphics\|take a screenshot]]. Note however that it is not thread safe: the handle to the DC can only be used by a single thread at any one time as [documented here](https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-getdc).
372	374
373	375		### Multithreading in packages
374	376
375	377		Packages which uses multi-threading should add the -dUseCThreads flag to the custom usage options. Open the package editor of the package, then Options \> Usage \> Custom and add -dUseCThreads. This will define this flag to all projects and packages using this package, including the IDE. The IDE and all new applications created by the IDE have already the following code in their .lpr file:
376	378
377	379		``` pascal
378	380		uses
379	381		{$IFDEF UNIX}{$IFDEF UseCThreads}
380	382		cthreads,
381	383		cmem, // the c memory manager is on some systems much faster for multi-threading
382	384		{$ENDIF}{$ENDIF}
383	385		```
384	386
385	387		### Heaptrc
386	388
387	389		You can not use the -gh switch with the cmem unit. The -gh switch uses the heaptrc unit, which extends the heap manager. Therefore the heaptrc unit must be used after the cmem unit.
388	390
389	391		``` pascal
390	392		uses
391	393		{$IFDEF UNIX}{$IFDEF UseCThreads}
392	394		cthreads,
393	395		cmem, // the c memory manager is on some systems much faster for multi-threading
394	396		{$ENDIF}{$ENDIF}
395	397		heaptrc,
396	398		```
397	399
398	400		### Initialization and Finalization
399	401
400	402		To initialize the thread object itself, you can either start it suspended and set its properties and/or create a new constructor and call the inherited constructor.
401	403
402	404		Note: Using the AfterConstruction when CreateSuspended=false is dangerous, as the thread has already started.
403	405
404	406		On the other hand, the destructor may be used to finalize the object's resources.
405	407
406	408		``` pascal
407	409		type
408	410		TMyThread = class(TThread)
409	411		private
410	412		fRTLEvent: PRTLEvent;
411	413		public
412	414		constructor Create(SomeData: TSomeObject; CreateSuspended: boolean);
413	415		destructor Destroy; override;
414	416		end;
415	417
416	418		constructor TMyThread.Create(SomeData: TSomeObject; CreateSuspended: boolean);
417	419		begin
418	420		// example: set up events, critical sections and other ressources like files or database connections
419	421		RTLEventCreate(fRTLEvent);
420	422		inherited Create(CreateSuspended);
421	423		end;
422	424
423	425		destructor TMyThread.Destroy;
424	426		begin
425	427		RTLeventDestroy(fRTLEvent);
426	428		inherited Destroy;
427	429		end;
428	430		```
429	431
430	432		### Non LCL program
431	433
432	434		TThread.Synchronize requires that the main thread regularly calls CheckSynchronize. The LCL does that in its loop. If you don't use the LCL event loop you must call it yourself.
433	435
434	436		## SMP Support
435	437
436	438		The good news is that if your application works properly multi-threaded this way, it is already SMP enabled!
437	439
438	440		## Debugging Multi-threaded Applications with Lazarus
439	441
440	442		The debugging on Lazarus requires GDB and is rapidly becoming more and more fully featured and stable. However, there still exists a few Linux distributions with some problems.
441	443
442	444		### Debugging output
443	445
444	446		In a single threaded application, you can simply write to console/terminal/whatever and the order of the lines is the same as they were written. In multi-threaded application things are more complicated. If two threads are writing, say a line is written by thread A before a line by thread B, then the lines are not necessarily written in that order. It can even happen, that a thread writes its output, while the other thread is writing a line.While under linux (maybe) you'll get proper [[DebugLn]]() output, under win32 you can get exceptions (probably DiskFull) because of DebugLn() usage outside of main thread.So, to avoid headaches use DebugLnThreadLog() mentioned below.
445	447
446	448		The LCLProc unit contains several functions, to let each thread write to its own log file:
447	449
448	450		``` pascal
449	451		procedure DbgOutThreadLog(const Msg: string); overload;
450	452		procedure DebuglnThreadLog(const Msg: string); overload;
451	453		procedure DebuglnThreadLog(Args: array of const); overload;
452	454		procedure DebuglnThreadLog; overload;
453	455		```
454	456
455	457		For example: Instead of writeln('Some text ',123); use
456	458
457		-	~~` DebuglnThreadLog(['Some text ',123]);`~~
	459	+	```text
	460	+	DebuglnThreadLog(['Some text ',123]);
	461	+	```
458	462
459	463		This will append a line 'Some text 123' to Log\<PID\>.txt, where \<PID\> is the process ID of the current thread.
460	464
461	465		It is a good idea to remove the log files before each run:
462	466
463		-	~~` rm -f Log* && ./project1`~~
	467	+	```text
	468	+	rm -f Log* && ./project1
	469	+	```
464	470
465	471		### Linux
466	472
467	473		If you try to debug a multi-threaded application on Linux, you will have one big problem: the Desktop Manager on X server can hang. This happens for instance when the application has captured the mouse/keyboard and was paused by gdb and the X server waits for your application. When that happens you can simply log in from another computer and kill the gdb or exit out of that session by pressing CTRL+ALT+F3 and kill gdb. Alternatively you can restart the window manager: enter sudo /etc/init.d/gdm restart. This will restart the desktop manager and get you back into your desktop.
468	474
469	475		Since it depends where gdb stops your program in some cases some tricks may help: for Ubuntu x64 set the Project options for debugging required extra information file...
470	476
471		-	~~` Project Options -> Compiler Options -> Linking -> Debugging: Check Use external gdb debug symbols file (-Xg).`~~
	477	+	```text
	478	+	Project Options -> Compiler Options -> Linking -> Debugging: Check Use external gdb debug symbols file (-Xg).
	479	+	```
472	480
473	481		The other option is to open another X desktop, run the IDE/gdb on one and the application on the other, so that only the test desktop freezes. Create a new instance of X with:
474	482
475		-	~~` X :1 &`~~
	483	+	```text
	484	+	X :1 &
	485	+	```
476	486
477	487		It will open, and when you switch to another desktop (the one you are working with pressing CTRL+ALT+F7), you will be able to go back to the new graphical desktop with CTRL+ALT+F8 (if this combination does not work, try with CTRL+ALT+F2... this one worked on [Slackware](http://www.slackware.com)).
478	488
479	489		Then you could, if you want, create a desktop session on the X started with:
480	490
481		-	~~` gnome-session --display=:1 &`~~
	491	+	```text
	492	+	gnome-session --display=:1 &
	493	+	```
482	494
483	495		Then, in Lazarus, on the run parameters dialog for the project, check "Use display" and enter :1.
484	496
485	497		Now the application will run on the second X server and you will be able to debug it on the first one.
486	498
487	499		This was tested with Free Pascal 2.0 and Lazarus 0.9.10 on Windows and Linux.
488	500
489	501		------------------------------------------------------------------------
490	502
491	503		Instead of creating a new X session, one can use [Xnest](http://en.wikipedia.org/wiki/Xnest). Xnest is a X session on a window. Using it X server didn't lock while debugging threads, and it's much easier to debug without keeping changing terminals.
492	504
493	505		The command line to run Xnest is
494	506
495		-	~~` Xnest :1 -ac`~~
	507	+	```text
	508	+	Xnest :1 -ac
	509	+	```
496	510
497	511		to create a X session on :1, and disabling access control.
498	512
499	513		## Lazarus Widgetset Interfaces
500	514
501	515		The win32, the gtk and the carbon interfaces support multi-threading. This means, TThread, critical sections and Synchronize work. But they are not thread safe. This means only one thread at a time can access the LCL. And since the main thread should never wait for another thread, it means only the main thread is allowed to access the LCL, which means anything that has to do with TControl, Application and LCL widget handles. There are some thread safe functions in the LCL. For example most of the functions in the FileUtil unit are thread safe.
502	516
503	517		### Using SendMessage/PostMessage to communicate between threads
504	518
505	519		Only one thread in an application should call LCL APIs, usually the main thread. Other threads can make use of the LCL through a number of indirect methods, one good option being the usage of SendMessage or PostMessage. LCLIntf.SendMessage and LCLIntf.PostMessage will post a message directed to a window in the message pool of the application.
506	520
507	521		See also the documentation for these routines:
508	522
509	523		- [[doc:lcl/lclintf/sendmessage.html\|SendMessage]]
510	524		- [[doc:lcl/lclintf/postmessage.html\|PostMessage]]
511	525
512	526		The difference between SendMessage and PostMessage is the way that they return control to the calling thread. Like Synchronize, SendMessage blocks and control is not returned until the window that the message was sent to has completed processing it; however under certain circumstances SendMessage might attempt to optimise processing by remaining in the context of the thread that called it. With PostMessage control is returned immediately up to some system-defined maximum number of enqueued messages and as long as space remains on the heap for attached data.
513	527
514	528		In both cases the procedure handling the message (see below) should avoid calling application.ProcessMessages, since this might cause a second message to be dispatched which will be handled reentrantly. If this is unavoidable then it would probably be preferable to use some other mechanism to transfer serialised events between threads.
515	529
516	530		Here is an example of how a secondary thread could send text to be displayed in an LCL control to the main thread:
517	531
518	532		``` pascal
519	533		const
520	534		WM_GOT_ERROR = LM_USER + 2004;
521	535		WM_VERBOSE = LM_USER + 2005;
522	536
523	537		procedure VerboseLog(Msg: string);
524	538		var
525	539		PError: PChar;
526	540		begin
527	541		if MessageHandler = 0 then Exit;
528	542		PError := StrAlloc(Length(Msg)+1);
529	543		StrCopy(PError, PChar(Msg));
530	544		PostMessage(formConsole.Handle, WM_VERBOSE, Integer(PError), 0);
531	545		end;
532	546		```
533	547
534	548		And an example of how to handle this message from a window:
535	549
536	550		``` pascal
537	551		const
538	552		WM_GOT_ERROR = LM_USER + 2004;
539	553		WM_VERBOSE = LM_USER + 2005;
540	554
541	555		type
542	556		{ TformConsole }
543	557
544	558		TformConsole = class(TForm)
545	559		DebugList: TListView;
546	560		// ...
547	561		private
548	562		procedure HandleDebug(var Msg: TLMessage); message WM_VERBOSE;
549	563		end;
550	564
551	565		var
552	566		formConsole: TformConsole;
553	567
554	568		implementation
555	569
556	570		....
557	571
558	572		{ TformConsole }
559	573
560	574		procedure TformConsole.HandleDebug(var Msg: TLMessage);
561	575		var
562	576		Item: TListItem;
563	577		MsgStr: PChar;
564	578		MsgPasStr: string;
565	579		begin
566	580		MsgStr := PChar(Msg.wparam);
567	581		MsgPasStr := StrPas(MsgStr);
568	582		Item := DebugList.Items.Add;
569	583		Item.Caption := TimeToStr(SysUtils.Now);
570	584		Item.SubItems.Add(MsgPasStr);
571	585		Item.MakeVisible(False);
572	586
573	587		// Followed by something like
574	588
575	589		TrayControl.SetError(MsgPasStr);
576	590		StrDispose(MsgStr)
577	591		end;
578	592
579	593		end.
580	594		```
581	595
582	596		When you get on the Linux x64 machine an error: "Project XY raised exception class 'External: SIGSEGV'" you have to change "Integer(PError)" to "PtrInt(PError)" in procedure "VerboseLog". Modified line have to look like:
583	597
584		-	~~` PostMessage(formConsole.Handle, WM_VERBOSE, PtrInt(PError), 0);`~~
	598	+	```text
	599	+	PostMessage(formConsole.Handle, WM_VERBOSE, PtrInt(PError), 0);
	600	+	```
585	601
586	602		## Critical sections
587	603
588	604		A critical section is an object used to make sure, that some part of the code is executed only by one thread at a time. A critical section needs to be created/initialized before it can be used and be freed when it is not needed anymore.
589	605
590	606		There are two ways you use critical sections, from the RTL or from LCL. The text below shows the RTL model and shows the LCL alternatives as a comment, the only difference is the method names.
591	607
592	608		Critical sections are normally used this way:
593	609
594	610		``` pascal
595	611		// uses LCLIntf, LCLType;
596	612		```
597	613
598	614		the necessary RTL units will almost certainly already be mentioned.
599	615
600	616		Declare the section (globally for all threads which should access the section):
601	617
602	618		``` pascal
603	619		MyCriticalSection: TRTLCriticalSection;
604	620		// MyCriticalSection : TCriticalSection;
605	621		```
606	622
607	623		Create the section:
608	624
609	625		``` pascal
610	626		InitCriticalSection(MyCriticalSection);
611	627		//InitializeCriticalSection(MyCriticalSection);
612	628		```
613	629
614	630		Run some threads. Doing something exclusively:
615	631
616	632		``` pascal
617	633		EnterCriticalSection(MyCriticalSection);
618	634		try
619	635		// access some variables, write files, send some network packets, etc
620	636		finally
621	637		LeaveCriticalSection(MyCriticalSection);
622	638		end;
623	639		// RTL and LCL use same syntax, thats nice.
624	640		```
625	641
626	642		After all threads terminated, free it:
627	643
628	644		``` pascal
629	645		DoneCriticalSection(MyCriticalSection);
630	646		// DeleteCriticalSection(MyCriticalSection);
631	647		```
632	648
633	649		As an alternative, you can use a TCriticalSection object. The creation does the initialization, the Enter method does the EnterCriticalSection, the Leave method does the LeaveCriticalSection and the destruction of the object does the deletion.
634	650
635	651		Note that a critical section does not protect against the same thread entering the same block of code, only against different threads. For that reason it cannot be used to protect against e.g. reentry of a message handler (see the section above).
636	652
637	653		For example: 5 threads incrementing a counter. See lazarus/examples/multithreading/criticalsectionexample1.lpi
638	654
639	655		> Warning: There are two sets of the above four functions. The RTL and the LCL ones. The LCL ones are defined in the unit LCLIntf and LCLType. Both work pretty much the same. You can use both at the same time in your application, but you should not use a RTL function within an LCL Critical Section and vice versa.
640	656
641	657		### Sharing Variables
642	658
643	659		If some threads share a variable, that is read only, then there is nothing to worry about. Just read it. But if one or several threads changes the variable, then you must make sure, that only one thread accesses the variables at a time.
644	660
645	661		For example: 5 threads incrementing a counter. See lazarus/examples/multithreading/criticalsectionexample1.lpi
646	662
647	663		## Waiting for another thread
648	664
649	665		If a thread A needs a result of another thread B, it must wait, till B has finished.
650	666
651	667		Important: The main thread should never wait for another thread. Instead use Synchronize (see above).
652	668
653	669		See for an example: lazarus/examples/multithreading/waitforexample1.lpi
654	670
655	671		``` pascal
656	672		{ TThreadA }
657	673
658	674		procedure TThreadA.Execute;
659	675		begin
660	676		Form1.ThreadB:=TThreadB.Create(false);
661	677		// create event
662	678		WaitForB:=RTLEventCreate;
663	679		while not Application.Terminated do begin
664	680		// wait infinitely (until B wakes A)
665	681		RtlEventWaitFor(WaitForB);
666	682		writeln('A: ThreadB.Counter='+IntToStr(Form1.ThreadB.Counter));
667	683		end;
668	684		end;
669	685
670	686		{ TThreadB }
671	687
672	688		procedure TThreadB.Execute;
673	689		var
674	690		i: Integer;
675	691		begin
676	692		Counter:=0;
677	693		while not Application.Terminated do begin
678	694		// B: Working ...
679	695		Sleep(1500);
680	696		inc(Counter);
681	697		// wake A
682	698		RtlEventSetEvent(Form1.ThreadA.WaitForB);
683	699		end;
684	700		end;
685	701		```
686	702
687	703		> Note: RtlEventSetEvent can be called before RtlEventWaitFor. Then RtlEventWaitFor will return immediately. Use RTLeventResetEvent to clear a flag.
688	704
689	705		## Fork
690	706
691	707		When forking in a multi-threaded application, be aware that any threads created and running BEFORE the fork (or fpFork) call, will NOT be running in the child process. As stated on the fork() man page, any threads that were running before the fork call, their state will be undefined.
692	708
693	709		So be aware of any threads initializing before the call (including on the initialization section). They will NOT work.
694	710
695	711		## Parallel procedures/loops
696	712
697	713		A special case of multi threading is running a single procedure in parallel. See [[Parallel procedures]].
698	714
699	715		## Distributed computing
700	716
701	717		The next higher steps after multi threading is running the threads on multiple machines.
702	718
703	719		- You can use one of the TCP suites like synapse, lnet or indy for communications. This gives you maximum flexibility and is mostly used for loosely connected Client / Server applications.
704	720		- You can use message passing libraries like [[MPICH]], which are used for HPC (High Performance Computing) on clusters.
705	721
706	722		## External threads
707	723
708	724		To make Free Pascal's threading system work properly, each newly created FPC thread needs to be initialized (more exactly, the exception, I/O system and threadvar system per thread needs to be initialized so threadvars and heap are working). That is fully automatically done for you if you use BeginThread (or indirectly by using the TThread class). However, if you use threads that were created without BeginThread (i.e. external threads), additional work (currently) might be required. External threads also include those that were created in external C libraries (.DLL/.so).
709	725
710	726		Things to consider when using external threads (might not be needed in all or future compiler versions):
711	727
712	728		- Do not use external threads at all - use FPC threads. If can you can get control over how the thread is created, create the thread by yourself by using BeginThread.
713	729
714	730		If the calling convention doesn't fit (e.g. if your original thread function needs cdecl calling convention but BeginThread needs pascal convention, create a record, store the original required thread function in it, and call that function in your pascal thread function:
715	731
716	732		``` pascal
717	733		type
718	734		TCdeclThreadFunc = function (user_data:Pointer):Pointer;cdecl;
719	735
720	736		PCdeclThreadFuncData = ^TCdeclThreadFuncData;
721	737		TCdeclThreadFuncData = record
722	738		Func: TCdeclThreadFunc; //cdecl function
723	739		Data: Pointer; //original data
724	740		end;
725	741
726	742		// The Pascal thread calls the cdecl function
727	743		function C2P_Translator(FuncData: pointer) : ptrint;
728	744		var
729	745		ThreadData: TCdeclThreadFuncData;
730	746		begin
731	747		ThreadData := PCdeclThreadFuncData(FuncData)^;
732	748		Result := ptrint(ThreadData.Func(ThreadData.Data));
733	749		end;
734	750
735	751		procedure CreatePascalThread;
736	752		var
737	753		ThreadData: PCdeclThreadFuncData;
738	754		begin
739	755		New(ThreadData);
740	756		// this is the desired cdecl thread function
741	757		ThreadData^.Func := func;
742	758		ThreadData^.Data := user_data;
743	759		// this creates the Pascal thread
744	760		BeginThread(@C2P_Translator, ThreadData );
745	761		end;
746	762		```
747	763
748	764		- Initialize the FPC's threading system by creating a dummy thread. If you don't create any Pascal thread in your app, the thread system won't be initialized (and thus threadvars won't work and thus heap will not work correctly).
749	765
750	766		``` pascal
751	767		type
752	768		tc = class(tthread)
753	769		procedure execute;override;
754	770		end;
755	771
756	772		procedure tc.execute;
757	773		begin
758	774		end;
759	775
760	776		{ main program }
761	777		begin
762	778		{ initialise threading system }
763	779		with tc.create(false) do
764	780		begin
765	781		waitfor;
766	782		free;
767	783		end;
768	784		{ ... your code follows }
769	785		end.
770	786		```
771	787
772	788		(After the threading system is initialized, the runtime may set the system variable "IsMultiThread" to true which is used by FPC routines to perform locks here and there. You should not set this variable manually.)
773	789
774	790		- If for some reason this doesn't work for you, try this code in your external thread function:
775	791
776	792		``` pascal
777	793		function ExternalThread(param: Pointer): LongInt; stdcall;
778	794		var
779	795		tm: TThreadManager;
780	796		begin
781	797		GetThreadManager(tm);
782	798		tm.AllocateThreadVars;
783	799		InitThread(1000000); // adjust inital stack size here
784	800
785	801		{ do something threaded here ... }
786	802
787	803		Result:=0;
788	804		end;
789	805		```
790	806
791	807		### Identifying external threads
792	808
793	809		Sometimes you even don't know if you have to deal with external threads (eg if some C library makes a [[callback]]). This can help to analyse this:
794	810
795	811		1\. Ask the OS for the ID of the current thread at your application's start
796	812
797	813		``` pascal
798	814		GetCurrentThreadID() // Windows;
799	815		GetThreadID() // Darwin (macOS); FreeBSD;
800	816		TThreadID(pthread_self) // Linux;
801	817		```
802	818
803	819		2\. Ask again for the ID of the current thread inside the thread function and compare this with the result of step 1.
804	820
805	821		### Give up some time slice
806	822
807	823		[ThreadSwitch](https://www.freepascal.org/docs-html/rtl/system/threadswitch.html) - Note: may be ignored.
808	824
809	825		> Note: Do not use the Windows trick [Sleep(0)](https://www.freepascal.org/docs-html/rtl/sysutils/sleep.html) as this won't work on all platforms.
810	826
811	827		## See also
812	828
813	829		- [[Streaming components]]
814	830		- [[Manager Worker Threads System]]
815	831		- [[Example of multi-threaded application: array of threads]]
816	832		- [[Parallel procedures]]
817	833		- [[Main Loop Hooks]]
818	834		- [[Asynchronous Calls]]
819	835		- [A forum discussion](https://forum.lazarus.freepascal.org/index.php/topic,55164.0.html) - useful background, why you should almost certainly not access LCL items from within a thread and what you can, safely access.
820	836		- [Mutlithreading - The Delphi way](http://nickhodges.com/MultiThreadingInDelphi/ToC.html)
821	837		- [Synchronizing Threads and GUI in a Delphi Application](https://www.thoughtco.com/synchronizing-threads-and-gui-delphi-application-1058159)
822	838		- [Introduction to thread programming in Lazarus](https://www.freepascal.org/~michael/articles/lazthread/lazthread.pdf) - handout given by Michael Van Canneyt
823	839
824	840		---
825	841		From the Free Pascal wiki, page "Multithreaded Application Tutorial", as it stood on 2024-02-28 after a change by Ernesto, 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).

Back to history