Cocoa Internals/Memory Management: what changed

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

Back to history