Multithreaded Application Tutorial/zh CN: what changed

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

Old	New		Line
1	1		## 概述
2	2
3	3		这个页面将试图解释如何在Free Pascal 和 Lazarus上编写和调试一个多线程应用程序。一个多线程应用程序创建两个或多个线程同时执行任务。如果你正需要使用多线程，请阅读"你需要多线程吗?"，以确定你是否真的需要；这可以避免些麻烦。
4	4
5	5		程序中的一个线程被称为主线程，也就是在应用程序启动时由操作系统创建的那个线程。主线程是唯一一个可以更新用户界面组件的线程，否则，应用程序可能会挂起。
6	6
7	7		其主要思想是：应用程序使用第二个线程在后台处其他事情，同时用户可以继续使用主线程工作。
8	8
9	9		线程的另一个用途是为了更好的响应应用程序。如，你创建了一个应用程序，在应用程序启动时，用户按下按钮启动一个大的任务……处理中……之后，程序停止响应，这让用户觉得应用程序假死了，在用户体验上这很不好。如果大的任务在另一个线程中运行，应用程序保持响应，它就像在闲置，在本例中它是个不错的选择。不过，在启用线程之前，你需要禁用表单按钮，以避用户启动多个线程。
10	10
11	11		还有，服务器应用程序在使用多线程后，它能够同时响应多个客户端的请求。
12	12
13	13		## 你需要多线程吗?
14	14
15	15		如果你刚想使用多线程，而只是想让你的应用程序长时间运行任务而不失去响应，那么，多线程可能超过你的需要。多线程应用程序难以调试并且很复杂，多数情况下你不需要多线程。单线程就足够了。如果你能将耗时的任务分隔成几块，并使用Application.ProcessMessages。这种方法让LCL处理所有等待的消息并返回。其核心是，在长时间运行任务时定期调用Application.ProcessMessages以处理用户点击了什么东西，或者重绘进度条等等。
16	16
17	17		例如：读取一个大文件并处理它。参看 examples/multithreading/singlethreadingexample1.lpi。
18	18
19	19		使用多线程
20	20
21	21		- blocking handles, like network communications(~~屏蔽处理,比如网络通信~~)
22	22		- 同时使用多个处理器 (SMP)
23	23		- 算法和库调用，必须通过一个 API 调用，如不能被分解成更小的部分。
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		~~你想使用多线程使用多个处理器来提高速度，检查当前程序使用1个核心的CPU上的100%资源（如，你的程序可以积极使用输入输出操作，如写入文件等等，这需要大量时间，但CPU没有负载；在这种情况下，你的程序将不会比多种线程快。）检查优化级别设置为最大(3)。切换优化级别1到3，程序运行可能会快5倍。~~
28	28
29	29		## 多线程单元
30	30
31	31		在Windows上你不需要任何特殊单元。
32	32
33	33		然而在Linux、Mac OS X和FreeBSD上,你需要cthreads单元，并且，必须项目中第一个引入的单元（项目源文件，通常是 .lpr文件）！
34	34
35	35		所以，你的Lazarus应用程序代码看起来应该是：
36	36
37	37		``` pascal
38	38		program MyMultiThreadedProgram;
39	39		{$mode objfpc}{$H+}
40	40		uses
41	41		{$ifdef unix}
42	42		cthreads,
43	43		cmem, // the c memory manager is on some systems much faster for multi-threading(C内存管理器在某些系统中使多线程运行更快)
44	44		{$endif}
45	45		Interfaces, // this includes the LCL widgetset 引入LCL 部件工具箱
46	46		Forms
47	47		{ you can add units here },
48	48		```
49	49
50	50		如果你忘记了这一点，使用TThread启动应用程序时，你会得到这样的错误：
51	51
52		-	~~` This binary has no thread support compiled in. (`~~`二进制文件编译时没有线程支持`~~`)`\~~
53		-	~~` Recompile the application with a thread-driver in the program uses clause before other units using thread.(`~~`在引用线程单元前引用了其他单元`~~`)`~~
	52	+	``` pascal
	53	+	This binary has no thread support compiled in. (<strike>二进制文件编译时没有线程支持</strike>)
	54	+	Recompile the application with a thread-driver in the program uses clause before other units using thread.(<strike>在引用线程单元前引用了其他单元</strike>)
	55	+	```
54	56
55	57		> Note: 提示"mcount"未找到的错误。在你的单元里包含了多线程代码，你需要添加 cthreads单元或使用智能链接。
56	58
57	59		> Note: "Project raised exception class 'RunError(232)'" in procedure SYSTEM_NOTHREADERROR (项目引发的异常类)错误，你的代码里需要线程，你需要添加 cthreads单元。
58	60
59	61		## TThread类
60	62
61	63		下面的例子可以在 examples/multithreading/ 目录中找到。
62	64
63	65		若要创建一个多线程的应用程序，最简单的方法是使用 TThread 类。This class permits the creation of an additional thread (alongside the main thread) in a simple way.(~~这个线程允许在主线程上创建一个附加线程)。~~)通常你只需要重写 2 个方法：创建构造函数（constructor）和执行方法（Execute）。
64	66
65	67		在构造函数中，设置线程运行前初始化需要的变量，在TThread原始构造函数中有一参数Suspended，设置Suspended = True防止在创建后自动启动线程。设置为False，则在在调用Start方法后才执行。
66	68
67	69		> Note: 方法摘要在：[自FPC 2.4.4 弃用](http://wiki.freepascal.org/User_Changes_2.4.4#TThread.Suspend_and_TThread.Resume_have_been_deprecated)。它被Start代替。
68	70
69	71		FPC 2.0.1及更高版本，TThread.Create有一个隐含的堆栈大小参数。根据需要，你可以改变默认堆栈的大小。深层递归过程是个很好的例子。如果你不指定堆栈大小，将使用系统默认的大小。
70	72
71	73		重写Execute方法，编写将在线程中执行的代码。
72	74
73	75		TThread 类有一个重要属性：
74	76
75		-	~~`Terminated : boolean;`~~
	77	+	```text
	78	+	Terminated : boolean;
	79	+	```
76	80
77	81		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.
78	82
79	83		(~~如果线程中包含循环（这是典型的），当 Terminated 为True时退出循环（默认为 False）。每次循环都将检查 Terminated值，如果为真将退出循环，之后做些必要的清理。牢记 Terminate方法不做任何事情，默认情况下：.Execute 方法实现退出循环后的操作。~~)
80	84
81	85		如上所述，线程不应该与可见组件交互，对可见组件操作应该在主线程的上下文中进行。
82	86
83	87		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.
84	88
85	89		(~~要这样做，可以在TThread 方法调用Synchronize。以同步线程中的方法（不带参数）作为参数。当你调用Synchronize(@MyMethod)，线程将暂停执行，并从主线程中调用MyMethod，之后线程恢复。~~)
86	90
87	91		The exact working of Synchronize depends on the platform, but basically it does this: (~~同步的具体工作取决于平台，它基本上是：~~)
88	92
89	93		- 发送消息到主消息队列并进入睡眠
90	94		- 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.
91	95		- 主线程执行 MyMethod后，唤醒睡眠的线程和下条消息
92	96		- 之后，线程继续执行
93	97
94	98		另外，还有一重要属性： TThread: FreeOnTerminate。为True时，线程停止(.Execute 方法)后自动释放。否则，需要手动释放。
95	99
96	100		示例：
97	101
98	102		``` pascal
99	103		Type
100	104		TMyThread = class(TThread)
101	105		private
102	106		fStatusText : string;
103	107		procedure ShowStatus;
104	108		protected
105	109		procedure Execute; override;
106	110		public
107	111		Constructor Create(CreateSuspended : boolean);
108	112		end;
109	113
110	114		constructor TMyThread.Create(CreateSuspended : boolean);
111	115		begin
112	116		FreeOnTerminate := True;
113	117		inherited Create(CreateSuspended);
114	118		end;
115	119
116	120		procedure TMyThread.ShowStatus;
117	121		// this method is executed by the mainthread and can therefore access all GUI elements.
118	122		begin
119	123		Form1.Caption := fStatusText;
120	124		end;
121	125
122	126		procedure TMyThread.Execute;
123	127		var
124	128		newStatus : string;
125	129		begin
126	130		fStatusText := 'TMyThread Starting...';
127	131		Synchronize(@Showstatus);
128	132		fStatusText := 'TMyThread Running...';
129	133		while (not Terminated) and ([any condition required]) do
130	134		begin
131	135		...
132	136		[here goes the code of the main thread loop]
133	137		...
134	138		if NewStatus <> fStatusText then
135	139		begin
136	140		fStatusText := newStatus;
137	141		Synchronize(@Showstatus);
138	142		end;
139	143		end;
140	144		end;
141	145		```
142	146
143	147		在应用程序中，
144	148
145	149		``` pascal
146	150		var
147	151		MyThread : TMyThread;
148	152		begin
149	153		MyThread := TMyThread.Create(True); // This way it doesn't start automatically
150	154		...
151	155		[Here the code initialises anything required before the threads starts executing]
152	156		...
153	157		MyThread.Start;
154	158		end;
155	159		```
156	160
157	161		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:
158	162
159	163		(~~如果想使你的应用更加灵活，可以创建一个事件的线程；这样一来,synchronized方法将不会被特定窗体或类紧耦合：你可以监听线程的事件。~~)
160	164
161	165		下面是一个例子：
162	166
163	167		``` pascal
164	168		Type
165	169		TShowStatusEvent = procedure(Status: String) of Object;
166	170
167	171		TMyThread = class(TThread)
168	172		private
169	173		fStatusText : string;
170	174		FOnShowStatus: TShowStatusEvent;
171	175		procedure ShowStatus;
172	176		protected
173	177		procedure Execute; override;
174	178		public
175	179		Constructor Create(CreateSuspended : boolean);
176	180		property OnShowStatus: TShowStatusEvent read FOnShowStatus write FOnShowStatus;
177	181		end;
178	182
179	183		constructor TMyThread.Create(CreateSuspended : boolean);
180	184		begin
181	185		FreeOnTerminate := True;
182	186		inherited Create(CreateSuspended);
183	187		end;
184	188
185	189		procedure TMyThread.ShowStatus;
186	190		// this method is executed by the mainthread and can therefore access all GUI elements.
187	191		begin
188	192		if Assigned(FOnShowStatus) then
189	193		begin
190	194		FOnShowStatus(fStatusText);
191	195		end;
192	196		end;
193	197
194	198		procedure TMyThread.Execute;
195	199		var
196	200		newStatus : string;
197	201		begin
198	202		fStatusText := 'TMyThread Starting...';
199	203		Synchronize(@Showstatus);
200	204		fStatusText := 'TMyThread Running...';
201	205		while (not Terminated) and ([any condition required]) do
202	206		begin
203	207		...
204	208		[here goes the code of the main thread loop]
205	209		...
206	210		if NewStatus <> fStatusText then
207	211		begin
208	212		fStatusText := newStatus;
209	213		Synchronize(@Showstatus);
210	214		end;
211	215		end;
212	216		end;
213	217		```
214	218
215	219		在应用程序中，
216	220
217	221		``` pascal
218	222		Type
219	223		TForm1 = class(TForm)
220	224		Button1: TButton;
221	225		Label1: TLabel;
222	226		procedure FormCreate(Sender: TObject);
223	227		procedure FormDestroy(Sender: TObject);
224	228		private
225	229		{ private declarations }
226	230		MyThread: TMyThread;
227	231		procedure ShowStatus(Status: string);
228	232		public
229	233		{ public declarations }
230	234		end;
231	235
232	236		procedure TForm1.FormCreate(Sender: TObject);
233	237		begin
234	238		inherited;
235	239		MyThread := TMyThread.Create(true);
236	240		MyThread.OnShowStatus := @ShowStatus;
237	241		end;
238	242
239	243		procedure TForm1.FormDestroy(Sender: TObject);
240	244		begin
241	245		MyThread.Terminate;
242	246
243	247		// FreeOnTerminate is true so we should not write:
244	248		// MyThread.Free;
245	249		inherited;
246	250		end;
247	251
248	252		procedure TForm1.Button1Click(Sender: TObject);
249	253		begin
250	254		MyThread.Start;
251	255		end;
252	256
253	257		procedure TForm1.ShowStatus(Status: string);
254	258		begin
255	259		Label1.Caption := Status;
256	260		end;
257	261		```
258	262
259	263		## 特殊处理
260	264
261	265		### Windows堆栈检查
262	266
263	267		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.
264	268
265	269		A good code to check for this and other exceptions which can occur in thread creation is:
266	270
267	271		如果在Windows使用-CT（堆栈检查）会引发一些问题。如果你使用默认的堆栈大小在，堆栈检查将在TThread.Create时"触发"，原因不是很清楚。唯一的解决方法是，不使用-CT。请注意，它不会导致主线程的异常，但新创建的却不一定。如果线程从未启动过，它"看起来"会。
268	272
269	273		下面的代码来检查它，用于在线程创建时抛出异常：
270	274
271	275		``` pascal
272	276		MyThread := TThread.Create(False);
273	277		if Assigned(MyThread.FatalException) then
274	278		raise MyThread.FatalException;
275	279		```
276	280
277	281		This code will assure that any exception which occurred during thread creation will be raised in your main thread.
278	282
279	283		~~上面的代码，将在某个线程创建时抛出任何异常在主线程中。~~
280	284
281	285		### 多线程包
282	286
283	287		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:
284	288
285	289		``` pascal
286	290		uses
287	291		{$IFDEF UNIX}{$IFDEF UseCThreads}
288	292		cthreads,
289	293		cmem, // the c memory manager is on some systems much faster for multi-threading
290	294		{$ENDIF}{$ENDIF}
291	295		```
292	296
293	297		### Heaptrc
294	298
295	299		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.
296	300
297	301		~~你不能使用-gh选项与 cmem 单元。-gh使用了heaptrc单元，它扩展了堆管理器。因此heaptrc 必须在cmem单元后引用。~~
298	302
299	303		``` pascal
300	304		uses
301	305		{$IFDEF UNIX}{$IFDEF UseCThreads}
302	306		cthreads,
303	307		cmem, // the c memory manager is on some systems much faster for multi-threading
304	308		{$ENDIF}{$ENDIF}
305	309		heaptrc,
306	310		```
307	311
308	312		## SMP支持
309	313
310	314		好消息是，如果你的应用程序在多线程上工作正常，看来SMP已经启用。
311	315
312	316		## Lazarus调试多线程应用程序
313	317
314	318		Lzarus上使用[GDB](http://zh.wikipedia.org/zh-cn/GDB)进行调试，它功能齐全、稳定。不过，在一些Linux发行版上存在一些问题。
315	319
316	320		### 调试输出
317	321
318	322		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.
319	323
320	324		（在一个单线程的应用程序中，你可以很容易的写入（输出信息）到控制台/终端/其他，因为写入顺序是一样的。
321	325
322	326		在多线程应用程序中这样做会变得很复杂。如果两个线程在写，线程A在线程B之前输出一行，似乎输出结果并不会按写入顺序显示。甚至会发生，一个线程写入一个线程输出，其他的线程在写。在Linux下使用DebugLn()你会得到正确的输出结果。在Win32下可能得到异常（或许是DiskFull），它是因为，在主线程外使用DebugLn()。
323	327
324	328		所以，为了避免这类问题，使用DebugLnThreadLog()，下面将会提到：）
325	329
326	330		LCLProc 单元包含几个过程，让每个线程写入它自己的日志文件：
327	331
328	332		``` pascal
329	333		procedure DbgOutThreadLog(const Msg: string); overload;
330	334		procedure DebuglnThreadLog(const Msg: string); overload;
331	335		procedure DebuglnThreadLog(Args: array of const); overload;
332	336		procedure DebuglnThreadLog; overload;
333	337		```
334	338
335	339		示例：不是writeln('Some text ',123); 而是，使用
336	340
337		-	~~` DebuglnThreadLog(['Some text ',123]);`~~
	341	+	```text
	342	+	DebuglnThreadLog(['Some text ',123]);
	343	+	```
338	344
339	345		这将在Log\<PID\>.txt文件中添加一行'Some text 123'。\<PID\>是当前线程的进程ID。
340	346
341	347		在每次运行前删除日志文件是个不错的选择：
342	348
343		-	~~` rm -f Log* && ./project1`~~
	349	+	```text
	350	+	rm -f Log* && ./project1
	351	+	```
344	352
345	353		### Linux
346	354
347	355		如果你尝试在Linux调试多线程应用程序，你将会遇到一个很大的问题：
348	356
349	357		X服务器上的桌面管理器可能会挂掉。如应用程序已捕获鼠标/键盘gdb暂停，X服务器等待应用程序响应。
350	358
351	359		发生这种情况时，你可以使用另一个用户登录计算机杀掉gdb或按Ctrl+Alt+F3退出会话并杀掉gdb。
352	360
353	361		或者，你重新启动窗口管理器：输入 /etc/init.d/gdm restart。
354	362
355	363		这将重新启动桌面管理器，让你回到桌面。
356	364
357	365		Since it depends where gdb stops your program in some cases some tricks may help: 为Ubuntu x64设置项目选项用于调试所需的额外信息文件...
358	366
359		-	~~` 工程菜单 -> 工程选项 -> 编译选项中的调试项，勾选``使用外部gdb调试语法文件(-Xg)``。`~~
	367	+	```text
	368	+	工程菜单 -> 工程选项 -> 编译选项中的调试项，勾选使用外部gdb调试语法文件(-Xg)。
	369	+	```
360	370
361	371		另一种选择是，打开另一个X桌面，在里面运行 IDE/GDB和其他应用程序，因此，只会在测试桌面中冻结。创建一个新的X实例：
362	372
363		-	~~` X :1 &`~~
	373	+	```text
	374	+	X :1 &
	375	+	```
364	376
365	377		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)).
366	378
367	379		（~~这将打开，按Ctrl+Alt+F7切换到另一个桌面，Ctrl+Alt+F8切换到原桌面（桌面快捷键没效果，尝试按Ctrl+Alt+F2，它工作在[Slackware](http://www.slackware.com)）。~~）
368	380
369	381		Then you could, if you want, create a desktop session on the X started with:
370	382
371	383		（~~之后，如果你愿意，你可以在X开始时创建会话：~~）
372	384
373		-	~~` gnome-session --display=:1 &`~~
	385	+	```text
	386	+	gnome-session --display=:1 &
	387	+	```
374	388
375	389		Then, in Lazarus, on the run parameters dialog for the project, check "Use display" and enter :1.
376	390
377	391		（~~之后在Lazarus运行参数对话框中检查Use display并设置为:1。~~）
378	392
379	393		现在应用程序运行在第二个X服务器上，你可以在第一个X服务器上调试它。。
380	394
381	395		在Windows及Linux上的Free Pascal 2.0 和Lazarus 0.9.10 测试。
382	396
383	397		------------------------------------------------------------------------
384	398
385	399		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.
386	400
387	401		（~~而不是创建一个新的X会话，可以使用[Xnest](http://en.wikipedia.org/wiki/Xnest)。Xnest是X会话窗口，它使用X服务器不锁定调试线程，及更容易调试并改变终端。~~）
388	402
389	403		运行 Xnest 命令
390	404
391		-	~~` Xnest :1 -ac`~~
	405	+	```text
	406	+	Xnest :1 -ac
	407	+	```
392	408
393	409		创建一个X会话:1，并禁用访问控制。
394	410
395	411		## Lazarus 部件工具箱接口
396	412
397	413		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.
398	414
399	415		(~~在Win32 中，gtk 和carbon接口支持多线程。这意味着，TThread、关键区域和同步工作，但它们不是线程安全的。也就是说只有一个线程在同一时间可以访问LCL。由于主线程不应该等待另一个线程，这使得只有主线程访问LCL，这意味着任何TControl，应用程序和LCL控件句柄。LCL中有一些线程安全函数。例如大部分的 FileUtil 单元中的函数是[线程安全](http://zh.wikipedia.org/wiki/%E7%BA%BF%E7%A8%8B%E5%AE%89%E5%85%A8)的。~~)
400	416
401	417		### 使用SendMessage/PostMessage进行线程间通信
402	418
403	419		在应用程序中只有一个线程可以调用LCL API，通常是主线程。其他线程可以通过一些间接的方法调用LCL，使用SendMessage、PostMessage是不错的选择。LCLIntf.SendMessage 和 LCLIntf.PostMessage将发送一条消息到应用程序的消息队列中。
404	420
405	421		参看这些例程文档
406	422
407	423		- [[doc:lcl/lclintf/sendmessage.html\|SendMessage]]
408	424		- [[doc:lcl/lclintf/postmessage.html\|PostMessage]]
409	425
410	426		The difference between SendMessage and PostMessage is the way that they return control to the calling thread. With SendMessage control is not returned until the window that the message was sent to has completed processing the sent message, however with PostMessage control is returned immediately.
411	427
412	428		(~~SendMessage 和 PostMessage区别在于处理调用线程的方式。SendMessage 在接收到返回值后才继续执行，而PostMessage则不会等待。~~)
413	429
414	430		Here is an example of how a secondary thread could send text to be displayed in an LCL control to the main thread:
415	431
416	432		``` pascal
417	433		const
418	434		WM_GOT_ERROR = LM_USER + 2004;
419	435		WM_VERBOSE = LM_USER + 2005;
420	436
421	437		procedure VerboseLog(Msg: string);
422	438		var
423	439		PError: PChar;
424	440		begin
425	441		if MessageHandler = 0 then Exit;
426	442		PError := StrAlloc(Length(Msg)+1);
427	443		StrCopy(PError, PChar(Msg));
428	444		PostMessage(formConsole.Handle, WM_VERBOSE, Integer(PError), 0);
429	445		end;
430	446		```
431	447
432	448		及如何从窗口中处理这个消息：
433	449
434	450		``` pascal
435	451		const
436	452		WM_GOT_ERROR = LM_USER + 2004;
437	453		WM_VERBOSE = LM_USER + 2005;
438	454
439	455		type
440	456		{ TformConsole }
441	457
442	458		TformConsole = class(TForm)
443	459		DebugList: TListView;
444	460		// ...
445	461		private
446	462		procedure HandleDebug(var Msg: TLMessage); message WM_VERBOSE;
447	463		end;
448	464
449	465		var
450	466		formConsole: TformConsole;
451	467
452	468		implementation
453	469
454	470		....
455	471
456	472		{ TformConsole }
457	473
458	474		procedure TformConsole.HandleDebug(var Msg: TLMessage);
459	475		var
460	476		Item: TListItem;
461	477		MsgStr: PChar;
462	478		MsgPasStr: string;
463	479		begin
464	480		MsgStr := PChar(Msg.wparam);
465	481		MsgPasStr := StrPas(MsgStr);
466	482		Item := DebugList.Items.Add;
467	483		Item.Caption := TimeToStr(SysUtils.Now);
468	484		Item.SubItems.Add(MsgPasStr);
469	485		Item.MakeVisible(False);
470	486		//f/TrayControl.SetError(MsgPasStr);
471	487		end;
472	488
473	489		end.
474	490		```
475	491
476	492		## 临界区
477	493
478	494		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.
479	495
480	496		(~~[临界区](http://zh.wikipedia.org/wiki/%E4%B8%B4%E7%95%8C%E5%8C%BA)用来确保代码的某些部分同一时间只能由一个线程执行。临界区需要被创建/初始化后才能使用，不需要时释放它。~~)
481	497
482	498		临界区通常使用这种方式：
483	499
484	500		声明（全局范围内所有线程可以访问）：
485	501
486		-	~~` MyCriticalSection: TRTLCriticalSection;`~~
	502	+	```text
	503	+	MyCriticalSection: TRTLCriticalSection;
	504	+	```
487	505
488	506		初始化临界区：
489	507
490		-	~~` InitializeCriticalSection(MyCriticalSection);`~~
	508	+	```text
	509	+	InitializeCriticalSection(MyCriticalSection);
	510	+	```
491	511
492	512		运行一些线程，只做
493	513
494	514		``` pascal
495	515		EnterCriticalSection(MyCriticalSection);
496	516		try
497	517		// 访问变量、写入文件、发送网络数据包等等
498	518		finally
499	519		LeaveCriticalSection(MyCriticalSection);
500	520		end;
501	521		```
502	522
503	523		所有线程结束后，释放它：
504	524
505		-	~~` DeleteCriticalSection(MyCriticalSection);`~~
	525	+	```text
	526	+	DeleteCriticalSection(MyCriticalSection);
	527	+	```
506	528
507	529		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.
508	530
509	531		(~~作为代替者，你可以使用TCriticalSection对象。创建即初始化临界区，进入临界区使用 EnterCriticalSection，离开时使用 LeaveCriticalSection，对象销毁时删除临界区。~~)
510	532
511	533		例如：5个线程递增计数器。查看 lazarus/examples/multithreading/criticalsectionexample1.lpi
512	534
513	535		注意： There are two sets of the above 4 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 with an LCL Critical Section and vice versus.
514	536
515	537		### 共享变量
516	538
517	539		如果一些线程共享变量，它是只读的，那么就没有什么好担心的，直接读取就可以了。
518	540
519	541		但是如果一个或多个线程想改变变量，那么你必须确保，同一时间只有一个线程访问该变量。
520	542
521	543		示例：5线程递增计数器。查看 lazarus/examples/multithreading/criticalsectionexample1.lpi
522	544
523	545		## 等待另一个线程
524	546
525	547		如果一个线程A需要线程B的结果，那么它必须等待，直到B完成。
526	548
527	549		重要：主线程不应该等待另一个线程，不是使用Synchronize（见上文）。
528	550
529	551		查看示例： lazarus/examples/multithreading/waitforexample1.lpi
530	552
531	553		``` pascal
532	554		{ TThreadA }
533	555
534	556		procedure TThreadA.Execute;
535	557		begin
536	558		Form1.ThreadB:=TThreadB.Create(false);
537	559		// create event
538	560		WaitForB:=RTLEventCreate;
539	561		while not Application.Terminated do begin
540	562		// wait infinitely (until B wakes A)
541	563		RtlEventWaitFor(WaitForB);
542	564		writeln('A: ThreadB.Counter='+IntToStr(Form1.ThreadB.Counter));
543	565		end;
544	566		end;
545	567
546	568		{ TThreadB }
547	569
548	570		procedure TThreadB.Execute;
549	571		var
550	572		i: Integer;
551	573		begin
552	574		Counter:=0;
553	575		while not Application.Terminated do begin
554	576		// B: Working ...
555	577		Sleep(1500);
556	578		inc(Counter);
557	579		// wake A
558	580		RtlEventSetEvent(Form1.ThreadA.WaitForB);
559	581		end;
560	582		end;
561	583		```
562	584
563	585		> Note: RtlEventSetEvent can be called before RtlEventWaitFor. Then RtlEventWaitFor will return immediately. Use RTLeventResetEvent to clear a flag.
564	586
565	587		> Note: ~~RtlEventSetEvent可以在RtlEventWaitFor之前被调用。之后RtlEventWaitFor将立即返回。使用RTLeventResetEvent清除标记。~~
566	588
567	589		## Fork
568	590
569	591		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.
570	592
571	593		So be aware of any threads initializing before the call (including on the initialization section). They will NOT work.
572	594
573	595		## 并行程序/循环
574	596
575	597		多线程的一个特殊情况是并行运行一个程序。参见[[Parallel procedures\|并行程序]]。
576	598
577	599		## 分布式计算
578	600
579	601		The next higher steps after multi threading is running the threads on multiple machines.
580	602
581	603		- 可以使用TCP组件像synapse、lnet 或 indy通信。这给你最大的灵活性和主要用于松散连接的客户端/服务器应用程序。
582	604		- 你可以使用消息传递库，像[[MPICH]]，用于HPC（高性能计算）集群上。
583	605
584	606		## 外部线程
585	607
586	608		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).
587	609
588	610		Things to consider when using external threads (might not be needed in all or future compiler versions):
589	611
590	612		- 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.
591	613
592	614		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:
593	615
594	616		``` pascal
595	617		type
596	618		TCdeclThreadFunc = function (user_data:Pointer):Pointer;cdecl;
597	619
598	620		PCdeclThreadFuncData = ^TCdeclThreadFuncData;
599	621		TCdeclThreadFuncData = record
600	622		Func: TCdeclThreadFunc; //cdecl function
601	623		Data: Pointer; //original data
602	624		end;
603	625
604	626		// The Pascal thread calls the cdecl function
605	627		function C2P_Translator(FuncData: pointer) : ptrint;
606	628		var
607	629		ThreadData: TCdeclThreadFuncData;
608	630		begin
609	631		ThreadData := PCdeclThreadFuncData(FuncData)^;
610	632		Result := ptrint(ThreadData.Func(ThreadData.Data));
611	633		end;
612	634
613	635		procedure CreatePascalThread;
614	636		var
615	637		ThreadData: PCdeclThreadFuncData;
616	638		begin
617	639		New(ThreadData);
618	640		// this is the desired cdecl thread function
619	641		ThreadData^.Func := func;
620	642		ThreadData^.Data := user_data;
621	643		// this creates the Pascal thread
622	644		BeginThread(@C2P_Translator, ThreadData );
623	645		end;
624	646		```
625	647
626	648		- 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).
627	649
628	650		``` pascal
629	651		type
630	652		tc = class(tthread)
631	653		procedure execute;override;
632	654		end;
633	655
634	656		procedure tc.execute;
635	657		begin
636	658		end;
637	659
638	660		{ main program }
639	661		begin
640	662		{ initialise threading system }
641	663		with tc.create(false) do
642	664		begin
643	665		waitfor;
644	666		free;
645	667		end;
646	668		{ ... your code follows }
647	669		end.
648	670		```
649	671
650	672		(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.)
651	673
652	674		- If for some reason this doesn't work for you, try this code in your external thread function:
653	675
654	676		``` pascal
655	677		function ExternalThread(param: Pointer): LongInt; stdcall;
656	678		var
657	679		tm: TThreadManager;
658	680		begin
659	681		GetThreadManager(tm);
660	682		tm.AllocateThreadVars;
661	683		InitThread(1000000); // adjust inital stack size here
662	684
663	685		{ do something threaded here ... }
664	686
665	687		Result:=0;
666	688		end;
667	689		```
668	690
669	691		### 识别外部线程
670	692
671	693		有时你甚至不知道是否要处理外部线程（如对C 库进行回调）。这个可以帮助你来分析：
672	694
673	695		1\. 询问操作系统当前应用程序线程的ID
674	696
675	697		``` pascal
676	698		GetCurrentThreadID() // Windows;
677	699		GetThreadID() // Darwin/OSX;
678	700		TThreadID(pthread_self) // Linux;
679	701		```
680	702
681	703		2\. 再次询问线程内部的当前线程的ID和步骤1结果对比
682	704
683	705		### 放弃时间片
684	706
685	707		ThreadSwitch()
686	708
687	709		> Note: 不要使用Windows的 Sleep(0)，因为它不会在所有平台上工作。
688	710
689	711		## 参见
690	712
691	713		- [[Streaming components\|流媒体组件]]
692	714		- [[Manager Worker Threads System\|管理工作线程系统]]
693	715		- [[Example of multi-threaded application: array of threads\|多线程应用示例：数组线程]]
694	716		- [[Parallel procedures\|并行程序]]
695	717		- [[Main Loop Hooks\|主循环钩子]]
696	718		- [[Asynchronous Calls\|异步调用]]
697	719
698	720		---
699	721		From the Free Pascal wiki, page "Multithreaded Application Tutorial/zh CN", as it stood on 2020-02-20 after a change by Trev, 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