Cocoa Internals/Memory Management: what changed

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

Old	New		Line
1	1		All Objective-C objects are reference counted objects. Once the count reaches zero - the object is freed.
2	2
3	3		The modern Objective-C (or Swift) recommends (strongly, fiercely) to use Automatic-Reference-Counting (ARC) support. FPC support for Objective-C was started way before ARC became highly recommended and was part of the language. Right now Objective-C 2.0 syntax provides the language level support for ARC, while FPC doesn't have those (yet?). All Cocoa Widgetset code cannot doesn't rely on ARC and using reference and dereference manually.
4	4
5	5		## Memory Management
6	6
7	7		As mentioned earlier - all Cocoa objects are reference counted objects. They should be allocated via a class constructor (typically alloc()) and be released via release() method (rather than calling a "destructor" dealloc).
8	8
9	9		Consider the following code example:
10	10
11	11		A new sub-class of NSObject is declared, overriding its alloc (constructor) and dealloc (destructor) methods. Overridden methods are providing a logging output.
12	12
13	13		```delphi
14	14		program project1;
15	15
16	16		{$mode delphi}{$H+}
17	17		{$modeswitch objectivec1}
18	18		{$modeswitch objectivec2}
19	19
20	20		uses CocoaAll;
21	21
22	22		type
23	23
24	24		{ NSMyObject }
25	25
26	26		NSMyObject = objcclass(NSObject)
27	27		public
28	28		class function alloc: id; override;
29	29		procedure dealloc; override;
30	30		end;
31	31
32	32		{ NSMyObject }
33	33
34	34		class function NSMyObject.alloc: id;
35	35		begin
36	36		Result:=inherited alloc;
37	37		writeln('alloc: ', PtrUInt(Result));
38	38		end;
39	39
40	40		procedure NSMyObject.dealloc;
41	41		begin
42	42		writeln('dealloc: ', PtrUInt(Self));
43	43		inherited dealloc;
44	44		end;
45	45
46	46		procedure MakeObject;
47	47		var
48	48		obj : NSMyObject;
49	49		begin
50	50		obj:=NSMyObject.alloc.init;
51	51		obj.release;
52	52		end;
53	53
54	54		begin
55	55		MakeObject;
56	56		MakeObject;
57	57		MakeObject;
58	58		end.
59	59		```
60	60
61	61		The output of calling such process would be:
62	62
63		-	~~`alloc: 3206800`\~~
64		-	~~`dealloc: 3206800`\~~
65		-	~~`alloc: 3206800`\~~
66		-	~~`dealloc: 3206800`\~~
67		-	~~`alloc: 3206800`\~~
68		-	~~`dealloc: 3206800`~~
	63	+	```
	64	+	alloc: 3206800
	65	+	dealloc: 3206800
	66	+	alloc: 3206800
	67	+	dealloc: 3206800
	68	+	alloc: 3206800
	69	+	dealloc: 3206800
	70	+	```
69	71
70	72		This is happening, because whenever an object is allocated, it's reference count is set to 1. Calling release method reduced the reference counter by 1. If reference count becomes zero, objc runtime - is calling objects destructor - dealloc.
71	73
72	74		### Leaking
73	75
74	76		If MakeObject procedure is modified as following:
75	77
76	78		```delphi
77	79		procedure MakeObject;
78	80		var
79	81		obj : NSMyObject;
80	82		begin
81	83		obj:=NSMyObject.alloc.init;
82	84		// removed the line with .release call
83	85		end;
84	86		```
85	87
86	88		the output of the application changes to:
87	89
88		-	~~`alloc: 2146560 `\~~
89		-	~~`alloc: 2146288 `\~~
90		-	~~`alloc: 2146304`~~
	90	+	```
	91	+	alloc: 2146560
	92	+	alloc: 2146288
	93	+	alloc: 2146304
	94	+	```
91	95
92	96		That looks like a memory leak via ObjC objects, because allocated objects were not released.
93	97
94	98		Preventing a leak requires a proper release of an object.
95	99
96	100		### Autorelease Pools
97	101
98	102		In order to decrease a complexity of tracking of object life-span and releasing, Cocoa provides an autorelease mechanism. Any object registered in with an autorelease pool, would be released at the time autorelease pool is drained and the object's reference count is equal to 1.
99	103
100	104		(Autorelease pools are drained whenever they're released).
101	105
102	106		Let's modify the example above in the following manner:
103	107
104	108		```delphi
105	109		procedure MakeObject;
106	110		var
107	111		obj : NSMyObject;
108	112		begin
109	113		obj:=NSMyObject.alloc.init.autorelease; // registering the allocated object with autorelease pool
110	114		end;
111	115
112	116		var
113	117		pool : NSAutoreleasePool;
114	118		begin
115	119		pool := NSAutoreleasePool.alloc.init;
116	120		MakeObject;
117	121		MakeObject;
118	122		MakeObject;
119	123		writeln('releasing the pool');
120	124		pool.release;
121	125		writeln('done');
122	126		end.
123	127		```
124	128
125	129		The output of the program is as following:
126	130
127		-	~~`alloc: 3175888`\~~
128		-	~~`alloc: 3172352`\~~
129		-	~~`alloc: 3172368 `\~~
130		-	~~`releasing the pool`\~~
131		-	~~`dealloc: 3172368 `\~~
132		-	~~`dealloc: 3172352`\~~
133		-	~~`dealloc: 3175888`\~~
134		-	~~`done`~~
	131	+	```
	132	+	alloc: 3175888
	133	+	alloc: 3172352
	134	+	alloc: 3172368
	135	+	releasing the pool
	136	+	dealloc: 3172368
	137	+	dealloc: 3172352
	138	+	dealloc: 3175888
	139	+	done
	140	+	```
135	141
136	142		All objects were released together with release of the pool.
137	143
138	144		### Leaking out of the pool
139	145
140	146		Note that any time a pool is created it's placed on the "stack" of the pools and become a current pool. Any objects allocated before the pool, would not be released with the pool itself. \<source lang="delphi\>var
141	147
142	148		` pool : NSAutoreleasePool;`
143	149
144	150		begin
145	151
146	152		` MakeObject;`\
147	153		` pool := NSAutoreleasePool.alloc.init;`\
148	154		` MakeObject;`\
149	155		` MakeObject;`\
150	156		` writeln('releasing the pool');`\
151	157		` pool.release;`\
152	158		` writeln('done');`
153	159
154	160		end.
155	161
156	162		output:
157	163
158		-	~~`alloc: 4199616`\~~
159		-	~~`alloc: 4202144 `\~~
160		-	~~`alloc: 4202160`\~~
161		-	~~`releasing the pool`\~~
162		-	~~`dealloc: 4202160 `\~~
163		-	~~`dealloc: 4202144`\~~
164		-	~~`done`~~
	164	+	```
	165	+	alloc: 4199616
	166	+	alloc: 4202144
	167	+	alloc: 4202160
	168	+	releasing the pool
	169	+	dealloc: 4202160
	170	+	dealloc: 4202144
	171	+	done
	172	+	```
165	173
166	174		As you can see only two later objects were released. The first object remained in the memory.
167	175
168	176		### Multiple pools
169	177
170	178		It's expected that multiple pools would could be used. The typical example of is to have an additional pool for a routine where a great number of temporary objects could be used.
171	179
172	180		In the end the memory would be cleaned up, together with the local pool released:
173	181
174	182		```delphi
175	183		procedure ExtraProc;
176	184		var
177	185		pool : NSAutoreleasePool;
178	186		begin
179	187		pool := NSAutoreleasePool.alloc.init;
180	188		try
181	189		MakeObject;
182	190		MakeObject;
183	191		finally
184	192		pool.release;
185	193		end;
186	194		end;
187	195
188	196		var
189	197		pool : NSAutoreleasePool;
190	198		begin
191	199		pool := NSAutoreleasePool.alloc.init;
192	200		MakeObject;
193	201		writeln('calling ExtraProc()');
194	202		ExtraProc();
195	203		writeln('ExtraProc() done');
196	204		pool.release;
197	205		end.
198	206		```
199	207
200	208		output:
201	209
202		-	~~`alloc: 3155200`\~~
203		-	~~`calling ExtraProc()`\~~
204		-	~~`alloc: 3155024`\~~
205		-	~~`alloc: 3155248`\~~
206		-	~~`dealloc: 3155248`\~~
207		-	~~`dealloc: 3155024`\~~
208		-	~~`ExtraProc() done`\~~
209		-	~~`dealloc: 3155200`~~
	210	+	```
	211	+	alloc: 3155200
	212	+	calling ExtraProc()
	213	+	alloc: 3155024
	214	+	alloc: 3155248
	215	+	dealloc: 3155248
	216	+	dealloc: 3155024
	217	+	ExtraProc() done
	218	+	dealloc: 3155200
	219	+	```
210	220
211	221		Objects allocated within ExtraProc were released within ExtraProc. Object created outside of extra proc was released with its own "global" autorelease pool.
212	222
213	223		### Leaking with Pools because of too many Retains
214	224
215	225		Note, that an object would be released with autorelease pool only, if it's reference count reached 1. (when draining a pool would simply decrease the reference count, and if it drops to 0 the object is released).
216	226
217	227		Modifying ExtraProc from the example above as following:
218	228
219	229		```delphi
220	230		procedure ExtraProc;
221	231		var
222	232		pool : NSAutoreleasePool;
223	233		obj : NSMyObject;
224	234		begin
225	235		pool := NSAutoreleasePool.alloc.init;
226	236		try
227	237		MakeObject;
228	238		obj:=NSMyObject.alloc.init.autorelease; // the same allocation code as in MakeObject proc
229	239		writeln('ref count = ', obj.retainCount);
230	240		obj.retain;
231	241		writeln('ref count = ', obj.retainCount);
232	242		finally
233	243		pool.release;
234	244		writeln('ref count = ', obj.retainCount);
235	245		end;
236	246		end;
237	247		```
238	248
239	249		the output of the program would be:
240	250
241		-	~~` alloc: 4202000`\~~
242		-	~~` calling ExtraProc()`\~~
243		-	~~` alloc: 4201824 ; allocating the first object in ExtraProc `\~~
244		-	~~` alloc: 4202048 ; allocating the second object in ExtraProc`\~~
245		-	~~` ref count = 1 ; the reference count after allocation`\~~
246		-	~~` ref count = 2 ; manually increasing the reference count by calling .retain`\~~
247		-	~~` dealloc: 4201824 ; on release of the pool, the first object with reference count was removed. `\~~
248		-	~~` ref count = 1 ; the second object had its reference count decreased to 1 and leaked `\~~
249		-	~~` ExtraProc() done`\~~
250		-	~~` dealloc: 4202000`~~
	251	+	``` pascal
	252	+	alloc: 4202000
	253	+	calling ExtraProc()
	254	+	alloc: 4201824 ; allocating the first object in ExtraProc
	255	+	alloc: 4202048 ; allocating the second object in ExtraProc
	256	+	ref count = 1 ; the reference count after allocation
	257	+	ref count = 2 ; manually increasing the reference count by calling .retain
	258	+	dealloc: 4201824 ; on release of the pool, the first object with reference count was removed.
	259	+	ref count = 1 ; the second object had its reference count decreased to 1 and leaked
	260	+	ExtraProc() done
	261	+	dealloc: 4202000
	262	+	```
251	263
252	264		Note that "global" pool also has no effect on the leaked object. So after the global pool released, the leaked object remained. The leaked object attached to "local" pool that was in current at that time.
253	265
254	266		### App Event Loop and AutoreleasePools
255	267
256	268		Every event (i.e. mouse press, key press, draw, etc) handling is enclosed in it's own AutoreleasePool. The pool is released once the event has been processed.
257	269
258	270		Cocoa Widgetset implements its own event queue, but the same rule remains enforced.
259	271
260	272		Make sure that an object that should stay alive after the event is not autoreleased.
261	273
262	274		### Object Ownership
263	275
264	276		As [Apple documentation](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmRules.html#//apple_ref/doc/uid/20000994-SW1) suggests:
265	277
266	278		The memory management model is based on object ownership. Any object may have one or more owners. As long as an object has at least one owner, it continues to exist. If an object has no owners, the runtime system destroys it automatically. To make sure it is clear when you own an object and when you do not, Cocoa sets the following policy:
267	279
268	280		- You own any object you create
269	281
270	282
271	283		You create an object using a method whose name begins with “alloc”, “new”, “copy”, or “mutableCopy” (for example, alloc, newObject, or mutableCopy).
272	284
273	285		- You can take ownership of an object using retain
274	286
275	287
276	288		A received object is normally guaranteed to remain valid within the method it was received in, and that method may also safely return the object to its invoker. You use retain in two situations: (1) In the implementation of an accessor method or an init method, to take ownership of an object you want to store as a property value; and (2) To prevent an object from being invalidated as a side-effect of some other operation (as explained in Avoid Causing Deallocation of Objects You’re Using).
277	289
278	290		- When you no longer need it, you must relinquish ownership of an object you own
279	291
280	292
281	293		You relinquish ownership of an object by sending it a release message or an autorelease message. In Cocoa terminology, relinquishing ownership of an object is therefore typically referred to as “releasing” an object.
282	294
283	295		- You must not relinquish ownership of an object you do not own
284	296
285	297
286	298		This is just corollary of the previous policy rules, stated explicitly.
287	299
288	300		In practice, not following the serules, might cause unexpected errors in run-time.
289	301
290	302		#### Ownership Violation
291	303
292	304		Consider this following:
293	305
294	306		```delphi
295	307		{$mode objfpc}{$H+}
296	308		{$modeswitch objectivec2}
297	309		uses CocoaAll;
298	310		var
299	311		p : NSIndexSet;
300	312		begin
301	313		p:=NSIndexSet.indexSetWithIndex(10);
302	314		writeln('idx=',p.firstIndex,' refCount=',p.retainCount);
303	315		p.release; // a potential error
304	316		end.
305	317		```
306	318
307	319		If you try to execute the code, it would act as expected and produce no problems.
308	320
309	321		However, there's an error. The object was created using "indexSetWithindex" method.
310	322
311	323		The last line attempts to .release() the object. That violates the ownership rule, where the object is owned only if "alloc"/"new" or "copy" methods were used.
312	324
313	325		The run-time error will show up, if you try to put this code into Autorelease pool:
314	326
315	327		```delphi
316	328		var
317	329		p : NSIndexSet;
318	330		pool : NSAutoreleasePool;
319	331		begin
320	332		pool := NSAutoreleasePool.alloc.init;
321	333		p:=NSIndexSet.indexSetWithIndex(10);
322	334		writeln('idx=',p.firstIndex,' refCount=',p.retainCount);
323	335		p.release;
324	336		pool.release; // error here: *** error for object 0x308a70: pointer being freed was not allocated
325	337		end.
326	338		```
327	339
328	340		The reason behind it, is that "indexSetWithIndex" did allocate an object of NSIndexSet, however it also autorelease-d object. (Notably, why Cocoa internally is using AutoreleasePools often).
329	341
330	342		There are two ways to fix the error:
331	343
332	344		1\) either alloc.initXXX pair should be used, that guaranteers the ownership of the object
333	345
334	346		```delphi
335	347		var
336	348		p : NSIndexSet;
337	349		pool : NSAutoreleasePool;
338	350		begin
339	351		pool := NSAutoreleasePool.alloc.init;
340	352		p:=NSIndexSet.alloc.initWithIndex(10);
341	353		writeln('idx=',p.firstIndex,' refCount=',p.retainCount);
342	354		p.release;
343	355		pool.release;
344	356		end.
345	357		```
346	358
347	359		2\) or the object should not be released explicitly
348	360
349	361		```delphi
350	362		var
351	363		p : NSIndexSet;
352	364		pool : NSAutoreleasePool;
353	365		begin
354	366		pool := NSAutoreleasePool.alloc.init;
355	367		p:=NSIndexSet.indexSetWithIndex(10);
356	368		writeln('idx=',p.firstIndex,' refCount=',p.retainCount);
357	369		pool.release;
358	370		end.
359	371		```
360	372
361	373		The actual approach depends on how NSIndexSet needs to be used in the code.
362	374
363	375		#### Using NSZombies
364	376
365	377		In the example below, the error typed into stderr is not very informative.
366	378
367		-	~~`error here: *** error for object 0xNNNNNNNN: pointer being freed was not allocated`~~
	379	+	``` pascal
	380	+	error here: *** error for object 0xNNNNNNNN: pointer being freed was not allocated
	381	+	```
368	382
369	383		When there's potentially a great number of objects/code that could cause a double-release, it might be handy to use NSZombies.
370	384
371	385		NSZombies are the special debugging mode in Cocoa library. Whenever an object is released, it's not actually being released, but instead is released by NSZombie object. If NSZombie object is released again, then it would produce an error message to stderr, to warn about the double release.
372	386
373	387		In order to enable NSZombies an environmental variable NSZombiesEnable must be set to "YES" (no quotes) declared at the time application starts.
374	388
375	389		Here's an example:
376	390
377	391		```delphi
378	392		program project1;
379	393
380	394		{$mode objfpc}{$H+}
381	395		{$modeswitch objectivec2}
382	396
383	397		uses
384	398		CocoaAll,SysUtils, Classes;
385	399
386	400		type
387	401		NSMyObject = objcclass(NSObject);
388	402
389	403		var
390	404		m: NSMyObject;
391	405		begin
392	406		m:=NSMyObject.alloc.init;
393	407		m.release;
394	408		m.release;
395	409		end.
396	410		```
397	411
398	412		In order to have the zombies enabled you might want to run the application from Terminal using the following commands:
399	413
400		-	~~`export NSZombieEnabled="YES"`\~~
401		-	~~`./project1`~~
	414	+	```
	415	+	export NSZombieEnabled="YES"
	416	+	./project1
	417	+	```
402	418
403	419		(export command could be ran once per Terminal tab. It doesn't affect other opened terminal tabs. Any new Terminal tab or window would require to run the command again, if you need to enable zombies)
404	420
405	421		when application fails, it would produce the following error message:
406	422
407		-	~~`*** -[NSMyObject release]: message sent to deallocated instance 0x606d20`~~
	423	+	```
	424	+	*** -[NSMyObject release]: message sent to deallocated instance 0x606d20
	425	+	```
408	426
409	427		If you try to run the faulty code from ownership violation the error you'd see would be like this:
410	428
411		-	~~`*** -[NSIndexSet release]: message sent to deallocated instance 0x605140`~~
	429	+	```
	430	+	*** -[NSIndexSet release]: message sent to deallocated instance 0x605140
	431	+	```
412	432
413	433		indicating that NSIndexSet was improperly released.
414	434
415	435		While NSZombies is very handy way of resolving problems, such as incorrect and double releases, they should be treated carefully. NSZombies in their nature are memory leaks, because the objects are never released, but rather replaced by the zombie's code. Thus NSZombies should never be used with memory leaks checks, as they would produce false positive results. If there are many objects allocation and releases, the application memory consumption will grow, that might also impact performance.
416	436
417	437		## ObjC Object Leaks
418	438
419	439		Free Pascal debugging unit [[heaptrc]] is only able to track leaking of memory allocated via Pascal Run-time memory management. It's not able to track allocations made via C-runtime/Obj-C memory manager.
420	440
421	441		Apple provides external tools in its Xcode Instruments to keep track of ObjC allocations.
422	442
423	443		### Xcode Instruments
424	444
425	445		The Xcode Instruments Allocations profiling template uses the Allocations and VM Tracker instruments to measure general and virtual memory usage in your app. However, to track down abandoned memory that’s been allocated but isn’t needed again, focus strictly on the Allocations instrument. This instrument measures heap memory usage and tracks allocations, including specific object allocations by class.
426	446
427	447		- See further [Find abandoned memory](https://help.apple.com/instruments/mac/current/#/dev7b8f6eb6).
428	448
429	449		The Xcode Instruments Leaks profiling template uses the Allocations and Leaks instruments to measure general memory usage in your app and check for leaks — memory that has been allocated to objects that are no longer referenced and reachable.
430	450
431	451		- See further [Find memory leaks](https://help.apple.com/instruments/mac/current/#/dev022f987b).
432	452
433	453		## LCL Handles
434	454
435	455		Whenever CreatingHandle in Cocoa widgetset at least 1 NSView (or NSControl) is allocated. (Allocation makes a control with 1 reference count)
436	456
437	457		The view is added to parent view by calling addSubView. By Cocoa standards, adding a view to subview adds another reference count, and object can be released right after the call. LCL Widgetset code SHOULD NOT release immediately, instead the explicit .release call would be called during DestroyHandle.
438	458
439	459		Any additional controls should also be released during DestroyHandle. It's not predictable when the actual "dealloc" would be called. It might be called right away, or at the end of the event processing, with NSAutorelease pool, or whenever the hosting NSWindow decides to cleanup. It's safer to release as much memory as possible at DestroyHandle.
440	460
441	461		## See Also
442	462
443	463		- [[Cocoa Internals]]
444	464		- [Advanced Memory Management](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/MemoryMgmt/Articles/MemoryMgmt.html) - at Apple Developer
445	465
446	466		---
447	467		From the Free Pascal wiki, page "Cocoa Internals/Memory Management", as it stood on 2020-09-19 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).
448	468		Category: Cocoa
449	469		Category: macOS

Back to history