summaryrefslogtreecommitdiff
path: root/clang/docs/AutomaticReferenceCounting.html
blob: 1416df58e45efda508a967365d6a872dc3a83d5f (about) (plain) 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
          "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Objective-C Automatic Reference Counting (ARC)</title>
<link type="text/css" rel="stylesheet" href="../menu.css">
<link type="text/css" rel="stylesheet" href="../content.css">
<style type="text/css">
/* Collapse the items in the ToC to the left. */
div#toc ul {
  padding-left: 0
}

/* Rationales appear in italic. */
div.rationale {
  font-style: italic
}

div.rationale em {
  font-style: normal
}

/* Revisions are also italicized. */
span.revision {
  font-style: italic
}

span.whenRevised {
  font-weight: bold;
  font-style: normal
}

div h1 { font-size: 2em; margin: .67em 0 }
div div h1 { font-size: 1.5em; margin: .75em 0 }
div div div h1 { font-size: 1.17em; margin: .83em 0 }
div div div div h1 { margin: 1.12em 0 }

span.term { font-style: italic; font-weight: bold  }
</style>

<script type="text/javascript">
/// A little script to recursively build a table of contents.
function buildTOC(div, toc, ancestry) {
  var children = div.childNodes;
  var len = children.length;

  var childNumber = 0;

  var list = null;
  for (var i = 0; i < len; ++i) {
    var child = children[i];
    if (child.nodeName != "DIV") continue;
    if (child.getAttribute("class") == "rationale") continue;
    if (child.id == "toc") continue;

    // Okay, we're actually going to build a list node.
    if (list === null) list = document.createElement("ul");

    var childAncestry = ancestry + ++childNumber + ".";

    var headerNode = child.childNodes[1];
    var title = headerNode.innerHTML;
    headerNode.insertBefore(document.createTextNode(childAncestry + " "),
                            headerNode.firstChild);

    var item = document.createElement("li");
    item.appendChild(document.createTextNode(childAncestry + " "));

    var anchor = document.createElement("a");
    anchor.href = "#" + child.id;
    anchor.innerHTML = title;
    item.appendChild(anchor);

    buildTOC(child, item, childAncestry);

    list.appendChild(item);
  }
  if (list) toc.appendChild(list);
}

function onLoad() {
  var toc = document.getElementById("toc");
  var content = document.getElementById("content");
  buildTOC(content, toc, "");
}
window.onload = onLoad;

</script>
</head>
<body>

<!--#include virtual="../menu.html.incl"-->

<div id="content">
<h1>Automatic Reference Counting</h1>

<div id="toc">
</div>

<div id="meta">
<h1>About this document</h1>

<div id="meta.purpose">
<h1>Purpose</h1>

<p>The first and primary purpose of this document is to serve as a
complete technical specification of Automatic Reference Counting.
Given a core Objective-C compiler and runtime, it should be possible
to write a compiler and runtime which implements these new
semantics.</p>

<p>The secondary purpose is to act as a rationale for why ARC was
designed in this way.  This should remain tightly focused on the
technical design and should not stray into marketing speculation.</p>

</div> <!-- meta.purpose -->

<div id="meta.background">
<h1>Background</h1>

<p>This document assumes a basic familiarity with C.</p>

<p><span class="term">Blocks</span> are a C language extension for
creating anonymous functions.  Users interact with and transfer block
objects using <span class="term">block pointers</span>, which are
represented like a normal pointer.  A block may capture values from
local variables; when this occurs, memory must be dynamically
allocated.  The initial allocation is done on the stack, but the
runtime provides a <tt>Block_copy</tt> function which, given a block
pointer, either copies the underlying block object to the heap,
setting its reference count to 1 and returning the new block pointer,
or (if the block object is already on the heap) increases its
reference count by 1.  The paired function is <tt>Block_release</tt>,
which decreases the reference count by 1 and destroys the object if
the count reaches zero and is on the heap.</p>

<p>Objective-C is a set of language extensions, significant enough to
be considered a different language.  It is a strict superset of C.
The extensions can also be imposed on C++, producing a language called
Objective-C++.  The primary feature is a single-inheritance object
system; we briefly describe the modern dialect.</p>

<p>Objective-C defines a new type kind, collectively called
the <span class="term">object pointer types</span>.  This kind has two
notable builtin members, <tt>id</tt> and <tt>Class</tt>; <tt>id</tt>
is the final supertype of all object pointers.  The validity of
conversions between object pointer types is not checked at runtime.
Users may define <span class="term">classes</span>; each class is a
type, and the pointer to that type is an object pointer type.  A class
may have a superclass; its pointer type is a subtype of its
superclass's pointer type.  A class has a set
of <span class="term">ivars</span>, fields which appear on all
instances of that class.  For every class <i>T</i> there's an
associated metaclass; it has no fields, its superclass is the
metaclass of <i>T</i>'s superclass, and its metaclass is a global
class.  Every class has a global object whose class is the
class's metaclass; metaclasses have no associated type, so pointers to
this object have type <tt>Class</tt>.</p>

<p>A class declaration (<tt>@interface</tt>) declares a set
of <span class="term">methods</span>.  A method has a return type, a
list of argument types, and a <span class="term">selector</span>: a
name like <tt>foo:bar:baz:</tt>, where the number of colons
corresponds to the number of formal arguments.  A method may be an
instance method, in which case it can be invoked on objects of the
class, or a class method, in which case it can be invoked on objects
of the metaclass.  A method may be invoked by providing an object
(called the <span class="term">receiver</span>) and a list of formal
arguments interspersed with the selector, like so:</p>

<pre>[receiver foo: fooArg bar: barArg baz: bazArg]</pre>

<p>This looks in the dynamic class of the receiver for a method with
this name, then in that class's superclass, etc., until it finds
something it can execute.  The receiver <q>expression</q> may also be
the name of a class, in which case the actual receiver is the class
object for that class, or (within method definitions) it may
be <tt>super</tt>, in which case the lookup algorithm starts with the
static superclass instead of the dynamic class.  The actual methods
dynamically found in a class are not those declared in the
<tt>@interface</tt>, but those defined in a separate
<tt>@implementation</tt> declaration; however, when compiling a
call, typechecking is done based on the methods declared in the
<tt>@interface</tt>.</p>

<p>Method declarations may also be grouped into
<span class="term">protocols</span>, which are not inherently
associated with any class, but which classes may claim to follow.
Object pointer types may be qualified with additional protocols that
the object is known to support.</p>

<p><span class="term">Class extensions</span> are collections of ivars
and methods, designed to allow a class's <tt>@interface</tt> to be
split across multiple files; however, there is still a primary
implementation file which must see the <tt>@interface</tt>s of all
class extensions.
<span class="term">Categories</span> allow methods (but not ivars) to
be declared <i>post hoc</i> on an arbitrary class; the methods in the
category's <tt>@implementation</tt> will be dynamically added to that
class's method tables which the category is loaded at runtime,
replacing those methods in case of a collision.</p>

<p>In the standard environment, objects are allocated on the heap, and
their lifetime is manually managed using a reference count.  This is
done using two instance methods which all classes are expected to
implement: <tt>retain</tt> increases the object's reference count by
1, whereas <tt>release</tt> decreases it by 1 and calls the instance
method <tt>dealloc</tt> if the count reaches 0.  To simplify certain
operations, there is also an <span class="term">autorelease
pool</span>, a thread-local list of objects to call <tt>release</tt>
on later; an object can be added to this pool by
calling <tt>autorelease</tt> on it.</p>

<p>Block pointers may be converted to type <tt>id</tt>; block objects
are laid out in a way that makes them compatible with Objective-C
objects.  There is a builtin class that all block objects are
considered to be objects of; this class implements <tt>retain</tt> by
adjusting the reference count, not by calling <tt>Block_copy</tt>.</p>

</div> <!-- meta.background -->

<div id="meta.evolution">
<h1>Evolution</h1>

<p>ARC is under continual evolution, and this document must be updated
as the language progresses.</p>

<p>If a change increases the expressiveness of the language, for
example by lifting a restriction or by adding new syntax, the change
will be annotated with a revision marker, like so:</p>

<blockquote>
  ARC applies to Objective-C pointer types, block pointer types, and
  <span class="revision"><span class="whenRevised">[beginning Apple
  8.0, LLVM 3.8]</span> BPTRs declared within <code>extern
  "BCPL"</code> blocks</span>.
</blockquote>

<p>For now, it is sensible to version this document by the releases of
its sole implementation (and its host project), clang.
<q>LLVM X.Y</q> refers to an open-source release of clang from the
LLVM project.  <q>Apple X.Y</q> refers to an Apple-provided release of
the Apple LLVM Compiler.  Other organizations that prepare their own,
separately-versioned clang releases and wish to maintain similar
information in this document should send requests to cfe-dev.</p>

<p>If a change decreases the expressiveness of the language, for
example by imposing a new restriction, this should be taken as an
oversight in the original specification and something to be avoided
in all versions.  Such changes are generally to be avoided.</p>

</div> <!-- meta.evolution -->

</div> <!-- meta -->

<div id="general">
<h1>General</h1>

<p>Automatic Reference Counting implements automatic memory management
for Objective-C objects and blocks, freeing the programmer from the
need to explicitly insert retains and releases.  It does not provide a
cycle collector; users must explicitly manage the lifetime of their
objects, breaking cycles manually or with weak or unsafe
references.</p>

<p>ARC may be explicitly enabled with the compiler
flag <tt>-fobjc-arc</tt>.  It may also be explicitly disabled with the
compiler flag <tt>-fno-objc-arc</tt>.  The last of these two flags
appearing on the compile line <q>wins</q>.</p>

<p>If ARC is enabled, <tt>__has_feature(objc_arc)</tt> will expand to
1 in the preprocessor.  For more information about <tt>__has_feature</tt>,
see the <a href="LanguageExtensions.html#__has_feature_extension">language
extensions</a> document.</p>

</div>  <!-- general -->

<div id="objects">
<h1>Retainable object pointers</h1>

<p>This section describes retainable object pointers, their basic
operations, and the restrictions imposed on their use under ARC.  Note
in particular that it covers the rules for pointer <em>values</em>
(patterns of bits indicating the location of a pointed-to object), not
pointer
<em>objects</em> (locations in memory which store pointer values).
The rules for objects are covered in the next section.</p>

<p>A <span class="term">retainable object pointer</span>
(or <q>retainable pointer</q>) is a value of
a <span class="term">retainable object pointer type</span>
(<q>retainable type</q>).  There are three kinds of retainable object
pointer types:</p>
<ul>
<li>block pointers (formed by applying the caret (<tt>^</tt>)
declarator sigil to a function type)</li>
<li>Objective-C object pointers (<tt>id</tt>, <tt>Class</tt>, <tt>NSFoo*</tt>, etc.)</li>
<li>typedefs marked with <tt>__attribute__((NSObject))</tt></li>
</ul>

<p>Other pointer types, such as <tt>int*</tt> and <tt>CFStringRef</tt>,
are not subject to ARC's semantics and restrictions.</p>

<div class="rationale">

<p>Rationale: We are not at liberty to require
all code to be recompiled with ARC; therefore, ARC must interoperate
with Objective-C code which manages retains and releases manually.  In
general, there are three requirements in order for a
compiler-supported reference-count system to provide reliable
interoperation:</p>

<ul>
<li>The type system must reliably identify which objects are to be
managed.  An <tt>int*</tt> might be a pointer to a <tt>malloc</tt>'ed
array, or it might be a interior pointer to such an array, or it might
point to some field or local variable.  In contrast, values of the
retainable object pointer types are never interior.</li>
<li>The type system must reliably indicate how to
manage objects of a type.  This usually means that the type must imply
a procedure for incrementing and decrementing retain counts.
Supporting single-ownership objects requires a lot more explicit
mediation in the language.</li>
<li>There must be reliable conventions for whether and
when <q>ownership</q> is passed between caller and callee, for both
arguments and return values.  Objective-C methods follow such a
convention very reliably, at least for system libraries on Mac OS X,
and functions always pass objects at +0.  The C-based APIs for Core
Foundation objects, on the other hand, have much more varied transfer
semantics.</li>
</ul>
</div> <!-- rationale -->

<p>The use of <tt>__attribute__((NSObject))</tt> typedefs is not
recommended.  If it's absolutely necessary to use this attribute, be
very explicit about using the typedef, and do not assume that it will
be preserved by language features like <tt>__typeof</tt> and C++
template argument substitution.</p>

<div class="rationale"><p>Rationale: any compiler operation which
incidentally strips type <q>sugar</q> from a type will yield a type
without the attribute, which may result in unexpected
behavior.</p></div>

<div id="objects.retains">
<h1>Retain count semantics</h1>

<p>A retainable object pointer is either a <span class="term">null
pointer</span> or a pointer to a valid object.  Furthermore, if it has
block pointer type and is not <tt>null</tt> then it must actually be a
pointer to a block object, and if it has <tt>Class</tt> type (possibly
protocol-qualified) then it must actually be a pointer to a class
object.  Otherwise ARC does not enforce the Objective-C type system as
long as the implementing methods follow the signature of the static
type.  It is undefined behavior if ARC is exposed to an invalid
pointer.</p>

<p>For ARC's purposes, a valid object is one with <q>well-behaved</q>
retaining operations.  Specifically, the object must be laid out such
that the Objective-C message send machinery can successfully send it
the following messages:</p>

<ul>
<li><tt>retain</tt>, taking no arguments and returning a pointer to
the object.</li>
<li><tt>release</tt>, taking no arguments and returning <tt>void</tt>.</li>
<li><tt>autorelease</tt>, taking no arguments and returning a pointer
to the object.</li>
</ul>

<p>The behavior of these methods is constrained in the following ways.
The term <span class="term">high-level semantics</span> is an
intentionally vague term; the intent is that programmers must
implement these methods in a way such that the compiler, modifying
code in ways it deems safe according to these constraints, will not
violate their requirements.  For example, if the user puts logging
statements in <tt>retain</tt>, they should not be surprised if those
statements are executed more or less often depending on optimization
settings.  These constraints are not exhaustive of the optimization
opportunities: values held in local variables are subject to
additional restrictions, described later in this document.</p>

<p>It is undefined behavior if a computation history featuring a send
of <tt>retain</tt> followed by a send of <tt>release</tt> to the same
object, with no intervening <tt>release</tt> on that object, is not
equivalent under the high-level semantics to a computation
history in which these sends are removed.  Note that this implies that
these methods may not raise exceptions.</p>

<p>It is undefined behavior if a computation history features any use
whatsoever of an object following the completion of a send
of <tt>release</tt> that is not preceded by a send of <tt>retain</tt>
to the same object.</p>

<p>The behavior of <tt>autorelease</tt> must be equivalent to sending
<tt>release</tt> when one of the autorelease pools currently in scope
is popped.  It may not throw an exception.</p>

<p>When the semantics call for performing one of these operations on a
retainable object pointer, if that pointer is <tt>null</tt> then the
effect is a no-op.</p>

<p>All of the semantics described in this document are subject to
additional <a href="#optimization">optimization rules</a> which permit
the removal or optimization of operations based on local knowledge of
data flow.  The semantics describe the high-level behaviors that the
compiler implements, not an exact sequence of operations that a
program will be compiled into.</p>

</div> <!-- objects.retains -->

<div id="objects.operands">
<h1>Retainable object pointers as operands and arguments</h1>

<p>In general, ARC does not perform retain or release operations when
simply using a retainable object pointer as an operand within an
expression.  This includes:</p>
<ul>
<li>loading a retainable pointer from an object with non-weak
<a href="#ownership">ownership</a>,</li>
<li>passing a retainable pointer as an argument to a function or
method, and</li>
<li>receiving a retainable pointer as the result of a function or
method call.</li>
</ul>

<div class="rationale"><p>Rationale: while this might seem
uncontroversial, it is actually unsafe when multiple expressions are
evaluated in <q>parallel</q>, as with binary operators and calls,
because (for example) one expression might load from an object while
another writes to it.  However, C and C++ already call this undefined
behavior because the evaluations are unsequenced, and ARC simply
exploits that here to avoid needing to retain arguments across a large
number of calls.</p></div>

<p>The remainder of this section describes exceptions to these rules,
how those exceptions are detected, and what those exceptions imply
semantically.</p>

<div id="objects.operands.consumed">
<h1>Consumed parameters</h1>

<p>A function or method parameter of retainable object pointer type
may be marked as <span class="term">consumed</span>, signifying that
the callee expects to take ownership of a +1 retain count.  This is
done by adding the <tt>ns_consumed</tt> attribute to the parameter
declaration, like so:</p>

<pre>void foo(__attribute((ns_consumed)) id x);
- (void) foo: (id) __attribute((ns_consumed)) x;</pre>

<p>This attribute is part of the type of the function or method, not
the type of the parameter.  It controls only how the argument is
passed and received.</p>

<p>When passing such an argument, ARC retains the argument prior to
making the call.</p>

<p>When receiving such an argument, ARC releases the argument at the
end of the function, subject to the usual optimizations for local
values.</p>

<div class="rationale"><p>Rationale: this formalizes direct transfers
of ownership from a caller to a callee.  The most common scenario here
is passing the <tt>self</tt> parameter to <tt>init</tt>, but it is
useful to generalize.  Typically, local optimization will remove any
extra retains and releases: on the caller side the retain will be
merged with a +1 source, and on the callee side the release will be
rolled into the initialization of the parameter.</p></div>

<p>The implicit <tt>self</tt> parameter of a method may be marked as
consumed by adding <tt>__attribute__((ns_consumes_self))</tt> to the
method declaration.  Methods in the <tt>init</tt>
<a href="#family">family</a> are treated as if they were implicitly
marked with this attribute.</p>

<p>It is undefined behavior if an Objective-C message send to a method
with <tt>ns_consumed</tt> parameters (other than self) is made with a
null receiver.  It is undefined behavior if the method to which an
Objective-C message send statically resolves to has a different set
of <tt>ns_consumed</tt> parameters than the method it dynamically
resolves to.  It is undefined behavior if a block or function call is
made through a static type with a different set of <tt>ns_consumed</tt>
parameters than the implementation of the called block or function.</p>

<div class="rationale"><p>Rationale: consumed parameters with null
receiver are a guaranteed leak.  Mismatches with consumed parameters
will cause over-retains or over-releases, depending on the direction.
The rule about function calls is really just an application of the
existing C/C++ rule about calling functions through an incompatible
function type, but it's useful to state it explicitly.</p></div>

</div>  <!-- objects.operands.consumed -->

<div id="objects.operands.retained-returns">
<h1>Retained return values</h1>

<p>A function or method which returns a retainable object pointer type
may be marked as returning a retained value, signifying that the
caller expects to take ownership of a +1 retain count.  This is done
by adding the <tt>ns_returns_retained</tt> attribute to the function or
method declaration, like so:</p>

<pre>id foo(void) __attribute((ns_returns_retained));
- (id) foo __attribute((ns_returns_retained));</pre>

<p>This attribute is part of the type of the function or method.</p>

<p>When returning from such a function or method, ARC retains the
value at the point of evaluation of the return statement, before
leaving all local scopes.</p>

<p>When receiving a return result from such a function or method, ARC
releases the value at the end of the full-expression it is contained
within, subject to the usual optimizations for local values.</p>

<div class="rationale"><p>Rationale: this formalizes direct transfers of
ownership from a callee to a caller.  The most common scenario this
models is the retained return from <tt>init</tt>, <tt>alloc</tt>,
<tt>new</tt>, and <tt>copy</tt> methods, but there are other cases in
the frameworks.  After optimization there are typically no extra
retains and releases required.</p></div>

<p>Methods in
the <tt>alloc</tt>, <tt>copy</tt>, <tt>init</tt>, <tt>mutableCopy</tt>,
and <tt>new</tt> <a href="#family">families</a> are implicitly marked
<tt>__attribute__((ns_returns_retained))</tt>.  This may be suppressed
by explicitly marking the
method <tt>__attribute__((ns_returns_not_retained))</tt>.</p>

<p>It is undefined behavior if the method to which an Objective-C
message send statically resolves has different retain semantics on its
result from the method it dynamically resolves to.  It is undefined
behavior if a block or function call is made through a static type
with different retain semantics on its result from the implementation
of the called block or function.</p>

<div class="rationale"><p>Rationale: Mismatches with returned results
will cause over-retains or over-releases, depending on the direction.
Again, the rule about function calls is really just an application of
the existing C/C++ rule about calling functions through an
incompatible function type.</p></div>

</div>  <!-- objects.operands.retained-returns -->

<div id="objects.operands.other-returns">
<h1>Unretained return values</h1>

<p>A method or function which returns a retainable object type but
does not return a retained value must ensure that the object is
still valid across the return boundary.</p>

<p>When returning from such a function or method, ARC retains the
value at the point of evaluation of the return statement, then leaves
all local scopes, and then balances out the retain while ensuring that
the value lives across the call boundary.  In the worst case, this may
involve an <tt>autorelease</tt>, but callers must not assume that the
value is actually in the autorelease pool.</p>

<p>ARC performs no extra mandatory work on the caller side, although
it may elect to do something to shorten the lifetime of the returned
value.</p>

<div class="rationale"><p>Rationale: it is common in non-ARC code to not
return an autoreleased value; therefore the convention does not force
either path.  It is convenient to not be required to do unnecessary
retains and autoreleases; this permits optimizations such as eliding
retain/autoreleases when it can be shown that the original pointer
will still be valid at the point of return.</p></div>

<p>A method or function may be marked
with <tt>__attribute__((ns_returns_autoreleased))</tt> to indicate
that it returns a pointer which is guaranteed to be valid at least as
long as the innermost autorelease pool.  There are no additional
semantics enforced in the definition of such a method; it merely
enables optimizations in callers.</p>

</div>  <!-- objects.operands.other-returns -->

<div id="objects.operands.casts">
<h1>Bridged casts</h1>

<p>A <span class="term">bridged cast</span> is a C-style cast
annotated with one of three keywords:</p>

<ul>
<li><tt>(__bridge T) op</tt> casts the operand to the destination
type <tt>T</tt>.  If <tt>T</tt> is a retainable object pointer type,
then <tt>op</tt> must have a non-retainable pointer type.
If <tt>T</tt> is a non-retainable pointer type, then <tt>op</tt> must
have a retainable object pointer type.  Otherwise the cast is
ill-formed.  There is no transfer of ownership, and ARC inserts
no retain operations.</li>

<li><tt>(__bridge_retained T) op</tt> casts the operand, which must
have retainable object pointer type, to the destination type, which
must be a non-retainable pointer type.  ARC retains the value, subject
to the usual optimizations on local values, and the recipient is
responsible for balancing that +1.</li>

<li><tt>(__bridge_transfer T) op</tt> casts the operand, which must
have non-retainable pointer type, to the destination type, which must
be a retainable object pointer type.  ARC will release the value at
the end of the enclosing full-expression, subject to the usual
optimizations on local values.</li>
</ul>

<p>These casts are required in order to transfer objects in and out of
ARC control; see the rationale in the section
on <a href="#objects.restrictions.conversion">conversion of retainable
object pointers</a>.</p>

<p>Using a <tt>__bridge_retained</tt> or <tt>__bridge_transfer</tt>
cast purely to convince ARC to emit an unbalanced retain or release,
respectively, is poor form.</p>

</div>  <!-- objects.operands.casts -->

</div>  <!-- objects.operands -->

<div id="objects.restrictions">
<h1>Restrictions</h1>

<div id="objects.restrictions.conversion">
<h1>Conversion of retainable object pointers</h1>

<p>In general, a program which attempts to implicitly or explicitly
convert a value of retainable object pointer type to any
non-retainable type, or vice-versa, is ill-formed.  For example, an
Objective-C object pointer shall not be converted to <tt>void*</tt>. 
As an exception, cast to <tt>intptr_t</tt> is allowed because such 
casts are not transferring ownership. The <a href="#objects.operands.casts">bridged
casts</a> may be used to perform these conversions where
necessary.</p>

<div class="rationale"><p>Rationale: we cannot ensure the correct
management of the lifetime of objects if they may be freely passed
around as unmanaged types.  The bridged casts are provided so that the
programmer may explicitly describe whether the cast transfers control
into or out of ARC.</p></div>

<p>However, the following exceptions apply.</p>

</div>  <!-- objects.restrictions.conversion -->

<div id="objects.restrictions.conversion-exception-known">
<h1>Conversion to retainable object pointer type of
  expressions with known semantics</h1>

<p><span class="revision"><span class="whenRevised">[beginning Apple
  4.0, LLVM 3.1]</span> These exceptions have been greatly expanded;
  they previously applied only to a much-reduced subset which is
  difficult to categorize but which included null pointers, message
  sends (under the given rules), and the various global constants.</span></p>
  
<p>An unbridged conversion to a retainable object pointer type from a
type other than a retainable object pointer type is ill-formed, as
discussed above, unless the operand of the cast has a syntactic form
which is known retained, known unretained, or known
retain-agnostic.</p>

<p>An expression is <span class="term">known retain-agnostic</span> if
it is:</p>
<ul>
<li>an Objective-C string literal,</li>
<li>a load from a <tt>const</tt> system global variable of
<a href="#misc.c-retainable">C retainable pointer type</a>, or</li>
<li>a null pointer constant.</li>
</ul>

<p>An expression is <span class="term">known unretained</span> if it
is an rvalue of <a href="#misc.c-retainable">C retainable
pointer type</a> and it is:</p>
<ul>
<li>a direct call to a function, and either that function has the
  <tt>cf_returns_not_retained</tt> attribute or it is an
  <a href="#misc.c-retainable.audit">audited</a> function that does not
  have the <tt>cf_returns_retained</tt> attribute and does not follow
  the create/copy naming convention,</li>
<li>a message send, and the declared method either has
  the <tt>cf_returns_not_retained</tt> attribute or it has neither
  the <tt>cf_returns_retained</tt> attribute nor a
  <a href="#family">selector family</a> that implies a retained
  result.</li>
</ul>

<p>An expression is <span class="term">known retained</span> if it is
an rvalue of <a href="#misc.c-retainable">C retainable pointer type</a>
and it is:</p>
<ul>
<li>a message send, and the declared method either has the
  <tt>cf_returns_retained</tt> attribute, or it does not have
  the <tt>cf_returns_not_retained</tt> attribute but it does have a
  <a href="#family">selector family</a> that implies a retained
  result.</li>
</ul>

<p>Furthermore:</p>
<ul>
<li>a comma expression is classified according to its right-hand side,</li>
<li>a statement expression is classified according to its result
expression, if it has one,</li>
<li>an lvalue-to-rvalue conversion applied to an Objective-C property
lvalue is classified according to the underlying message send, and</li>
<li>a conditional operator is classified according to its second and
third operands, if they agree in classification, or else the other
if one is known retain-agnostic.</li>
</ul>

<p>If the cast operand is known retained, the conversion is treated as
a <tt>__bridge_transfer</tt> cast.  If the cast operand is known
unretained or known retain-agnostic, the conversion is treated as
a <tt>__bridge</tt> cast.</p>

<div class="rationale"><p>Rationale: Bridging casts are annoying.
Absent the ability to completely automate the management of CF
objects, however, we are left with relatively poor attempts to reduce
the need for a glut of explicit bridges.  Hence these rules.</p>

<p>We've so far consciously refrained from implicitly turning retained
CF results from function calls into <tt>__bridge_transfer</tt> casts.
The worry is that some code patterns &mdash; for example, creating a
CF value, assigning it to an ObjC-typed local, and then
calling <tt>CFRelease</tt> when done &mdash; are a bit too likely to
be accidentally accepted, leading to mysterious behavior.</p></div>

</div>  <!-- objects.restrictions.conversion-exception-known -->

<div id="objects.restrictions.conversion-exception-contextual">
<h1>Conversion from retainable object pointer type in certain contexts</h1>

<p><span class="revision"><span class="whenRevised">[beginning Apple
  4.0, LLVM 3.1]</span></span></p>

<p>If an expression of retainable object pointer type is explicitly
cast to a <a href="#misc.c-retainable">C retainable pointer type</a>,
the program is ill-formed as discussed above unless the result is
immediately used:</p>

<ul>
<li>to initialize a parameter in an Objective-C message send where the
parameter is not marked with the <tt>cf_consumed</tt> attribute, or</li>
<li>to initialize a parameter in a direct call to
an <a href="#misc.c-retainable.audit">audited</a> function where the
parameter is not marked with the <tt>cf_consumed</tt> attribute.</li>
</ul>

<div class="rationale"><p>Rationale: Consumed parameters are left out
because ARC would naturally balance them with a retain, which was
judged too treacherous.  This is in part because several of the most
common consuming functions are in the <tt>Release</tt> family, and it
would be quite unfortunate for explicit releases to be silently
balanced out in this way.</p></div>

</div>  <!-- objects.restrictions.conversion-exception-contextual -->

</div>  <!-- objects.restrictions -->

</div>  <!-- objects -->

<div id="ownership">
<h1>Ownership qualification</h1>

<p>This section describes the behavior of <em>objects</em> of
retainable object pointer type; that is, locations in memory which
store retainable object pointers.</p>

<p>A type is a <span class="term">retainable object owner type</span>
if it is a retainable object pointer type or an array type whose
element type is a retainable object owner type.</p>

<p>An <span class="term">ownership qualifier</span> is a type
qualifier which applies only to retainable object owner types. An array type is
ownership-qualified according to its element type, and adding an ownership 
qualifier to an array type so qualifies its element type.</p>

<p>A program is ill-formed if it attempts to apply an ownership qualifier
to a type which is already ownership-qualified, even if it is the same
qualifier. There is a single exception to this rule: an ownership qualifier 
may be applied to a substituted template type parameter, which overrides the
ownership qualifier provided by the template argument.</p>

<p>Except as described under
the <a href="#ownership.inference">inference rules</a>, a program is
ill-formed if it attempts to form a pointer or reference type to a
retainable object owner type which lacks an ownership qualifier.</p>

<div class="rationale"><p>Rationale: these rules, together with the
inference rules, ensure that all objects and lvalues of retainable
object pointer type have an ownership qualifier. The ability to override an ownership qualifier during template substitution is required to counteract the <a href="#ownership.inference.template_arguments">inference of <tt>__strong</tt> for template type arguments</a>. </p></div>

<p>There are four ownership qualifiers:</p>

<ul>
<li><tt>__autoreleasing</tt></li>
<li><tt>__strong</tt></li>
<li><tt>__unsafe_unretained</tt></li>
<li><tt>__weak</tt></li>
</ul>

<p>A type is <span class="term">nontrivially ownership-qualified</span>
if it is qualified with <tt>__autoreleasing</tt>, <tt>__strong</tt>, or
<tt>__weak</tt>.</p>

<div id="ownership.spelling">
<h1>Spelling</h1>

<p>The names of the ownership qualifiers are reserved for the
implementation.  A program may not assume that they are or are not
implemented with macros, or what those macros expand to.</p>

<p>An ownership qualifier may be written anywhere that any other type
qualifier may be written.</p>

<p>If an ownership qualifier appears in
the <i>declaration-specifiers</i>, the following rules apply:</p>

<ul>
<li>if the type specifier is a retainable object owner type, the
qualifier applies to that type;</li>
<li>if the outermost non-array part of the declarator is a pointer or
block pointer, the qualifier applies to that type;</li>
<li>otherwise the program is ill-formed.</li>
</ul>

<p>If an ownership qualifier appears on the declarator name, or on the
declared object, it is applied to outermost pointer or block-pointer
type.</p>

<p>If an ownership qualifier appears anywhere else in a declarator, it
applies to the type there.</p>

<div id="ownership.spelling.property">
<h1>Property declarations</h1>

<p>A property of retainable object pointer type may have ownership.
If the property's type is ownership-qualified, then the property has
that ownership.  If the property has one of the following modifiers,
then the property has the corresponding ownership.  A property is
ill-formed if it has conflicting sources of ownership, or if it has
redundant ownership modifiers, or if it has <tt>__autoreleasing</tt>
ownership.</p>

<ul>
<li><tt>assign</tt> implies <tt>__unsafe_unretained</tt> ownership.</li>
<li><tt>copy</tt> implies <tt>__strong</tt> ownership, as well as the
  usual behavior of copy semantics on the setter.</li>
<li><tt>retain</tt> implies <tt>__strong</tt> ownership.</li>
<li><tt>strong</tt> implies <tt>__strong</tt> ownership.</li>
<li><tt>unsafe_unretained</tt> implies <tt>__unsafe_unretained</tt>
  ownership.</li>
<li><tt>weak</tt> implies <tt>__weak</tt> ownership.</li>
</ul>

<p>With the exception of <tt>weak</tt>, these modifiers are available
in non-ARC modes.</p>

<p>A property's specified ownership is preserved in its metadata, but
otherwise the meaning is purely conventional unless the property is
synthesized.  If a property is synthesized, then the
<span class="term">associated instance variable</span> is the
instance variable which is named, possibly implicitly, by the
<tt>@synthesize</tt> declaration.  If the associated instance variable
already exists, then its ownership qualification must equal the
ownership of the property; otherwise, the instance variable is created
with that ownership qualification.</p>

<p>A property of retainable object pointer type which is synthesized
without a source of ownership has the ownership of its associated
instance variable, if it already exists; otherwise,
<span class="revision"><span class="whenRevised">[beginning Apple 3.1,
LLVM 3.1]</span> its ownership is implicitly <tt>strong</tt></span>.
Prior to this revision, it was ill-formed to synthesize such a
property.</p>

<div class="rationale"><p>Rationale: using <tt>strong</tt> by default
is safe and consistent with the generic ARC rule about
<a href="#ownership.inference.variables">inferring ownership</a>.  It
is, unfortunately, inconsistent with the non-ARC rule which states
that such properties are implicitly <tt>assign</tt>.  However, that
rule is clearly untenable in ARC, since it leads to default-unsafe
code.  The main merit to banning the properties is to avoid confusion
with non-ARC practice, which did not ultimately strike us as
sufficient to justify requiring extra syntax and (more importantly)
forcing novices to understand ownership rules just to declare a
property when the default is so reasonable.  Changing the rule away
from non-ARC practice was acceptable because we had conservatively
banned the synthesis in order to give ourselves exactly this
leeway.</p></div>

</div> <!-- ownership.spelling.property -->

</div> <!-- ownership.spelling -->

<div id="ownership.semantics">
<h1>Semantics</h1>

<p>There are five <span class="term">managed operations</span> which
may be performed on an object of retainable object pointer type.  Each
qualifier specifies different semantics for each of these operations.
It is still undefined behavior to access an object outside of its
lifetime.</p>

<p>A load or store with <q>primitive semantics</q> has the same
semantics as the respective operation would have on an <tt>void*</tt>
lvalue with the same alignment and non-ownership qualification.</p>

<p><span class="term">Reading</span> occurs when performing a
lvalue-to-rvalue conversion on an object lvalue.</p>

<ul>
<li>For <tt>__weak</tt> objects, the current pointee is retained and
then released at the end of the current full-expression.  This must
execute atomically with respect to assignments and to the final
release of the pointee.</li>
<li>For all other objects, the lvalue is loaded with primitive
semantics.</li>
</ul>

<p><span class="term">Assignment</span> occurs when evaluating
an assignment operator.  The semantics vary based on the qualification:</p>
<ul>
<li>For <tt>__strong</tt> objects, the new pointee is first retained;
second, the lvalue is loaded with primitive semantics; third, the new
pointee is stored into the lvalue with primitive semantics; and
finally, the old pointee is released.  This is not performed
atomically; external synchronization must be used to make this safe in
the face of concurrent loads and stores.</li>
<li>For <tt>__weak</tt> objects, the lvalue is updated to point to the
new pointee, unless the new pointee is an object currently undergoing
deallocation, in which case the lvalue is updated to a null pointer.
This must execute atomically with respect to other assignments to the
object, to reads from the object, and to the final release of the new
pointee.</li>
<li>For <tt>__unsafe_unretained</tt> objects, the new pointee is
stored into the lvalue using primitive semantics.</li>
<li>For <tt>__autoreleasing</tt> objects, the new pointee is retained,
autoreleased, and stored into the lvalue using primitive semantics.</li>
</ul>

<p><span class="term">Initialization</span> occurs when an object's
lifetime begins, which depends on its storage duration.
Initialization proceeds in two stages:</p>
<ol>
<li>First, a null pointer is stored into the lvalue using primitive
semantics.  This step is skipped if the object
is <tt>__unsafe_unretained</tt>.</li>
<li>Second, if the object has an initializer, that expression is
evaluated and then assigned into the object using the usual assignment
semantics.</li>
</ol>

<p><span class="term">Destruction</span> occurs when an object's
lifetime ends.  In all cases it is semantically equivalent to
assigning a null pointer to the object, with the proviso that of
course the object cannot be legally read after the object's lifetime
ends.</p>

<p><span class="term">Moving</span> occurs in specific situations
where an lvalue is <q>moved from</q>, meaning that its current pointee
will be used but the object may be left in a different (but still
valid) state.  This arises with <tt>__block</tt> variables and rvalue
references in C++. For <tt>__strong</tt> lvalues, moving is equivalent
to loading the lvalue with primitive semantics, writing a null pointer
to it with primitive semantics, and then releasing the result of the
load at the end of the current full-expression.  For all other
lvalues, moving is equivalent to reading the object.</p>

</div> <!-- ownership.semantics -->

<div id="ownership.restrictions">
<h1>Restrictions</h1>

<div id="ownership.restrictions.weak">
<h1>Weak-unavailable types</h1>

<p>It is explicitly permitted for Objective-C classes to not
support <tt>__weak</tt> references.  It is undefined behavior to
perform an operation with weak assignment semantics with a pointer to
an Objective-C object whose class does not support <tt>__weak</tt>
references.</p>

<div class="rationale"><p>Rationale: historically, it has been
possible for a class to provide its own reference-count implementation
by overriding <tt>retain</tt>, <tt>release</tt>, etc.  However, weak
references to an object require coordination with its class's
reference-count implementation because, among other things, weak loads
and stores must be atomic with respect to the final release.
Therefore, existing custom reference-count implementations will
generally not support weak references without additional effort.  This
is unavoidable without breaking binary compatibility.</p></div>

<p>A class may indicate that it does not support weak references by
providing the <tt>objc_arc_weak_unavailable</tt> attribute on the
class's interface declaration.  A retainable object pointer type
is <span class="term">weak-unavailable</span> if is a pointer to an
(optionally protocol-qualified) Objective-C class <tt>T</tt>
where <tt>T</tt> or one of its superclasses has
the <tt>objc_arc_weak_unavailable</tt> attribute.  A program is
ill-formed if it applies the <tt>__weak</tt> ownership qualifier to a
weak-unavailable type or if the value operand of a weak assignment
operation has a weak-unavailable type.</p>
</div> <!-- ownership.restrictions.weak -->

<div id="ownership.restrictions.autoreleasing">
<h1>Storage duration of <tt>__autoreleasing</tt> objects</h1>

<p>A program is ill-formed if it declares an <tt>__autoreleasing</tt>
object of non-automatic storage duration.  A program is ill-formed
if it captures an <tt>__autoreleasing</tt> object in a block or,
unless by reference, in a C++11 lambda.</p>

<div class="rationale"><p>Rationale: autorelease pools are tied to the
current thread and scope by their nature.  While it is possible to
have temporary objects whose instance variables are filled with
autoreleased objects, there is no way that ARC can provide any sort of
safety guarantee there.</p></div>

<p>It is undefined behavior if a non-null pointer is assigned to
an <tt>__autoreleasing</tt> object while an autorelease pool is in
scope and then that object is read after the autorelease pool's scope
is left.</p>

</div>

<div id="ownership.restrictions.conversion.indirect">
<h1>Conversion of pointers to ownership-qualified types</h1>

<p>A program is ill-formed if an expression of type <tt>T*</tt> is
converted, explicitly or implicitly, to the type <tt>U*</tt>,
where <tt>T</tt> and <tt>U</tt> have different ownership
qualification, unless:</p>
<ul>
<li><tt>T</tt> is qualified with <tt>__strong</tt>,
 <tt>__autoreleasing</tt>, or <tt>__unsafe_unretained</tt>, and
 <tt>U</tt> is qualified with both <tt>const</tt> and
 <tt>__unsafe_unretained</tt>; or</li>
<li>either <tt>T</tt> or <tt>U</tt> is <tt>cv void</tt>, where
<tt>cv</tt> is an optional sequence of non-ownership qualifiers; or</li>
<li>the conversion is requested with a <tt>reinterpret_cast</tt> in
 Objective-C++; or</li>
<li>the conversion is a
well-formed <a href="#ownership.restrictions.pass_by_writeback">pass-by-writeback</a>.</li>
</ul>

<p>The analogous rule applies to <tt>T&amp;</tt> and <tt>U&amp;</tt> in
Objective-C++.</p>

<div class="rationale"><p>Rationale: these rules provide a reasonable
level of type-safety for indirect pointers, as long as the underlying
memory is not deallocated.  The conversion to <tt>const
__unsafe_unretained</tt> is permitted because the semantics of reads
are equivalent across all these ownership semantics, and that's a very
useful and common pattern.  The interconversion with <tt>void*</tt> is
useful for allocating memory or otherwise escaping the type system,
but use it carefully.  <tt>reinterpret_cast</tt> is considered to be
an obvious enough sign of taking responsibility for any
problems.</p></div>

<p>It is undefined behavior to access an ownership-qualified object
through an lvalue of a differently-qualified type, except that any
non-<tt>__weak</tt> object may be read through
an <tt>__unsafe_unretained</tt> lvalue.</p>

<p>It is undefined behavior if a managed operation is performed on
a <tt>__strong</tt> or <tt>__weak</tt> object without a guarantee that
it contains a primitive zero bit-pattern, or if the storage for such
an object is freed or reused without the object being first assigned a
null pointer.</p>

<div class="rationale"><p>Rationale: ARC cannot differentiate between
an assignment operator which is intended to <q>initialize</q> dynamic
memory and one which is intended to potentially replace a value.
Therefore the object's pointer must be valid before letting ARC at it.
Similarly, C and Objective-C do not provide any language hooks for
destroying objects held in dynamic memory, so it is the programmer's
responsibility to avoid leaks (<tt>__strong</tt> objects) and
consistency errors (<tt>__weak</tt> objects).</p>

<p>These requirements are followed automatically in Objective-C++ when
creating objects of retainable object owner type with <tt>new</tt>
or <tt>new[]</tt> and destroying them with <tt>delete</tt>,
<tt>delete[]</tt>, or a pseudo-destructor expression.  Note that
arrays of nontrivially-ownership-qualified type are not ABI compatible
with non-ARC code because the element type is non-POD: such arrays
that are <tt>new[]</tt>'d in ARC translation units cannot
be <tt>delete[]</tt>'d in non-ARC translation units and
vice-versa.</p></div>

</div>

<div id="ownership.restrictions.pass_by_writeback">
<h1>Passing to an out parameter by writeback</h1>

<p>If the argument passed to a parameter of type
<tt>T __autoreleasing *</tt> has type <tt>U oq *</tt>,
where <tt>oq</tt> is an ownership qualifier, then the argument is a
candidate for <span class="term">pass-by-writeback</span> if:</p>

<ul>
<li><tt>oq</tt> is <tt>__strong</tt> or <tt>__weak</tt>, and</li>
<li>it would be legal to initialize a <tt>T __strong *</tt> with
a <tt>U __strong *</tt>.</li>
</ul>

<p>For purposes of overload resolution, an implicit conversion
sequence requiring a pass-by-writeback is always worse than an
implicit conversion sequence not requiring a pass-by-writeback.</p>

<p>The pass-by-writeback is ill-formed if the argument expression does
not have a legal form:</p>

<ul>
<li><tt>&amp;var</tt>, where <tt>var</tt> is a scalar variable of
automatic storage duration with retainable object pointer type</li>
<li>a conditional expression where the second and third operands are
both legal forms</li>
<li>a cast whose operand is a legal form</li>
<li>a null pointer constant</li>
</ul>

<div class="rationale"><p>Rationale: the restriction in the form of
the argument serves two purposes.  First, it makes it impossible to
pass the address of an array to the argument, which serves to protect
against an otherwise serious risk of mis-inferring an <q>array</q>
argument as an out-parameter.  Second, it makes it much less likely
that the user will see confusing aliasing problems due to the
implementation, below, where their store to the writeback temporary is
not immediately seen in the original argument variable.</p></div>

<p>A pass-by-writeback is evaluated as follows:</p>
<ol>
<li>The argument is evaluated to yield a pointer <tt>p</tt> of
 type <tt>U oq *</tt>.</li>
<li>If <tt>p</tt> is a null pointer, then a null pointer is passed as
 the argument, and no further work is required for the pass-by-writeback.</li>
<li>Otherwise, a temporary of type <tt>T __autoreleasing</tt> is
 created and initialized to a null pointer.</li>
<li>If the parameter is not an Objective-C method parameter marked
 <tt>out</tt>, then <tt>*p</tt> is read, and the result is written
 into the temporary with primitive semantics.</li>
<li>The address of the temporary is passed as the argument to the
 actual call.</li>
<li>After the call completes, the temporary is loaded with primitive
 semantics, and that value is assigned into <tt>*p</tt>.</li>
</ol>

<div class="rationale"><p>Rationale: this is all admittedly
convoluted.  In an ideal world, we would see that a local variable is
being passed to an out-parameter and retroactively modify its type to
be <tt>__autoreleasing</tt> rather than <tt>__strong</tt>.  This would
be remarkably difficult and not always well-founded under the C type
system.  However, it was judged unacceptably invasive to require
programmers to write <tt>__autoreleasing</tt> on all the variables
they intend to use for out-parameters.  This was the least bad
solution.</p></div>

</div>

<div id="ownership.restrictions.records">
<h1>Ownership-qualified fields of structs and unions</h1>

<p>A program is ill-formed if it declares a member of a C struct or
union to have a nontrivially ownership-qualified type.</p>

<div class="rationale"><p>Rationale: the resulting type would be
non-POD in the C++ sense, but C does not give us very good language
tools for managing the lifetime of aggregates, so it is more
convenient to simply forbid them.  It is still possible to manage this
with a <tt>void*</tt> or an <tt>__unsafe_unretained</tt>
object.</p></div>

<p>This restriction does not apply in Objective-C++.  However,
nontrivally ownership-qualified types are considered non-POD: in C++11
terms, they are not trivially default constructible, copy
constructible, move constructible, copy assignable, move assignable,
or destructible.  It is a violation of C++'s One Definition Rule to use
a class outside of ARC that, under ARC, would have a nontrivially
ownership-qualified member.</p>

<div class="rationale"><p>Rationale: unlike in C, we can express all
the necessary ARC semantics for ownership-qualified subobjects as
suboperations of the (default) special member functions for the class.
These functions then become non-trivial.  This has the non-obvious
result that the class will have a non-trivial copy constructor and
non-trivial destructor; if this would not normally be true outside of
ARC, objects of the type will be passed and returned in an
ABI-incompatible manner.</p></div>

</div>

</div>

<div id="ownership.inference">
<h1>Ownership inference</h1>

<div id="ownership.inference.variables">
<h1>Objects</h1>

<p>If an object is declared with retainable object owner type, but
without an explicit ownership qualifier, its type is implicitly
adjusted to have <tt>__strong</tt> qualification.</p>

<p>As a special case, if the object's base type is <tt>Class</tt>
(possibly protocol-qualified), the type is adjusted to
have <tt>__unsafe_unretained</tt> qualification instead.</p>

</div>

<div id="ownership.inference.indirect_parameters">
<h1>Indirect parameters</h1>

<p>If a function or method parameter has type <tt>T*</tt>, where
<tt>T</tt> is an ownership-unqualified retainable object pointer type,
then:</p>

<ul>
<li>if <tt>T</tt> is <tt>const</tt>-qualified or <tt>Class</tt>, then
it is implicitly qualified with <tt>__unsafe_unretained</tt>;</li>
<li>otherwise, it is implicitly qualified
with <tt>__autoreleasing</tt>.</li>
</ul>

<div class="rationale"><p>Rationale: <tt>__autoreleasing</tt> exists
mostly for this case, the Cocoa convention for out-parameters.  Since
a pointer to <tt>const</tt> is obviously not an out-parameter, we
instead use a type more useful for passing arrays.  If the user
instead intends to pass in a <em>mutable</em> array, inferring
<tt>__autoreleasing</tt> is the wrong thing to do; this directs some
of the caution in the following rules about writeback.</p></div>

<p>Such a type written anywhere else would be ill-formed by the
general rule requiring ownership qualifiers.</p>

<p>This rule does not apply in Objective-C++ if a parameter's type is
dependent in a template pattern and is only <em>instantiated</em> to
a type which would be a pointer to an unqualified retainable object
pointer type.  Such code is still ill-formed.</p>

<div class="rationale"><p>Rationale: the convention is very unlikely
to be intentional in template code.</p></div>

</div> <!-- ownership.inference.indirect_parameters -->

<div id="ownership.inference.template_arguments">
<h1>Template arguments</h1>

<p>If a template argument for a template type parameter is an
retainable object owner type that does not have an explicit ownership
qualifier, it is adjusted to have <tt>__strong</tt>
qualification. This adjustment occurs regardless of whether the
template argument was deduced or explicitly specified. </p>

<div class="rationale"><p>Rationale: <tt>__strong</tt> is a useful default for containers (e.g., <tt>std::vector&lt;id&gt;</tt>), which would otherwise require explicit qualification. Moreover, unqualified retainable object pointer types are unlikely to be useful within templates, since they generally need to have a qualifier applied to the before being used.</p></div>

</div> <!-- ownership.inference.template_arguments -->
</div> <!-- ownership.inference -->
</div> <!-- ownership -->


<div id="family">
<h1>Method families</h1>

<p>An Objective-C method may fall into a <span class="term">method
family</span>, which is a conventional set of behaviors ascribed to it
by the Cocoa conventions.</p>

<p>A method is in a certain method family if:</p>
<ul>
<li>it has a <tt>objc_method_family</tt> attribute placing it in that
 family; or if not that,</li>
<li>it does not have an <tt>objc_method_family</tt> attribute placing
 it in a different or no family, and</li>
<li>its selector falls into the corresponding selector family, and</li>
<li>its signature obeys the added restrictions of the method family.</li>
</ul>

<p>A selector is in a certain selector family if, ignoring any leading
underscores, the first component of the selector either consists
entirely of the name of the method family or it begins with that name
followed by a character other than a lowercase letter.  For
example, <tt>_perform:with:</tt> and <tt>performWith:</tt> would fall
into the <tt>perform</tt> family (if we recognized one),
but <tt>performing:with</tt> would not.</p>

<p>The families and their added restrictions are:</p>

<ul>
<li><tt>alloc</tt> methods must return a retainable object pointer type.</li>
<li><tt>copy</tt> methods must return a retainable object pointer type.</li>
<li><tt>mutableCopy</tt> methods must return a retainable object pointer type.</li>
<li><tt>new</tt> methods must return a retainable object pointer type.</li>
<li><tt>init</tt> methods must be instance methods and must return an
Objective-C pointer type.  Additionally, a program is ill-formed if it
declares or contains a call to an <tt>init</tt> method whose return
type is neither <tt>id</tt> nor a pointer to a super-class or
sub-class of the declaring class (if the method was declared on
a class) or the static receiver type of the call (if it was declared
on a protocol).

<div class="rationale"><p>Rationale: there are a fair number of existing
methods with <tt>init</tt>-like selectors which nonetheless don't
follow the <tt>init</tt> conventions.  Typically these are either
accidental naming collisions or helper methods called during
initialization.  Because of the peculiar retain/release behavior
of <tt>init</tt> methods, it's very important not to treat these
methods as <tt>init</tt> methods if they aren't meant to be.  It was
felt that implicitly defining these methods out of the family based on
the exact relationship between the return type and the declaring class
would be much too subtle and fragile.  Therefore we identify a small
number of legitimate-seeming return types and call everything else an
error.  This serves the secondary purpose of encouraging programmers
not to accidentally give methods names in the <tt>init</tt> family.</p>

<p>Note that a method with an <tt>init</tt>-family selector which
returns a non-Objective-C type (e.g. <tt>void</tt>) is perfectly
well-formed; it simply isn't in the <tt>init</tt> family.</p></div>
</li>
</ul>

<p>A program is ill-formed if a method's declarations,
implementations, and overrides do not all have the same method
family.</p>

<div id="family.attribute">
<h1>Explicit method family control</h1>

<p>A method may be annotated with the <tt>objc_method_family</tt>
attribute to precisely control which method family it belongs to.  If
a method in an <tt>@implementation</tt> does not have this attribute,
but there is a method declared in the corresponding <tt>@interface</tt>
that does, then the attribute is copied to the declaration in the
<tt>@implementation</tt>.  The attribute is available outside of ARC,
and may be tested for with the preprocessor query
<tt>__has_attribute(objc_method_family)</tt>.</p>

<p>The attribute is spelled
<tt>__attribute__((objc_method_family(<i>family</i>)))</tt>.
If <i>family</i> is <tt>none</tt>, the method has no family, even if
it would otherwise be considered to have one based on its selector and
type.  Otherwise, <i>family</i> must be one
of <tt>alloc</tt>, <tt>copy</tt>, <tt>init</tt>,
<tt>mutableCopy</tt>, or <tt>new</tt>, in which case the method is
considered to belong to the corresponding family regardless of its
selector.  It is an error if a method that is explicitly added to a
family in this way does not meet the requirements of the family other
than the selector naming convention.</p>

<div class="rationale"><p>Rationale: the rules codified in this document
describe the standard conventions of Objective-C.  However, as these
conventions have not heretofore been enforced by an unforgiving
mechanical system, they are only imperfectly kept, especially as they
haven't always even been precisely defined.  While it is possible to
define low-level ownership semantics with attributes like
<tt>ns_returns_retained</tt>, this attribute allows the user to
communicate semantic intent, which is of use both to ARC (which, e.g.,
treats calls to <tt>init</tt> specially) and the static analyzer.</p></div>
</div>

<div id="family.semantics">
<h1>Semantics of method families</h1>

<p>A method's membership in a method family may imply non-standard
semantics for its parameters and return type.</p>

<p>Methods in the <tt>alloc</tt>, <tt>copy</tt>, <tt>mutableCopy</tt>,
and <tt>new</tt> families &mdash; that is, methods in all the
currently-defined families except <tt>init</tt> &mdash; implicitly
<a href="#objects.operands.retained_returns">return a retained
object</a> as if they were annotated with
the <tt>ns_returns_retained</tt> attribute.  This can be overridden by
annotating the method with either of
the <tt>ns_returns_autoreleased</tt> or
<tt>ns_returns_not_retained</tt> attributes.</p>

<p>Properties also follow same naming rules as methods. This means that 
those in the <tt>alloc</tt>, <tt>copy</tt>, <tt>mutableCopy</tt>,
and <tt>new</tt> families provide access to 
<a href="#objects.operands.retained_returns">retained objects</a>. 
This can be overridden by annotating the property with 
<tt>ns_returns_not_retained</tt> attribute.</p>

<div id="family.semantics.init">
<h1>Semantics of <tt>init</tt></h1>
<p>Methods in the <tt>init</tt> family implicitly
<a href="#objects.operands.consumed">consume</a> their <tt>self</tt>
parameter and <a href="#objects.operands.retained_returns">return a
retained object</a>.  Neither of these properties can be altered
through attributes.</p>

<p>A call to an <tt>init</tt> method with a receiver that is either
<tt>self</tt> (possibly parenthesized or casted) or <tt>super</tt> is
called a <span class="term">delegate init call</span>.  It is an error
for a delegate init call to be made except from an <tt>init</tt>
method, and excluding blocks within such methods.</p>

<p>As an exception to the <a href="misc.self">usual rule</a>, the
variable <tt>self</tt> is mutable in an <tt>init</tt> method and has
the usual semantics for a <tt>__strong</tt> variable.  However, it is
undefined behavior and the program is ill-formed, no diagnostic
required, if an <tt>init</tt> method attempts to use the previous
value of <tt>self</tt> after the completion of a delegate init call.
It is conventional, but not required, for an <tt>init</tt> method to
return <tt>self</tt>.</p>

<p>It is undefined behavior for a program to cause two or more calls
to <tt>init</tt> methods on the same object, except that
each <tt>init</tt> method invocation may perform at most one delegate
init call.</p>

</div> <!-- family.semantics.init -->

<div id="family.semantics.result_type">
<h1>Related result types</h1>

<p>Certain methods are candidates to have <span class="term">related
result types</span>:</p>
<ul>
<li>class methods in the <tt>alloc</tt> and <tt>new</tt> method families</li>
<li>instance methods in the <tt>init</tt> family</li>
<li>the instance method <tt>self</tt></li>
<li>outside of ARC, the instance methods <tt>retain</tt> and <tt>autorelease</tt></li>
</ul>

<p>If the formal result type of such a method is <tt>id</tt> or
protocol-qualified <tt>id</tt>, or a type equal to the declaring class
or a superclass, then it is said to have a related result type.  In
this case, when invoked in an explicit message send, it is assumed to
return a type related to the type of the receiver:</p>

<ul>
<li>if it is a class method, and the receiver is a class
name <tt>T</tt>, the message send expression has type <tt>T*</tt>;
otherwise</li>
<li>if it is an instance method, and the receiver has type <tt>T</tt>,
the message send expression has type <tt>T</tt>; otherwise</li>
<li>the message send expression has the normal result type of the
method.</li>
</ul>

<p>This is a new rule of the Objective-C language and applies outside
of ARC.</p>

<div class="rationale"><p>Rationale: ARC's automatic code emission is
more prone than most code to signature errors, i.e. errors where a
call was emitted against one method signature, but the implementing
method has an incompatible signature.  Having more precise type
information helps drastically lower this risk, as well as catching
a number of latent bugs.</p></div>

</div> <!-- family.semantics.result_type -->
</div> <!-- family.semantics -->
</div> <!-- family -->

<div id="optimization">
<h1>Optimization</h1>

<p>ARC applies aggressive rules for the optimization of local
behavior.  These rules are based around a core assumption of
<span class="term">local balancing</span>: that other code will
perform retains and releases as necessary (and only as necessary) for
its own safety, and so the optimizer does not need to consider global
properties of the retain and release sequence.  For example, if a
retain and release immediately bracket a call, the optimizer can
delete the retain and release on the assumption that the called
function will not do a constant number of unmotivated releases
followed by a constant number of <q>balancing</q> retains, such that
the local retain/release pair is the only thing preventing the called
function from ending up with a dangling reference.</p>

<p>The optimizer assumes that when a new value enters local control,
e.g. from a load of a non-local object or as the result of a function
call, it is instaneously valid.  Subsequently, a retain and release of
a value are necessary on a computation path only if there is a use of
that value before the release and after any operation which might
cause a release of the value (including indirectly or non-locally),
and only if the value is not demonstrably already retained.</p>

<p>The complete optimization rules are quite complicated, but it would
still be useful to document them here.</p>

<div id="optimization.precise">
<h1>Precise lifetime semantics</h1>

<p>In general, ARC maintains an invariant that a retainable object
pointer held in a <tt>__strong</tt> object will be retained for the
full formal lifetime of the object.  Objects subject to this invariant
have <span class="term">precise lifetime semantics</span>.</p>

<p>By default, local variables of automatic storage duration do not
have precise lifetime semantics.  Such objects are simply strong
references which hold values of retainable object pointer type, and
these values are still fully subject to the optimizations on values
under local control.</p>

<div class="rationale"><p>Rationale: applying these precise-lifetime
semantics strictly would be prohibitive.  Many useful optimizations
that might theoretically decrease the lifetime of an object would be
rendered impossible.  Essentially, it promises too much.</p></div>

<p>A local variable of retainable object owner type and automatic
storage duration may be annotated with the <tt>objc_precise_lifetime</tt>
attribute to indicate that it should be considered to be an object
with precise lifetime semantics.</p>

<div class="rationale"><p>Rationale: nonetheless, it is sometimes
useful to be able to force an object to be released at a precise time,
even if that object does not appear to be used.  This is likely to be
uncommon enough that the syntactic weight of explicitly requesting
these semantics will not be burdensome, and may even make the code
clearer.</p></div>

</div> <!-- optimization.precise -->

</div> <!-- optimization -->

<div id="misc">
<h1>Miscellaneous</h1>

<div id="misc.special_methods">
<h1>Special methods</h1>

<div id="misc.special_methods.retain">
<h1>Memory management methods</h1>

<p>A program is ill-formed if it contains a method definition, message
send, or <tt>@selector</tt> expression for any of the following
selectors:</p>
<ul>
<li><tt>autorelease</tt></li>
<li><tt>release</tt></li>
<li><tt>retain</tt></li>
<li><tt>retainCount</tt></li>
</ul>

<div class="rationale"><p>Rationale: <tt>retainCount</tt> is banned
because ARC robs it of consistent semantics.  The others were banned
after weighing three options for how to deal with message sends:</p>

<p><b>Honoring</b> them would work out very poorly if a programmer
naively or accidentally tried to incorporate code written for manual
retain/release code into an ARC program.  At best, such code would do
twice as much work as necessary; quite frequently, however, ARC and
the explicit code would both try to balance the same retain, leading
to crashes.  The cost is losing the ability to perform <q>unrooted</q>
retains, i.e. retains not logically corresponding to a strong
reference in the object graph.</p>

<p><b>Ignoring</b> them would badly violate user expectations about their
code.  While it <em>would</em> make it easier to develop code simultaneously
for ARC and non-ARC, there is very little reason to do so except for
certain library developers.  ARC and non-ARC translation units share
an execution model and can seamlessly interoperate.  Within a
translation unit, a developer who faithfully maintains their code in
non-ARC mode is suffering all the restrictions of ARC for zero
benefit, while a developer who isn't testing the non-ARC mode is
likely to be unpleasantly surprised if they try to go back to it.</p>

<p><b>Banning</b> them has the disadvantage of making it very awkward
to migrate existing code to ARC.  The best answer to that, given a
number of other changes and restrictions in ARC, is to provide a
specialized tool to assist users in that migration.</p>

<p>Implementing these methods was banned because they are too integral
to the semantics of ARC; many tricks which worked tolerably under
manual reference counting will misbehave if ARC performs an ephemeral
extra retain or two.  If absolutely required, it is still possible to
implement them in non-ARC code, for example in a category; the
implementations must obey the <a href="#objects.retains">semantics</a>
laid out elsewhere in this document.</p>

</div>
</div> <!-- misc.special_methods.retain -->

<div id="misc.special_methods.dealloc">
<h1><tt>dealloc</tt></h1>

<p>A program is ill-formed if it contains a message send
or <tt>@selector</tt> expression for the selector <tt>dealloc</tt>.</p>

<div class="rationale"><p>Rationale: there are no legitimate reasons
to call <tt>dealloc</tt> directly.</p></div>

<p>A class may provide a method definition for an instance method
named <tt>dealloc</tt>.  This method will be called after the final
<tt>release</tt> of the object but before it is deallocated or any of
its instance variables are destroyed.  The superclass's implementation
of <tt>dealloc</tt> will be called automatically when the method
returns.</p>

<div class="rationale"><p>Rationale: even though ARC destroys instance
variables automatically, there are still legitimate reasons to write
a <tt>dealloc</tt> method, such as freeing non-retainable resources.
Failing to call <tt>[super&nbsp;dealloc]</tt> in such a method is nearly
always a bug.  Sometimes, the object is simply trying to prevent
itself from being destroyed, but <tt>dealloc</tt> is really far too
late for the object to be raising such objections.  Somewhat more
legitimately, an object may have been pool-allocated and should not be
deallocated with <tt>free</tt>; for now, this can only be supported
with a <tt>dealloc</tt> implementation outside of ARC.  Such an
implementation must be very careful to do all the other work
that <tt>NSObject</tt>'s <tt>dealloc</tt> would, which is outside the
scope of this document to describe.</p></div>

</div>

</div> <!-- misc.special_methods -->

<div id="autoreleasepool">
<h1><tt>@autoreleasepool</tt></h1>

<p>To simplify the use of autorelease pools, and to bring them under
the control of the compiler, a new kind of statement is available in
Objective-C.  It is written <tt>@autoreleasepool</tt> followed by
a <i>compound-statement</i>, i.e. by a new scope delimited by curly
braces.  Upon entry to this block, the current state of the
autorelease pool is captured.  When the block is exited normally,
whether by fallthrough or directed control flow (such
as <tt>return</tt> or <tt>break</tt>), the autorelease pool is
restored to the saved state, releasing all the objects in it.  When
the block is exited with an exception, the pool is not drained.</p>

<p><tt>@autoreleasepool</tt> may be used in non-ARC translation units,
with equivalent semantics.</p>

<p>A program is ill-formed if it refers to the
<tt>NSAutoreleasePool</tt> class.</p>

<div class="rationale"><p>Rationale: autorelease pools are clearly
important for the compiler to reason about, but it is far too much to
expect the compiler to accurately reason about control dependencies
between two calls.  It is also very easy to accidentally forget to
drain an autorelease pool when using the manual API, and this can
significantly inflate the process's high-water-mark.  The introduction
of a new scope is unfortunate but basically required for sane
interaction with the rest of the language.  Not draining the pool
during an unwind is apparently required by the Objective-C exceptions
implementation.</p></div>

</div> <!-- autoreleasepool -->

<div id="misc.self">
<h1><tt>self</tt></h1>

<p>The <tt>self</tt> parameter variable of an Objective-C method is
never actually retained by the implementation.  It is undefined
behavior, or at least dangerous, to cause an object to be deallocated
during a message send to that object.</p>

<p>To make this safe, for Objective-C instance methods <tt>self</tt> is
implicitly <tt>const</tt> unless the method is in the <a
href="#family.semantics.init"><tt>init</tt> family</a>. Further, <tt>self</tt>
is <b>always</b> implicitly <tt>const</tt> within a class method.</p>

<div class="rationale"><p>Rationale: the cost of
retaining <tt>self</tt> in all methods was found to be prohibitive, as
it tends to be live across calls, preventing the optimizer from
proving that the retain and release are unnecessary &mdash; for good
reason, as it's quite possible in theory to cause an object to be
deallocated during its execution without this retain and release.
Since it's extremely uncommon to actually do so, even unintentionally,
and since there's no natural way for the programmer to remove this
retain/release pair otherwise (as there is for other parameters by,
say, making the variable <tt>__unsafe_unretained</tt>), we chose to
make this optimizing assumption and shift some amount of risk to the
user.</p></div>

</div> <!-- misc.self -->

<div id="misc.enumeration">
<h1>Fast enumeration iteration variables</h1>

<p>If a variable is declared in the condition of an Objective-C fast
enumeration loop, and the variable has no explicit ownership
qualifier, then it is qualified with <tt>const __strong</tt> and
objects encountered during the enumeration are not actually
retained.</p>

<div class="rationale"><p>Rationale: this is an optimization made
possible because fast enumeration loops promise to keep the objects
retained during enumeration, and the collection itself cannot be
synchronously modified.  It can be overridden by explicitly qualifying
the variable with <tt>__strong</tt>, which will make the variable
mutable again and cause the loop to retain the objects it
encounters.</p></div>

</div> <!-- misc.enumeration -->

<div id="misc.blocks">
<h1>Blocks</h1>

<p>The implicit <tt>const</tt> capture variables created when
evaluating a block literal expression have the same ownership
semantics as the local variables they capture.  The capture is
performed by reading from the captured variable and initializing the
capture variable with that value; the capture variable is destroyed
when the block literal is, i.e. at the end of the enclosing scope.</p>

<p>The <a href="#ownership.inference">inference</a> rules apply
equally to <tt>__block</tt> variables, which is a shift in semantics
from non-ARC, where <tt>__block</tt> variables did not implicitly
retain during capture.</p>

<p><tt>__block</tt> variables of retainable object owner type are
moved off the stack by initializing the heap copy with the result of
moving from the stack copy.</p>

<p>With the exception of retains done as part of initializing
a <tt>__strong</tt> parameter variable or reading a <tt>__weak</tt>
variable, whenever these semantics call for retaining a value of
block-pointer type, it has the effect of a <tt>Block_copy</tt>.  The
optimizer may remove such copies when it sees that the result is
used only as an argument to a call.</p>

</div> <!-- misc.blocks -->

<div id="misc.exceptions">
<h1>Exceptions</h1>

<p>By default in Objective C, ARC is not exception-safe for normal
releases:</p>
<ul>
<li>It does not end the lifetime of <tt>__strong</tt> variables when
their scopes are abnormally terminated by an exception.</li>
<li>It does not perform releases which would occur at the end of
a full-expression if that full-expression throws an exception.</li>
</ul>

<p>A program may be compiled with the option
<tt>-fobjc-arc-exceptions</tt> in order to enable these, or with the
option <tt>-fno-objc-arc-exceptions</tt> to explicitly disable them,
with the last such argument <q>winning</q>.</p>

<div class="rationale"><p>Rationale: the standard Cocoa convention is
that exceptions signal programmer error and are not intended to be
recovered from.  Making code exceptions-safe by default would impose
severe runtime and code size penalties on code that typically does not
actually care about exceptions safety.  Therefore, ARC-generated code
leaks by default on exceptions, which is just fine if the process is
going to be immediately terminated anyway.  Programs which do care
about recovering from exceptions should enable the option.</p></div>

<p>In Objective-C++, <tt>-fobjc-arc-exceptions</tt> is enabled by
default.</p>

<div class="rationale"><p>Rationale: C++ already introduces pervasive
exceptions-cleanup code of the sort that ARC introduces.  C++
programmers who have not already disabled exceptions are much more
likely to actual require exception-safety.</p></div>

<p>ARC does end the lifetimes of <tt>__weak</tt> objects when an
exception terminates their scope unless exceptions are disabled in the
compiler.</p>

<div class="rationale"><p>Rationale: the consequence of a
local <tt>__weak</tt> object not being destroyed is very likely to be
corruption of the Objective-C runtime, so we want to be safer here.
Of course, potentially massive leaks are about as likely to take down
the process as this corruption is if the program does try to recover
from exceptions.</p></div>

</div> <!-- misc.exceptions -->

<div id="misc.interior">
<h1>Interior pointers</h1>

<p>An Objective-C method returning a non-retainable pointer may be
annotated with the <tt>objc_returns_inner_pointer</tt> attribute to
indicate that it returns a handle to the internal data of an object,
and that this reference will be invalidated if the object is
destroyed.  When such a message is sent to an object, the object's
lifetime will be extended until at least the earliest of:</p>

<ul>
<li>the last use of the returned pointer, or any pointer derived from
it, in the calling function or</li>
<li>the autorelease pool is restored to a previous state.</li>
</ul>

<div class="rationale"><p>Rationale: not all memory and resources are
managed with reference counts; it is common for objects to manage
private resources in their own, private way.  Typically these
resources are completely encapsulated within the object, but some
classes offer their users direct access for efficiency.  If ARC is not
aware of methods that return such <q>interior</q> pointers, its
optimizations can cause the owning object to be reclaimed too soon.
This attribute informs ARC that it must tread lightly.</p>

<p>The extension rules are somewhat intentionally vague.  The
autorelease pool limit is there to permit a simple implementation to
simply retain and autorelease the receiver.  The other limit permits
some amount of optimization.  The phrase <q>derived from</q> is
intended to encompass the results both of pointer transformations,
such as casts and arithmetic, and of loading from such derived
pointers; furthermore, it applies whether or not such derivations are
applied directly in the calling code or by other utility code (for
example, the C library routine <tt>strchr</tt>).  However, the
implementation never need account for uses after a return from the
code which calls the method returning an interior pointer.</p></div>

<p>As an exception, no extension is required if the receiver is loaded
directly from a <tt>__strong</tt> object
with <a href="#optimization.precise">precise lifetime semantics</a>.</p>

<div class="rationale"><p>Rationale: implicit autoreleases carry the
risk of significantly inflating memory use, so it's important to
provide users a way of avoiding these autoreleases.  Tying this to
precise lifetime semantics is ideal, as for local variables this
requires a very explicit annotation, which allows ARC to trust the
user with good cheer.</p></div>

</div> <!-- misc.interior -->

<div id="misc.c-retainable">
<h1>C retainable pointer types</h1>

<p>A type is a <span class="term">C retainable pointer type</span>
if it is a pointer to (possibly qualified) <tt>void</tt> or a
pointer to a (possibly qualifier) <tt>struct</tt> or <tt>class</tt>
type.</p>

<div class="rationale"><p>Rationale: ARC does not manage pointers of
CoreFoundation type (or any of the related families of retainable C
pointers which interoperate with Objective-C for retain/release
operation).  In fact, ARC does not even know how to distinguish these
types from arbitrary C pointer types.  The intent of this concept is
to filter out some obviously non-object types while leaving a hook for
later tightening if a means of exhaustively marking CF types is made
available.</p></div>

<div id="misc.c-retainable.audit">
<h1>Auditing of C retainable pointer interfaces</h1>

<p><span class="revision"><span class="whenRevised">[beginning Apple 4.0, LLVM 3.1]</span></span></p>

<p>A C function may be marked with the <tt>cf_audited_transfer</tt>
attribute to express that, except as otherwise marked with attributes,
it obeys the parameter (consuming vs. non-consuming) and return
(retained vs. non-retained) conventions for a C function of its name,
namely:</p>

<ul>
<li>A parameter of C retainable pointer type is assumed to not be
consumed unless it is marked with the <tt>cf_consumed</tt> attribute, and</li>
<li>A result of C retainable pointer type is assumed to not be
returned retained unless the function is either
marked <tt>cf_returns_retained</tt> or it follows
the create/copy naming convention and is not
marked <tt>cf_returns_not_retained</tt>.</li>
</ul>

<p>A function obeys the <span class="term">create/copy</span> naming
convention if its name contains as a substring:</p>
<ul>
<li>either <q>Create</q> or <q>Copy</q> not followed by a lowercase letter, or</li>
<li>either <q>create</q> or <q>copy</q> not followed by a lowercase
letter and not preceded by any letter, whether uppercase or lowercase.</li>
</ul>

<p>A second attribute, <tt>cf_unknown_transfer</tt>, signifies that a
function's transfer semantics cannot be accurately captured using any
of these annotations.  A program is ill-formed if it annotates the
same function with both <tt>cf_audited_transfer</tt>
and <tt>cf_unknown_transfer</tt>.</p>

<p>A pragma is provided to faciliate the mass annotation of interfaces:</p>

<pre>#pragma arc_cf_code_audited begin
...
#pragma arc_cf_code_audited end</pre>

<p>All C functions declared within the extent of this pragma are
treated as if annotated with the <tt>cf_audited_transfer</tt>
attribute unless they otherwise have the <tt>cf_unknown_transfer</tt>
attribute.  The pragma is accepted in all language modes.  A program
is ill-formed if it attempts to change files, whether by including a
file or ending the current file, within the extent of this pragma.</p>

<p>It is possible to test for all the features in this section with
<tt>__has_feature(arc_cf_code_audited)</tt>.</p>

<div class="rationale"><p>Rationale: A significant inconvenience in
ARC programming is the necessity of interacting with APIs based around
C retainable pointers.  These features are designed to make it
relatively easy for API authors to quickly review and annotate their
interfaces, in turn improving the fidelity of tools such as the static
analyzer and ARC.  The single-file restriction on the pragma is
designed to eliminate the risk of accidentally annotating some other
header's interfaces.</p></div>

</div> <!-- misc.c-retainable.audit -->

</div> <!-- misc.c-retainable -->

</div> <!-- misc -->

<div id="runtime">
<h1>Runtime support</h1>

<p>This section describes the interaction between the ARC runtime and
the code generated by the ARC compiler.  This is not part of the ARC
language specification; instead, it is effectively a language-specific
ABI supplement, akin to the <q>Itanium</q> generic ABI for C++.</p>

<p>Ownership qualification does not alter the storage requirements for
objects, except that it is undefined behavior if a <tt>__weak</tt>
object is inadequately aligned for an object of type <tt>id</tt>.  The
other qualifiers may be used on explicitly under-aligned memory.</p>

<p>The runtime tracks <tt>__weak</tt> objects which holds non-null
values.  It is undefined behavior to direct modify a <tt>__weak</tt>
object which is being tracked by the runtime except through an
<a href="#runtime.objc_storeWeak"><tt>objc_storeWeak</tt></a>,
<a href="#runtime.objc_destroyWeak"><tt>objc_destroyWeak</tt></a>,
or <a href="#runtime.objc_moveWeak"><tt>objc_moveWeak</tt></a>
call.</p>

<p>The runtime must provide a number of new entrypoints which the
compiler may emit, which are described in the remainder of this
section.</p>

<div class="rationale"><p>Rationale: Several of these functions are
semantically equivalent to a message send; we emit calls to C
functions instead because:</p>
<ul>
<li>the machine code to do so is significantly smaller,</li>
<li>it is much easier to recognize the C functions in the ARC optimizer, and</li>
<li>a sufficient sophisticated runtime may be able to avoid the
message send in common cases.</li>
</ul>

<p>Several other of these functions are <q>fused</q> operations which
can be described entirely in terms of other operations.  We use the
fused operations primarily as a code-size optimization, although in
some cases there is also a real potential for avoiding redundant
operations in the runtime.</p>

</div>

<div id="runtime.objc_autorelease">
<h1><tt>id objc_autorelease(id value);</tt></h1>
<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
valid object.</p>
<p>If <tt>value</tt> is null, this call has no effect.  Otherwise, it
adds the object to the innermost autorelease pool exactly as if the
object had been sent the <tt>autorelease</tt> message.</p>
<p>Always returns <tt>value</tt>.</p>
</div> <!-- runtime.objc_autorelease -->

<div id="runtime.objc_autoreleasePoolPop">
<h1><tt>void objc_autoreleasePoolPop(void *pool);</tt></h1>
<p><i>Precondition:</i> <tt>pool</tt> is the result of a previous call to
<a href="runtime.objc_autoreleasePoolPush"><tt>objc_autoreleasePoolPush</tt></a>
on the current thread, where neither <tt>pool</tt> nor any enclosing
pool have previously been popped.</p>
<p>Releases all the objects added to the given autorelease pool and
any autorelease pools it encloses, then sets the current autorelease
pool to the pool directly enclosing <tt>pool</tt>.</p>
</div> <!-- runtime.objc_autoreleasePoolPop -->

<div id="runtime.objc_autoreleasePoolPush">
<h1><tt>void *objc_autoreleasePoolPush(void);</tt></h1>
<p>Creates a new autorelease pool that is enclosed by the current
pool, makes that the current pool, and returns an opaque <q>handle</q>
to it.</p>

<div class="rationale"><p>Rationale: while the interface is described
as an explicit hierarchy of pools, the rules allow the implementation
to just keep a stack of objects, using the stack depth as the opaque
pool handle.</p></div>

</div> <!-- runtime.objc_autoreleasePoolPush -->

<div id="runtime.objc_autoreleaseReturnValue">
<h1><tt>id objc_autoreleaseReturnValue(id value);</tt></h1>
<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
valid object.</p>
<p>If <tt>value</tt> is null, this call has no effect.  Otherwise, it
makes a best effort to hand off ownership of a retain count on the
object to a call
to <a href="runtime.objc_retainAutoreleasedReturnValue"><tt>objc_retainAutoreleasedReturnValue</tt></a>
for the same object in an enclosing call frame.  If this is not
possible, the object is autoreleased as above.</p>
<p>Always returns <tt>value</tt>.</p>
</div> <!-- runtime.objc_autoreleaseReturnValue -->

<div id="runtime.objc_copyWeak">
<h1><tt>void objc_copyWeak(id *dest, id *src);</tt></h1>
<p><i>Precondition:</i> <tt>src</tt> is a valid pointer which either
contains a null pointer or has been registered as a <tt>__weak</tt>
object.  <tt>dest</tt> is a valid pointer which has not been
registered as a <tt>__weak</tt> object.</p>
<p><tt>dest</tt> is initialized to be equivalent to <tt>src</tt>,
potentially registering it with the runtime.  Equivalent to the
following code:</p>
<pre>void objc_copyWeak(id *dest, id *src) {
  objc_release(objc_initWeak(dest, objc_loadWeakRetained(src)));
}</pre>
<p>Must be atomic with respect to calls to <tt>objc_storeWeak</tt>
on <tt>src</tt>.</p>
</div> <!-- runtime.objc_copyWeak -->

<div id="runtime.objc_destroyWeak">
<h1><tt>void objc_destroyWeak(id *object);</tt></h1>
<p><i>Precondition:</i> <tt>object</tt> is a valid pointer which
either contains a null pointer or has been registered as
a <tt>__weak</tt> object.</p>
<p><tt>object</tt> is unregistered as a weak object, if it ever was.
The current value of <tt>object</tt> is left unspecified; otherwise,
equivalent to the following code:</p>
<pre>void objc_destroyWeak(id *object) {
  objc_storeWeak(object, nil);
}</pre>
<p>Does not need to be atomic with respect to calls
to <tt>objc_storeWeak</tt> on <tt>object</tt>.</p>
</div> <!-- runtime.objc_destroyWeak -->

<div id="runtime.objc_initWeak">
<h1><tt>id objc_initWeak(id *object, id value);</tt></h1>
<p><i>Precondition:</i> <tt>object</tt> is a valid pointer which has
not been registered as a <tt>__weak</tt> object.  <tt>value</tt> is
null or a pointer to a valid object.</p>
<p>If <tt>value</tt> is a null pointer or the object to which it
points has begun deallocation, <tt>object</tt> is zero-initialized.
Otherwise, <tt>object</tt> is registered as a <tt>__weak</tt> object
pointing to <tt>value</tt>.  Equivalent to the following code:</p>
<pre>id objc_initWeak(id *object, id value) {
  *object = nil;
  return objc_storeWeak(object, value);
}</pre>
<p>Returns the value of <tt>object</tt> after the call.</p>
<p>Does not need to be atomic with respect to calls
to <tt>objc_storeWeak</tt> on <tt>object</tt>.</p>
</div> <!-- runtime.objc_initWeak -->

<div id="runtime.objc_loadWeak">
<h1><tt>id objc_loadWeak(id *object);</tt></h1>
<p><i>Precondition:</i> <tt>object</tt> is a valid pointer which
either contains a null pointer or has been registered as
a <tt>__weak</tt> object.</p>
<p>If <tt>object</tt> is registered as a <tt>__weak</tt> object, and
the last value stored into <tt>object</tt> has not yet been
deallocated or begun deallocation, retains and autoreleases that value
and returns it.  Otherwise returns null.  Equivalent to the following
code:</p>
<pre>id objc_loadWeak(id *object) {
  return objc_autorelease(objc_loadWeakRetained(object));
}</pre>
<p>Must be atomic with respect to calls to <tt>objc_storeWeak</tt>
on <tt>object</tt>.</p>
<div class="rationale">Rationale: loading weak references would be
inherently prone to race conditions without the retain.</div>
</div> <!-- runtime.objc_loadWeak -->

<div id="runtime.objc_loadWeakRetained">
<h1><tt>id objc_loadWeakRetained(id *object);</tt></h1>
<p><i>Precondition:</i> <tt>object</tt> is a valid pointer which
either contains a null pointer or has been registered as
a <tt>__weak</tt> object.</p>
<p>If <tt>object</tt> is registered as a <tt>__weak</tt> object, and
the last value stored into <tt>object</tt> has not yet been
deallocated or begun deallocation, retains that value and returns it.
Otherwise returns null.</p>
<p>Must be atomic with respect to calls to <tt>objc_storeWeak</tt>
on <tt>object</tt>.</p>
</div> <!-- runtime.objc_loadWeakRetained -->

<div id="runtime.objc_moveWeak">
<h1><tt>void objc_moveWeak(id *dest, id *src);</tt></h1>
<p><i>Precondition:</i> <tt>src</tt> is a valid pointer which either
contains a null pointer or has been registered as a <tt>__weak</tt>
object.  <tt>dest</tt> is a valid pointer which has not been
registered as a <tt>__weak</tt> object.</p>
<p><tt>dest</tt> is initialized to be equivalent to <tt>src</tt>,
potentially registering it with the runtime.  <tt>src</tt> may then be
left in its original state, in which case this call is equivalent
to <a href="#runtime.objc_copyWeak"><tt>objc_copyWeak</tt></a>, or it
may be left as null.</p>
<p>Must be atomic with respect to calls to <tt>objc_storeWeak</tt>
on <tt>src</tt>.</p>
</div> <!-- runtime.objc_moveWeak -->

<div id="runtime.objc_release">
<h1><tt>void objc_release(id value);</tt></h1>
<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
valid object.</p>
<p>If <tt>value</tt> is null, this call has no effect.  Otherwise, it
performs a release operation exactly as if the object had been sent
the <tt>release</tt> message.</p>
</div> <!-- runtime.objc_release -->

<div id="runtime.objc_retain">
<h1><tt>id objc_retain(id value);</tt></h1>
<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
valid object.</p>
<p>If <tt>value</tt> is null, this call has no effect.  Otherwise, it
performs a retain operation exactly as if the object had been sent
the <tt>retain</tt> message.</p>
<p>Always returns <tt>value</tt>.</p>
</div> <!-- runtime.objc_retain -->

<div id="runtime.objc_retainAutorelease">
<h1><tt>id objc_retainAutorelease(id value);</tt></h1>
<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
valid object.</p>
<p>If <tt>value</tt> is null, this call has no effect.  Otherwise, it
performs a retain operation followed by an autorelease operation.
Equivalent to the following code:</p>
<pre>id objc_retainAutorelease(id value) {
  return objc_autorelease(objc_retain(value));
}</pre>
<p>Always returns <tt>value</tt>.</p>
</div> <!-- runtime.objc_retainAutorelease -->

<div id="runtime.objc_retainAutoreleaseReturnValue">
<h1><tt>id objc_retainAutoreleaseReturnValue(id value);</tt></h1>
<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
valid object.</p>
<p>If <tt>value</tt> is null, this call has no effect.  Otherwise, it
performs a retain operation followed by the operation described in
<a href="#runtime.objc_autoreleaseReturnValue"><tt>objc_autoreleaseReturnValue</tt></a>.
Equivalent to the following code:</p>
<pre>id objc_retainAutoreleaseReturnValue(id value) {
  return objc_autoreleaseReturnValue(objc_retain(value));
}</pre>
<p>Always returns <tt>value</tt>.</p>
</div> <!-- runtime.objc_retainAutoreleaseReturnValue -->

<div id="runtime.objc_retainAutoreleasedReturnValue">
<h1><tt>id objc_retainAutoreleasedReturnValue(id value);</tt></h1>
<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
valid object.</p>
<p>If <tt>value</tt> is null, this call has no effect.  Otherwise, it
attempts to accept a hand off of a retain count from a call to
<a href="#runtime.objc_autoreleaseReturnValue"><tt>objc_autoreleaseReturnValue</tt></a>
on <tt>value</tt> in a recently-called function or something it
calls.  If that fails, it performs a retain operation exactly
like <a href="#runtime.objc_retain"><tt>objc_retain</tt></a>.</p>
<p>Always returns <tt>value</tt>.</p>
</div> <!-- runtime.objc_retainAutoreleasedReturnValue -->

<div id="runtime.objc_retainBlock">
<h1><tt>id objc_retainBlock(id value);</tt></h1>
<p><i>Precondition:</i> <tt>value</tt> is null or a pointer to a
valid block object.</p>
<p>If <tt>value</tt> is null, this call has no effect.  Otherwise, if
the block pointed to by <tt>value</tt> is still on the stack, it is
copied to the heap and the address of the copy is returned.  Otherwise
a retain operation is performed on the block exactly as if it had been
sent the <tt>retain</tt> message.</p>
</div> <!-- runtime.objc_retainBlock -->

<div id="runtime.objc_storeStrong">
<h1><tt>id objc_storeStrong(id *object, id value);</tt></h1>
<p><i>Precondition:</i> <tt>object</tt> is a valid pointer to
a <tt>__strong</tt> object which is adequately aligned for a
pointer.  <tt>value</tt> is null or a pointer to a valid object.</p>
<p>Performs the complete sequence for assigning to a <tt>__strong</tt>
object of non-block type.  Equivalent to the following code:</p>
<pre>id objc_storeStrong(id *object, id value) {
  value = [value retain];
  id oldValue = *object;
  *object = value;
  [oldValue release];
  return value;
}</pre>
<p>Always returns <tt>value</tt>.</p>
</div> <!-- runtime.objc_storeStrong -->

<div id="runtime.objc_storeWeak">
<h1><tt>id objc_storeWeak(id *object, id value);</tt></h1>
<p><i>Precondition:</i> <tt>object</tt> is a valid pointer which
either contains a null pointer or has been registered as
a <tt>__weak</tt> object.  <tt>value</tt> is null or a pointer to a
valid object.</p>
<p>If <tt>value</tt> is a null pointer or the object to which it
points has begun deallocation, <tt>object</tt> is assigned null
and unregistered as a <tt>__weak</tt> object.  Otherwise,
<tt>object</tt> is registered as a <tt>__weak</tt> object or has its
registration updated to point to <tt>value</tt>.</p>
<p>Returns the value of <tt>object</tt> after the call.</p>
</div> <!-- runtime.objc_storeWeak -->

</div> <!-- runtime -->
</div> <!-- root -->
</body>
</html>
generated by cgit v1.2.3 (git 2.46.2) at 2024-11-10 17:04:34 +0000