Asynchronous Calls: what changed

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

Old	New		Line
1	1		## Problem statement
2	2
3	3		When handling some event, you need to do something, but you can't do it right away. For example, you need to free an object, but it is or will be referenced somewhere in the parent (or its parent etc.) later on. Or you need to update GUI elements accessed by several threads in a thread safe manner.
4	4
5	5		## Solution
6	6
7	7		Call Application.[[doc:lcl/forms/tapplication.queueasynccall.html\|QueueAsyncCall]]:
8	8
9		-	~~[[doc:lcl/forms/tdataevent.html\|TDataEvent]]` = procedure (Data: PtrInt) of object;`\~~
	9	+	``` pascal
	10	+	TDataEvent = procedure (Data: PtrInt) of object;
10	11
11		-	~~`procedure `[[doc:lcl/forms/tapplication.queueasynccall.html\|QueueAsyncCall]]`(AMethod: TDataEvent; Data: PtrInt);`\~~
	12	+	procedure QueueAsyncCall(AMethod: TDataEvent; Data: PtrInt);
	13	+	```
12	14
13	15		This will "queue" the given method with the given parameter for execution in the main event loop, when all other events have been processed. In the example above, the reference to the object you wanted to free has gone, since the then-parent has finished execution, and the object you wanted to free can be freed safely.
14	16
15	17		Note that this is a more generic version of [[doc:lcl/forms/tapplication.releasecomponent.html\|ReleaseComponent]], and ReleaseComponent calls this method.
16	18
17	19		## Examples
18	20
19	21		### Simple data passed to async function
20	22
21	23		The following program shows the use of [[doc:lcl/forms/tapplication.queueasynccall.html\|QueueAsyncCall]]. If you press on the CallButton, 'Click 1', 'Click 2' and 'Async 1' is added to the LogListBox. Note that Async call is only executed after the CallButtonClick event has finished.
22	24
23	25		``` pascal
24	26		unit TestQueueAsyncCall;
25	27
26	28		{$mode objfpc}{$H+}
27	29
28	30		interface
29	31
30	32		uses
31	33		Classes, SysUtils, LResources, Forms, Controls, Graphics, Dialogs, Buttons,
32	34		StdCtrls;
33	35
34	36		type
35	37
36	38		{ TQueueAsyncCallForm }
37	39
38	40		TQueueAsyncCallForm = class(TForm)
39	41		CallButton: TButton;
40	42		LogListBox: TListBox;
41	43		procedure CallButtonClick(Sender: TObject);
42	44		private
43	45		{ private declarations }
44	46		FCounter: PtrInt;
45	47		procedure Async(Data: PtrInt);
46	48		public
47	49		{ public declarations }
48	50		end;
49	51
50	52		var
51	53		QueueAsyncCallForm: TQueueAsyncCallForm;
52	54
53	55		implementation
54	56
55	57		{$R *.lfm}
56	58
57	59		{ TQueueAsyncCallForm }
58	60
59	61		procedure TQueueAsyncCallForm.CallButtonClick(Sender: TObject);
60	62		begin
61	63		LogListBox.Items.Add('Click 1');
62	64		FCounter := FCounter+1;
63	65		Application.QueueAsyncCall(@Async,FCounter);
64	66		LogListBox.Items.Add('Click 2');
65	67		end;
66	68
67	69		procedure TQueueAsyncCallForm.Async(Data: PtrInt);
68	70		begin
69	71		LogListBox.Items.Add('Async '+ IntToStr(Data));
70	72		end;
71	73
72	74		end.
73	75		```
74	76
75	77		### Record passed to async function
76	78
77	79		Here is some code extracted from MultiLog's MemoChannel unit used for thread safe logging messages to Memo control. Thanks to QueueAsyncCall() all writings to Memo are serialized. There are no locks and no conflicts, even with hundreds of threads calling Write() method.
78	80
79	81		```delphi
80	82		...
81	83		type
82	84		TLogMsgData = record // record can hold much more then a simple string :-)
83	85		Text: string;
84	86		end;
85	87		PLogMsgData = ^TLogMsgData;
86	88		...
87	89		procedure TMemoChannel.Write(const AMsg: string);
88	90		var
89	91		LogMsgToSend: PLogMsgData;
90	92		begin
91	93		New(LogMsgToSend);
92	94		LogMsgToSend^.Text:= AMsg;
93	95		Application.QueueAsyncCall(@WriteAsyncQueue, PtrInt(LogMsgToSend)); // put log msg into queue that will be processed from the main thread after all other messages
94	96		end;
95	97		...
96	98		procedure TMemoChannel.WriteAsyncQueue(Data: PtrInt);
97	99		var // called from main thread after all other messages have been processed to allow thread safe TMemo access
98	100		ReceivedLogMsg: TLogMsgData;
99	101		begin
100	102		ReceivedLogMsg := PLogMsgData(Data)^;
101	103		try
102	104		if (FMemo <> nil) and (not Application.Terminated) then
103	105		begin
104	106		...
105	107		FMemo.Append(ReceivedLogMsg.Text) // <<< fully thread safe
106	108		end;
107	109		finally
108	110		Dispose(PLogMsgData(Data));
109	111		end;
110	112		end;
111	113		```
112	114
113	115		## See also
114	116
115	117		- [TThread.Queue, which provides the same functionality in a Delphi compatible way and with anonymous method support in FPC 3.3.x and later](https://www.freepascal.org/docs-html/rtl/classes/tthread.queue.html)
116	118		- [New 0.9.26 features. Part 1. SendMessage and PostMessage](http://lazarus-dev.blogspot.com/2008/01/new-0926-features-part-1-sendmessage.html)
117	119		- [[Main Loop Hooks]]
118	120		- [[Multithreaded Application Tutorial]]
119	121
120	122		---
121	123		From the Free Pascal wiki, page "Asynchronous Calls", as it stood on 2023-09-07 after a change by Marcov, 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