Cocoa Internals/Memory Management: what changed

Revision 3 to 4. 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		-	~~```~~
	63	+	```text
64	64		alloc: 3206800
65	65		dealloc: 3206800
66	66		alloc: 3206800
67	67		dealloc: 3206800
68	68		alloc: 3206800
69	69		dealloc: 3206800
70	70		```
71	71
72	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.
73	73
74	74		### Leaking
75	75
76	76		If MakeObject procedure is modified as following:
77	77
78	78		```delphi
79	79		procedure MakeObject;
80	80		var
81	81		obj : NSMyObject;
82	82		begin
83	83		obj:=NSMyObject.alloc.init;
84	84		// removed the line with .release call
85	85		end;
86	86		```
87	87
88	88		the output of the application changes to:
89	89
90		-	~~```~~
	90	+	```text
91	91		alloc: 2146560
92	92		alloc: 2146288
93	93		alloc: 2146304
94	94		```
95	95
96	96		That looks like a memory leak via ObjC objects, because allocated objects were not released.
97	97
98	98		Preventing a leak requires a proper release of an object.
99	99
100	100		### Autorelease Pools
101	101
102	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.
103	103
104	104		(Autorelease pools are drained whenever they're released).
105	105
106	106		Let's modify the example above in the following manner:
107	107
108	108		```delphi
109	109		procedure MakeObject;
110	110		var
111	111		obj : NSMyObject;
112	112		begin
113	113		obj:=NSMyObject.alloc.init.autorelease; // registering the allocated object with autorelease pool
114	114		end;
115	115
116	116		var
117	117		pool : NSAutoreleasePool;
118	118		begin
119	119		pool := NSAutoreleasePool.alloc.init;
120	120		MakeObject;
121	121		MakeObject;
122	122		MakeObject;
123	123		writeln('releasing the pool');
124	124		pool.release;
125	125		writeln('done');
126	126		end.
127	127		```
128	128
129	129		The output of the program is as following:
130	130
131		-	~~```~~
	131	+	```text
132	132		alloc: 3175888
133	133		alloc: 3172352
134	134		alloc: 3172368
135	135		releasing the pool
136	136		dealloc: 3172368
137	137		dealloc: 3172352
138	138		dealloc: 3175888
139	139		done
140	140		```
141	141
142	142		All objects were released together with release of the pool.
143	143
144	144		### Leaking out of the pool
145	145
146	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
147	147
148	148		` pool : NSAutoreleasePool;`
149	149
150	150		begin
151	151
152	152		` MakeObject;`\
153	153		` pool := NSAutoreleasePool.alloc.init;`\
154	154		` MakeObject;`\
155	155		` MakeObject;`\
156	156		` writeln('releasing the pool');`\
157	157		` pool.release;`\
158	158		` writeln('done');`
159	159
160	160		end.
161	161
162	162		output:
163	163
164		-	~~```~~
	164	+	```text
165	165		alloc: 4199616
166	166		alloc: 4202144
167	167		alloc: 4202160
168	168		releasing the pool
169	169		dealloc: 4202160
170	170		dealloc: 4202144
171	171		done
172	172		```
173	173
174	174		As you can see only two later objects were released. The first object remained in the memory.
175	175
176	176		### Multiple pools
177	177
178	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.
179	179
180	180		In the end the memory would be cleaned up, together with the local pool released:
181	181
182	182		```delphi
183	183		procedure ExtraProc;
184	184		var
185	185		pool : NSAutoreleasePool;
186	186		begin
187	187		pool := NSAutoreleasePool.alloc.init;
188	188		try
189	189		MakeObject;
190	190		MakeObject;
191	191		finally
192	192		pool.release;
193	193		end;
194	194		end;
195	195
196	196		var
197	197		pool : NSAutoreleasePool;
198	198		begin
199	199		pool := NSAutoreleasePool.alloc.init;
200	200		MakeObject;
201	201		writeln('calling ExtraProc()');
202	202		ExtraProc();
203	203		writeln('ExtraProc() done');
204	204		pool.release;
205	205		end.
206	206		```
207	207
208	208		output:
209	209
210		-	~~```~~
	210	+	```text
211	211		alloc: 3155200
212	212		calling ExtraProc()
213	213		alloc: 3155024
214	214		alloc: 3155248
215	215		dealloc: 3155248
216	216		dealloc: 3155024
217	217		ExtraProc() done
218	218		dealloc: 3155200
219	219		```
220	220
221	221		Objects allocated within ExtraProc were released within ExtraProc. Object created outside of extra proc was released with its own "global" autorelease pool.
222	222
223	223		### Leaking with Pools because of too many Retains
224	224
225	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).
226	226
227	227		Modifying ExtraProc from the example above as following:
228	228
229	229		```delphi
230	230		procedure ExtraProc;
231	231		var
232	232		pool : NSAutoreleasePool;
233	233		obj : NSMyObject;
234	234		begin
235	235		pool := NSAutoreleasePool.alloc.init;
236	236		try
237	237		MakeObject;
238	238		obj:=NSMyObject.alloc.init.autorelease; // the same allocation code as in MakeObject proc
239	239		writeln('ref count = ', obj.retainCount);
240	240		obj.retain;
241	241		writeln('ref count = ', obj.retainCount);
242	242		finally
243	243		pool.release;
244	244		writeln('ref count = ', obj.retainCount);
245	245		end;
246	246		end;
247	247		```
248	248
249	249		the output of the program would be:
250	250
251	251		``` pascal
252	252		alloc: 4202000
253	253		calling ExtraProc()
254	254		alloc: 4201824 ; allocating the first object in ExtraProc
255	255		alloc: 4202048 ; allocating the second object in ExtraProc
256	256		ref count = 1 ; the reference count after allocation
257	257		ref count = 2 ; manually increasing the reference count by calling .retain
258	258		dealloc: 4201824 ; on release of the pool, the first object with reference count was removed.
259	259		ref count = 1 ; the second object had its reference count decreased to 1 and leaked
260	260		ExtraProc() done
261	261		dealloc: 4202000
262	262		```
263	263
264	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.
265	265
266	266		### App Event Loop and AutoreleasePools
267	267
268	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.
269	269
270	270		Cocoa Widgetset implements its own event queue, but the same rule remains enforced.
271	271
272	272		Make sure that an object that should stay alive after the event is not autoreleased.
273	273
274	274		### Object Ownership
275	275
276	276		As [Apple documentation](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmRules.html#//apple_ref/doc/uid/20000994-SW1) suggests:
277	277
278	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:
279	279
280	280		- You own any object you create
281	281
282	282
283	283		You create an object using a method whose name begins with “alloc”, “new”, “copy”, or “mutableCopy” (for example, alloc, newObject, or mutableCopy).
284	284
285	285		- You can take ownership of an object using retain
286	286
287	287
288	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).
289	289
290	290		- When you no longer need it, you must relinquish ownership of an object you own
291	291
292	292
293	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.
294	294
295	295		- You must not relinquish ownership of an object you do not own
296	296
297	297
298	298		This is just corollary of the previous policy rules, stated explicitly.
299	299
300	300		In practice, not following the serules, might cause unexpected errors in run-time.
301	301
302	302		#### Ownership Violation
303	303
304	304		Consider this following:
305	305
306	306		```delphi
307	307		{$mode objfpc}{$H+}
308	308		{$modeswitch objectivec2}
309	309		uses CocoaAll;
310	310		var
311	311		p : NSIndexSet;
312	312		begin
313	313		p:=NSIndexSet.indexSetWithIndex(10);
314	314		writeln('idx=',p.firstIndex,' refCount=',p.retainCount);
315	315		p.release; // a potential error
316	316		end.
317	317		```
318	318
319	319		If you try to execute the code, it would act as expected and produce no problems.
320	320
321	321		However, there's an error. The object was created using "indexSetWithindex" method.
322	322
323	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.
324	324
325	325		The run-time error will show up, if you try to put this code into Autorelease pool:
326	326
327	327		```delphi
328	328		var
329	329		p : NSIndexSet;
330	330		pool : NSAutoreleasePool;
331	331		begin
332	332		pool := NSAutoreleasePool.alloc.init;
333	333		p:=NSIndexSet.indexSetWithIndex(10);
334	334		writeln('idx=',p.firstIndex,' refCount=',p.retainCount);
335	335		p.release;
336	336		pool.release; // error here: *** error for object 0x308a70: pointer being freed was not allocated
337	337		end.
338	338		```
339	339
340	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).
341	341
342	342		There are two ways to fix the error:
343	343
344	344		1\) either alloc.initXXX pair should be used, that guaranteers the ownership of the object
345	345
346	346		```delphi
347	347		var
348	348		p : NSIndexSet;
349	349		pool : NSAutoreleasePool;
350	350		begin
351	351		pool := NSAutoreleasePool.alloc.init;
352	352		p:=NSIndexSet.alloc.initWithIndex(10);
353	353		writeln('idx=',p.firstIndex,' refCount=',p.retainCount);
354	354		p.release;
355	355		pool.release;
356	356		end.
357	357		```
358	358
359	359		2\) or the object should not be released explicitly
360	360
361	361		```delphi
362	362		var
363	363		p : NSIndexSet;
364	364		pool : NSAutoreleasePool;
365	365		begin
366	366		pool := NSAutoreleasePool.alloc.init;
367	367		p:=NSIndexSet.indexSetWithIndex(10);
368	368		writeln('idx=',p.firstIndex,' refCount=',p.retainCount);
369	369		pool.release;
370	370		end.
371	371		```
372	372
373	373		The actual approach depends on how NSIndexSet needs to be used in the code.
374	374
375	375		#### Using NSZombies
376	376
377	377		In the example below, the error typed into stderr is not very informative.
378	378
379	379		``` pascal
380	380		error here: *** error for object 0xNNNNNNNN: pointer being freed was not allocated
381	381		```
382	382
383	383		When there's potentially a great number of objects/code that could cause a double-release, it might be handy to use NSZombies.
384	384
385	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.
386	386
387	387		In order to enable NSZombies an environmental variable NSZombiesEnable must be set to "YES" (no quotes) declared at the time application starts.
388	388
389	389		Here's an example:
390	390
391	391		```delphi
392	392		program project1;
393	393
394	394		{$mode objfpc}{$H+}
395	395		{$modeswitch objectivec2}
396	396
397	397		uses
398	398		CocoaAll,SysUtils, Classes;
399	399
400	400		type
401	401		NSMyObject = objcclass(NSObject);
402	402
403	403		var
404	404		m: NSMyObject;
405	405		begin
406	406		m:=NSMyObject.alloc.init;
407	407		m.release;
408	408		m.release;
409	409		end.
410	410		```
411	411
412	412		In order to have the zombies enabled you might want to run the application from Terminal using the following commands:
413	413
414		-	~~```~~
	414	+	```text
415	415		export NSZombieEnabled="YES"
416	416		./project1
417	417		```
418	418
419	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)
420	420
421	421		when application fails, it would produce the following error message:
422	422
423		-	~~```~~
	423	+	```text
424	424		*** -[NSMyObject release]: message sent to deallocated instance 0x606d20
425	425		```
426	426
427	427		If you try to run the faulty code from ownership violation the error you'd see would be like this:
428	428
429		-	~~```~~
	429	+	```text
430	430		*** -[NSIndexSet release]: message sent to deallocated instance 0x605140
431	431		```
432	432
433	433		indicating that NSIndexSet was improperly released.
434	434
435	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.
436	436
437	437		## ObjC Object Leaks
438	438
439	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.
440	440
441	441		Apple provides external tools in its Xcode Instruments to keep track of ObjC allocations.
442	442
443	443		### Xcode Instruments
444	444
445	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.
446	446
447	447		- See further [Find abandoned memory](https://help.apple.com/instruments/mac/current/#/dev7b8f6eb6).
448	448
449	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.
450	450
451	451		- See further [Find memory leaks](https://help.apple.com/instruments/mac/current/#/dev022f987b).
452	452
453	453		## LCL Handles
454	454
455	455		Whenever CreatingHandle in Cocoa widgetset at least 1 NSView (or NSControl) is allocated. (Allocation makes a control with 1 reference count)
456	456
457	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.
458	458
459	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.
460	460
461	461		## See Also
462	462
463	463		- [[Cocoa Internals]]
464	464		- [Advanced Memory Management](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/MemoryMgmt/Articles/MemoryMgmt.html) - at Apple Developer
465	465
466	466		---
467	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).
468	468		Category: Cocoa
469	469		Category: macOS

Back to history