/usr/share/doc/clang-3.8-doc/html/AutomaticReferenceCounting.html is in clang-3.8-doc 1:3.8.1-24.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Objective-C Automatic Reference Counting (ARC) — Clang 3.8 documentation</title>
<link rel="stylesheet" href="_static/haiku.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '3.8',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="top" title="Clang 3.8 documentation" href="index.html" />
<link rel="up" title="Clang Language Extensions" href="LanguageExtensions.html" />
<link rel="next" title="Attributes in Clang" href="AttributeReference.html" />
<link rel="prev" title="Block Implementation Specification" href="Block-ABI-Apple.html" />
</head>
<body role="document">
<div class="header" role="banner"><h1 class="heading"><a href="index.html">
<span>Clang 3.8 documentation</span></a></h1>
<h2 class="heading"><span>Objective-C Automatic Reference Counting (ARC)</span></h2>
</div>
<div class="topnav" role="navigation" aria-label="top navigation">
<p>
«  <a href="Block-ABI-Apple.html">Block Implementation Specification</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="AttributeReference.html">Attributes in Clang</a>  »
</p>
</div>
<div class="content">
<style>
.arc-term { font-style: italic; font-weight: bold; }
.revision { font-style: italic; }
.when-revised { font-weight: bold; font-style: normal; }
/*
* Automatic numbering is described in this article:
* http://dev.opera.com/articles/view/automatic-numbering-with-css-counters/
*/
/*
* Automatic numbering for the TOC.
* This is wrong from the semantics point of view, since it is an ordered
* list, but uses "ul" tag.
*/
div#contents.contents.local ul {
counter-reset: toc-section;
list-style-type: none;
}
div#contents.contents.local ul li {
counter-increment: toc-section;
background: none; // Remove bullets
}
div#contents.contents.local ul li a.reference:before {
content: counters(toc-section, ".") " ";
}
/* Automatic numbering for the body. */
body {
counter-reset: section subsection subsubsection;
}
.section h2 {
counter-reset: subsection subsubsection;
counter-increment: section;
}
.section h2 a.toc-backref:before {
content: counter(section) " ";
}
.section h3 {
counter-reset: subsubsection;
counter-increment: subsection;
}
.section h3 a.toc-backref:before {
content: counter(section) "." counter(subsection) " ";
}
.section h4 {
counter-increment: subsubsection;
}
.section h4 a.toc-backref:before {
content: counter(section) "." counter(subsection) "." counter(subsubsection) " ";
}
</style><div class="section" id="objective-c-automatic-reference-counting-arc">
<h1>Objective-C Automatic Reference Counting (ARC)<a class="headerlink" href="#objective-c-automatic-reference-counting-arc" title="Permalink to this headline">¶</a></h1>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><a class="reference internal" href="#about-this-document" id="id4">About this document</a><ul>
<li><a class="reference internal" href="#purpose" id="id5">Purpose</a></li>
<li><a class="reference internal" href="#background" id="id6">Background</a></li>
<li><a class="reference internal" href="#evolution" id="id7">Evolution</a></li>
</ul>
</li>
<li><a class="reference internal" href="#general" id="id8">General</a></li>
<li><a class="reference internal" href="#retainable-object-pointers" id="id9">Retainable object pointers</a><ul>
<li><a class="reference internal" href="#retain-count-semantics" id="id10">Retain count semantics</a></li>
<li><a class="reference internal" href="#retainable-object-pointers-as-operands-and-arguments" id="id11">Retainable object pointers as operands and arguments</a><ul>
<li><a class="reference internal" href="#consumed-parameters" id="id12">Consumed parameters</a></li>
<li><a class="reference internal" href="#retained-return-values" id="id13">Retained return values</a></li>
<li><a class="reference internal" href="#unretained-return-values" id="id14">Unretained return values</a></li>
<li><a class="reference internal" href="#bridged-casts" id="id15">Bridged casts</a></li>
</ul>
</li>
<li><a class="reference internal" href="#restrictions" id="id16">Restrictions</a><ul>
<li><a class="reference internal" href="#conversion-of-retainable-object-pointers" id="id17">Conversion of retainable object pointers</a></li>
<li><a class="reference internal" href="#conversion-to-retainable-object-pointer-type-of-expressions-with-known-semantics" id="id18">Conversion to retainable object pointer type of expressions with known semantics</a></li>
<li><a class="reference internal" href="#conversion-from-retainable-object-pointer-type-in-certain-contexts" id="id19">Conversion from retainable object pointer type in certain contexts</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#ownership-qualification" id="id20">Ownership qualification</a><ul>
<li><a class="reference internal" href="#spelling" id="id21">Spelling</a><ul>
<li><a class="reference internal" href="#property-declarations" id="id22">Property declarations</a></li>
</ul>
</li>
<li><a class="reference internal" href="#semantics" id="id23">Semantics</a></li>
<li><a class="reference internal" href="#arc-ownership-restrictions" id="id24">Restrictions</a><ul>
<li><a class="reference internal" href="#weak-unavailable-types" id="id25">Weak-unavailable types</a></li>
<li><a class="reference internal" href="#storage-duration-of-autoreleasing-objects" id="id26">Storage duration of <code class="docutils literal"><span class="pre">__autoreleasing</span></code> objects</a></li>
<li><a class="reference internal" href="#conversion-of-pointers-to-ownership-qualified-types" id="id27">Conversion of pointers to ownership-qualified types</a></li>
<li><a class="reference internal" href="#passing-to-an-out-parameter-by-writeback" id="id28">Passing to an out parameter by writeback</a></li>
<li><a class="reference internal" href="#ownership-qualified-fields-of-structs-and-unions" id="id29">Ownership-qualified fields of structs and unions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#ownership-inference" id="id30">Ownership inference</a><ul>
<li><a class="reference internal" href="#objects" id="id31">Objects</a></li>
<li><a class="reference internal" href="#indirect-parameters" id="id32">Indirect parameters</a></li>
<li><a class="reference internal" href="#template-arguments" id="id33">Template arguments</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#method-families" id="id34">Method families</a><ul>
<li><a class="reference internal" href="#explicit-method-family-control" id="id35">Explicit method family control</a></li>
<li><a class="reference internal" href="#semantics-of-method-families" id="id36">Semantics of method families</a><ul>
<li><a class="reference internal" href="#semantics-of-init" id="id37">Semantics of <code class="docutils literal"><span class="pre">init</span></code></a></li>
<li><a class="reference internal" href="#related-result-types" id="id38">Related result types</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#optimization" id="id39">Optimization</a><ul>
<li><a class="reference internal" href="#object-liveness" id="id40">Object liveness</a></li>
<li><a class="reference internal" href="#no-object-lifetime-extension" id="id41">No object lifetime extension</a></li>
<li><a class="reference internal" href="#precise-lifetime-semantics" id="id42">Precise lifetime semantics</a></li>
</ul>
</li>
<li><a class="reference internal" href="#miscellaneous" id="id43">Miscellaneous</a><ul>
<li><a class="reference internal" href="#special-methods" id="id44">Special methods</a><ul>
<li><a class="reference internal" href="#memory-management-methods" id="id45">Memory management methods</a></li>
<li><a class="reference internal" href="#dealloc" id="id46"><code class="docutils literal"><span class="pre">dealloc</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#autoreleasepool" id="id47"><code class="docutils literal"><span class="pre">@autoreleasepool</span></code></a></li>
<li><a class="reference internal" href="#self" id="id48"><code class="docutils literal"><span class="pre">self</span></code></a></li>
<li><a class="reference internal" href="#fast-enumeration-iteration-variables" id="id49">Fast enumeration iteration variables</a></li>
<li><a class="reference internal" href="#blocks" id="id50">Blocks</a></li>
<li><a class="reference internal" href="#exceptions" id="id51">Exceptions</a></li>
<li><a class="reference internal" href="#interior-pointers" id="id52">Interior pointers</a></li>
<li><a class="reference internal" href="#c-retainable-pointer-types" id="id53">C retainable pointer types</a><ul>
<li><a class="reference internal" href="#auditing-of-c-retainable-pointer-interfaces" id="id54">Auditing of C retainable pointer interfaces</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#runtime-support" id="id55">Runtime support</a><ul>
<li><a class="reference internal" href="#arc-runtime-objc-autorelease" id="id56"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_autorelease(id</span> <span class="pre">value);</span></code></a></li>
<li><a class="reference internal" href="#void-objc-autoreleasepoolpop-void-pool" id="id57"><code class="docutils literal"><span class="pre">void</span> <span class="pre">objc_autoreleasePoolPop(void</span> <span class="pre">*pool);</span></code></a></li>
<li><a class="reference internal" href="#void-objc-autoreleasepoolpush-void" id="id58"><code class="docutils literal"><span class="pre">void</span> <span class="pre">*objc_autoreleasePoolPush(void);</span></code></a></li>
<li><a class="reference internal" href="#arc-runtime-objc-autoreleasereturnvalue" id="id59"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_autoreleaseReturnValue(id</span> <span class="pre">value);</span></code></a></li>
<li><a class="reference internal" href="#void-objc-copyweak-id-dest-id-src" id="id60"><code class="docutils literal"><span class="pre">void</span> <span class="pre">objc_copyWeak(id</span> <span class="pre">*dest,</span> <span class="pre">id</span> <span class="pre">*src);</span></code></a></li>
<li><a class="reference internal" href="#void-objc-destroyweak-id-object" id="id61"><code class="docutils literal"><span class="pre">void</span> <span class="pre">objc_destroyWeak(id</span> <span class="pre">*object);</span></code></a></li>
<li><a class="reference internal" href="#arc-runtime-objc-initweak" id="id62"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_initWeak(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></code></a></li>
<li><a class="reference internal" href="#arc-runtime-objc-loadweak" id="id63"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_loadWeak(id</span> <span class="pre">*object);</span></code></a></li>
<li><a class="reference internal" href="#arc-runtime-objc-loadweakretained" id="id64"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_loadWeakRetained(id</span> <span class="pre">*object);</span></code></a></li>
<li><a class="reference internal" href="#void-objc-moveweak-id-dest-id-src" id="id65"><code class="docutils literal"><span class="pre">void</span> <span class="pre">objc_moveWeak(id</span> <span class="pre">*dest,</span> <span class="pre">id</span> <span class="pre">*src);</span></code></a></li>
<li><a class="reference internal" href="#void-objc-release-id-value" id="id66"><code class="docutils literal"><span class="pre">void</span> <span class="pre">objc_release(id</span> <span class="pre">value);</span></code></a></li>
<li><a class="reference internal" href="#arc-runtime-objc-retain" id="id67"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retain(id</span> <span class="pre">value);</span></code></a></li>
<li><a class="reference internal" href="#arc-runtime-objc-retainautorelease" id="id68"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutorelease(id</span> <span class="pre">value);</span></code></a></li>
<li><a class="reference internal" href="#arc-runtime-objc-retainautoreleasereturnvalue" id="id69"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutoreleaseReturnValue(id</span> <span class="pre">value);</span></code></a></li>
<li><a class="reference internal" href="#arc-runtime-objc-retainautoreleasedreturnvalue" id="id70"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutoreleasedReturnValue(id</span> <span class="pre">value);</span></code></a></li>
<li><a class="reference internal" href="#arc-runtime-objc-retainblock" id="id71"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainBlock(id</span> <span class="pre">value);</span></code></a></li>
<li><a class="reference internal" href="#arc-runtime-objc-storestrong" id="id72"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_storeStrong(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></code></a></li>
<li><a class="reference internal" href="#arc-runtime-objc-storeweak" id="id73"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_storeWeak(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></code></a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="about-this-document">
<span id="arc-meta"></span><h2><a class="toc-backref" href="#id4">About this document</a><a class="headerlink" href="#about-this-document" title="Permalink to this headline">¶</a></h2>
<div class="section" id="purpose">
<span id="arc-meta-purpose"></span><h3><a class="toc-backref" href="#id5">Purpose</a><a class="headerlink" href="#purpose" title="Permalink to this headline">¶</a></h3>
<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>
<div class="section" id="background">
<span id="arc-meta-background"></span><h3><a class="toc-backref" href="#id6">Background</a><a class="headerlink" href="#background" title="Permalink to this headline">¶</a></h3>
<p>This document assumes a basic familiarity with C.</p>
<p><span class="arc-term">Blocks</span> are a C language extension for creating anonymous functions.
Users interact with and transfer block objects using <span class="arc-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 <code class="docutils literal"><span class="pre">Block_copy</span></code> 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
<code class="docutils literal"><span class="pre">Block_release</span></code>, 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="arc-term">object
pointer types</span>. This kind has two notable builtin members, <code class="docutils literal"><span class="pre">id</span></code> and
<code class="docutils literal"><span class="pre">Class</span></code>; <code class="docutils literal"><span class="pre">id</span></code> 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="arc-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="arc-term">ivars</span>, fields which appear on all instances of that class. For
every class <em>T</em> there’s an associated metaclass; it has no fields, its
superclass is the metaclass of <em>T</em>‘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
<code class="docutils literal"><span class="pre">Class</span></code>.</p>
<p>A class declaration (<code class="docutils literal"><span class="pre">@interface</span></code>) declares a set of <span class="arc-term">methods</span>. A
method has a return type, a list of argument types, and a <span class="arc-term">selector</span>:
a name like <code class="docutils literal"><span class="pre">foo:bar:baz:</span></code>, 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="arc-term">receiver</span>) and a list of formal
arguments interspersed with the selector, like so:</p>
<div class="highlight-objc"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">receiver</span> <span class="nl">foo</span><span class="p">:</span> <span class="n">fooArg</span> <span class="nl">bar</span><span class="p">:</span> <span class="n">barArg</span> <span class="nl">baz</span><span class="p">:</span> <span class="n">bazArg</span><span class="p">]</span>
</pre></div>
</div>
<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 “expression” 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 <code class="docutils literal"><span class="pre">super</span></code>, 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 <code class="docutils literal"><span class="pre">@interface</span></code>, but
those defined in a separate <code class="docutils literal"><span class="pre">@implementation</span></code> declaration; however, when
compiling a call, typechecking is done based on the methods declared in the
<code class="docutils literal"><span class="pre">@interface</span></code>.</p>
<p>Method declarations may also be grouped into <span class="arc-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="arc-term">Class extensions</span> are collections of ivars and methods, designed to
allow a class’s <code class="docutils literal"><span class="pre">@interface</span></code> to be split across multiple files; however,
there is still a primary implementation file which must see the
<code class="docutils literal"><span class="pre">@interface</span></code>s of all class extensions. <span class="arc-term">Categories</span> allow
methods (but not ivars) to be declared <em>post hoc</em> on an arbitrary class; the
methods in the category’s <code class="docutils literal"><span class="pre">@implementation</span></code> 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: <code class="docutils literal"><span class="pre">retain</span></code>
increases the object’s reference count by 1, whereas <code class="docutils literal"><span class="pre">release</span></code> decreases it
by 1 and calls the instance method <code class="docutils literal"><span class="pre">dealloc</span></code> if the count reaches 0. To
simplify certain operations, there is also an <span class="arc-term">autorelease pool</span>, a
thread-local list of objects to call <code class="docutils literal"><span class="pre">release</span></code> on later; an object can be
added to this pool by calling <code class="docutils literal"><span class="pre">autorelease</span></code> on it.</p>
<p>Block pointers may be converted to type <code class="docutils literal"><span class="pre">id</span></code>; 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 <code class="docutils literal"><span class="pre">retain</span></code> by adjusting the reference count, not by calling
<code class="docutils literal"><span class="pre">Block_copy</span></code>.</p>
</div>
<div class="section" id="evolution">
<span id="arc-meta-evolution"></span><h3><a class="toc-backref" href="#id7">Evolution</a><a class="headerlink" href="#evolution" title="Permalink to this headline">¶</a></h3>
<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>
<div>ARC applies to Objective-C pointer types, block pointer types, and
<span class="when-revised">[beginning Apple 8.0, LLVM 3.8]</span> <span class="revision">BPTRs declared
within</span> <code class="docutils literal"><span class="pre">extern</span> <span class="pre">"BCPL"</span></code> blocks.</div></blockquote>
<p>For now, it is sensible to version this document by the releases of its sole
implementation (and its host project), clang. “LLVM X.Y” refers to an
open-source release of clang from the LLVM project. “Apple X.Y” 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>
</div>
<div class="section" id="general">
<span id="arc-general"></span><h2><a class="toc-backref" href="#id8">General</a><a class="headerlink" href="#general" title="Permalink to this headline">¶</a></h2>
<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 <code class="docutils literal"><span class="pre">-fobjc-arc</span></code>. It may
also be explicitly disabled with the compiler flag <code class="docutils literal"><span class="pre">-fno-objc-arc</span></code>. The last
of these two flags appearing on the compile line “wins”.</p>
<p>If ARC is enabled, <code class="docutils literal"><span class="pre">__has_feature(objc_arc)</span></code> will expand to 1 in the
preprocessor. For more information about <code class="docutils literal"><span class="pre">__has_feature</span></code>, see the
<a class="reference internal" href="LanguageExtensions.html#langext-has-feature-has-extension"><span class="std std-ref">language extensions</span></a> document.</p>
</div>
<div class="section" id="retainable-object-pointers">
<span id="arc-objects"></span><h2><a class="toc-backref" href="#id9">Retainable object pointers</a><a class="headerlink" href="#retainable-object-pointers" title="Permalink to this headline">¶</a></h2>
<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="arc-term">retainable object pointer</span> (or “retainable pointer”) is a value of
a <span class="arc-term">retainable object pointer type</span> (“retainable type”). There are
three kinds of retainable object pointer types:</p>
<ul class="simple">
<li>block pointers (formed by applying the caret (<code class="docutils literal"><span class="pre">^</span></code>) declarator sigil to a
function type)</li>
<li>Objective-C object pointers (<code class="docutils literal"><span class="pre">id</span></code>, <code class="docutils literal"><span class="pre">Class</span></code>, <code class="docutils literal"><span class="pre">NSFoo*</span></code>, etc.)</li>
<li>typedefs marked with <code class="docutils literal"><span class="pre">__attribute__((NSObject))</span></code></li>
</ul>
<p>Other pointer types, such as <code class="docutils literal"><span class="pre">int*</span></code> and <code class="docutils literal"><span class="pre">CFStringRef</span></code>, are not subject to
ARC’s semantics and restrictions.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p>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 class="last simple">
<li>The type system must reliably identify which objects are to be managed. An
<code class="docutils literal"><span class="pre">int*</span></code> might be a pointer to a <code class="docutils literal"><span class="pre">malloc</span></code>‘ed array, or it might be an
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 “ownership” 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>
<p>The use of <code class="docutils literal"><span class="pre">__attribute__((NSObject))</span></code> 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
<code class="docutils literal"><span class="pre">__typeof</span></code> and C++ template argument substitution.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">Any compiler operation which incidentally strips type “sugar” from a type
will yield a type without the attribute, which may result in unexpected
behavior.</p>
</div>
<div class="section" id="retain-count-semantics">
<span id="arc-objects-retains"></span><h3><a class="toc-backref" href="#id10">Retain count semantics</a><a class="headerlink" href="#retain-count-semantics" title="Permalink to this headline">¶</a></h3>
<p>A retainable object pointer is either a <span class="arc-term">null pointer</span> or a pointer
to a valid object. Furthermore, if it has block pointer type and is not
<code class="docutils literal"><span class="pre">null</span></code> then it must actually be a pointer to a block object, and if it has
<code class="docutils literal"><span class="pre">Class</span></code> 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 “well-behaved” 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 class="simple">
<li><code class="docutils literal"><span class="pre">retain</span></code>, taking no arguments and returning a pointer to the object.</li>
<li><code class="docutils literal"><span class="pre">release</span></code>, taking no arguments and returning <code class="docutils literal"><span class="pre">void</span></code>.</li>
<li><code class="docutils literal"><span class="pre">autorelease</span></code>, 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="arc-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 <code class="docutils literal"><span class="pre">retain</span></code>, 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
<code class="docutils literal"><span class="pre">retain</span></code> followed by a send of <code class="docutils literal"><span class="pre">release</span></code> to the same object, with no
intervening <code class="docutils literal"><span class="pre">release</span></code> 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 <code class="docutils literal"><span class="pre">release</span></code> that is not
preceded by a send of <code class="docutils literal"><span class="pre">retain</span></code> to the same object.</p>
<p>The behavior of <code class="docutils literal"><span class="pre">autorelease</span></code> must be equivalent to sending <code class="docutils literal"><span class="pre">release</span></code> 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 <code class="docutils literal"><span class="pre">null</span></code> then the effect is a no-op.</p>
<p>All of the semantics described in this document are subject to additional
<a class="reference internal" href="#arc-optimization"><span class="std std-ref">optimization rules</span></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>
<div class="section" id="retainable-object-pointers-as-operands-and-arguments">
<span id="arc-objects-operands"></span><h3><a class="toc-backref" href="#id11">Retainable object pointers as operands and arguments</a><a class="headerlink" href="#retainable-object-pointers-as-operands-and-arguments" title="Permalink to this headline">¶</a></h3>
<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 class="simple">
<li>loading a retainable pointer from an object with non-weak <a class="reference internal" href="#arc-ownership"><span class="std std-ref">ownership</span></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="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">While this might seem uncontroversial, it is actually unsafe when multiple
expressions are evaluated in “parallel”, 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 class="section" id="consumed-parameters">
<span id="arc-objects-operands-consumed"></span><h4><a class="toc-backref" href="#id12">Consumed parameters</a><a class="headerlink" href="#consumed-parameters" title="Permalink to this headline">¶</a></h4>
<p>A function or method parameter of retainable object pointer type may be marked
as <span class="arc-term">consumed</span>, signifying that the callee expects to take ownership
of a +1 retain count. This is done by adding the <code class="docutils literal"><span class="pre">ns_consumed</span></code> attribute to
the parameter declaration, like so:</p>
<div class="highlight-objc"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="n">__attribute</span><span class="p">((</span><span class="n">ns_consumed</span><span class="p">))</span> <span class="kt">id</span> <span class="n">x</span><span class="p">);</span>
<span class="p">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="nf">foo:</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span> <span class="nv">__attribute</span><span class="p">((</span><span class="n">ns_consumed</span><span class="p">))</span> <span class="nv">x</span><span class="p">;</span>
</pre></div>
</div>
<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="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">This formalizes direct transfers of ownership from a caller to a callee. The
most common scenario here is passing the <code class="docutils literal"><span class="pre">self</span></code> parameter to <code class="docutils literal"><span class="pre">init</span></code>, 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 <code class="docutils literal"><span class="pre">self</span></code> parameter of a method may be marked as consumed by adding
<code class="docutils literal"><span class="pre">__attribute__((ns_consumes_self))</span></code> to the method declaration. Methods in
the <code class="docutils literal"><span class="pre">init</span></code> <a class="reference internal" href="#arc-method-families"><span class="std std-ref">family</span></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
<code class="docutils literal"><span class="pre">ns_consumed</span></code> 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 <code class="docutils literal"><span class="pre">ns_consumed</span></code> 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
<code class="docutils literal"><span class="pre">ns_consumed</span></code> parameters than the implementation of the called block or
function.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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>
<div class="section" id="retained-return-values">
<span id="arc-object-operands-retained-return-values"></span><h4><a class="toc-backref" href="#id13">Retained return values</a><a class="headerlink" href="#retained-return-values" title="Permalink to this headline">¶</a></h4>
<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
<code class="docutils literal"><span class="pre">ns_returns_retained</span></code> attribute to the function or method declaration, like
so:</p>
<div class="highlight-objc"><div class="highlight"><pre><span></span><span class="kt">id</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute</span><span class="p">((</span><span class="n">ns_returns_retained</span><span class="p">));</span>
<span class="p">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span> <span class="nf">foo</span> <span class="n">__attribute</span><span class="p">((</span><span class="n">ns_returns_retained</span><span class="p">));</span>
</pre></div>
</div>
<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="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">This formalizes direct transfers of ownership from a callee to a caller. The
most common scenario this models is the retained return from <code class="docutils literal"><span class="pre">init</span></code>,
<code class="docutils literal"><span class="pre">alloc</span></code>, <code class="docutils literal"><span class="pre">new</span></code>, and <code class="docutils literal"><span class="pre">copy</span></code> 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 <code class="docutils literal"><span class="pre">alloc</span></code>, <code class="docutils literal"><span class="pre">copy</span></code>, <code class="docutils literal"><span class="pre">init</span></code>, <code class="docutils literal"><span class="pre">mutableCopy</span></code>, and <code class="docutils literal"><span class="pre">new</span></code>
<a class="reference internal" href="#arc-method-families"><span class="std std-ref">families</span></a> are implicitly marked
<code class="docutils literal"><span class="pre">__attribute__((ns_returns_retained))</span></code>. This may be suppressed by explicitly
marking the method <code class="docutils literal"><span class="pre">__attribute__((ns_returns_not_retained))</span></code>.</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="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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>
<div class="section" id="unretained-return-values">
<span id="arc-objects-operands-unretained-returns"></span><h4><a class="toc-backref" href="#id14">Unretained return values</a><a class="headerlink" href="#unretained-return-values" title="Permalink to this headline">¶</a></h4>
<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 <code class="docutils literal"><span class="pre">autorelease</span></code>, 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="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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
<code class="docutils literal"><span class="pre">__attribute__((ns_returns_autoreleased))</span></code> 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>
<div class="section" id="bridged-casts">
<span id="arc-objects-operands-casts"></span><h4><a class="toc-backref" href="#id15">Bridged casts</a><a class="headerlink" href="#bridged-casts" title="Permalink to this headline">¶</a></h4>
<p>A <span class="arc-term">bridged cast</span> is a C-style cast annotated with one of three
keywords:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">(__bridge</span> <span class="pre">T)</span> <span class="pre">op</span></code> casts the operand to the destination type <code class="docutils literal"><span class="pre">T</span></code>. If
<code class="docutils literal"><span class="pre">T</span></code> is a retainable object pointer type, then <code class="docutils literal"><span class="pre">op</span></code> must have a
non-retainable pointer type. If <code class="docutils literal"><span class="pre">T</span></code> is a non-retainable pointer type,
then <code class="docutils literal"><span class="pre">op</span></code> 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><code class="docutils literal"><span class="pre">(__bridge_retained</span> <span class="pre">T)</span> <span class="pre">op</span></code> 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><code class="docutils literal"><span class="pre">(__bridge_transfer</span> <span class="pre">T)</span> <span class="pre">op</span></code> 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 class="reference internal" href="#arc-objects-restrictions-conversion"><span class="std std-ref">conversion of retainable
object pointers</span></a>.</p>
<p>Using a <code class="docutils literal"><span class="pre">__bridge_retained</span></code> or <code class="docutils literal"><span class="pre">__bridge_transfer</span></code> cast purely to convince
ARC to emit an unbalanced retain or release, respectively, is poor form.</p>
</div>
</div>
<div class="section" id="restrictions">
<span id="arc-objects-restrictions"></span><h3><a class="toc-backref" href="#id16">Restrictions</a><a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h3>
<div class="section" id="conversion-of-retainable-object-pointers">
<span id="arc-objects-restrictions-conversion"></span><h4><a class="toc-backref" href="#id17">Conversion of retainable object pointers</a><a class="headerlink" href="#conversion-of-retainable-object-pointers" title="Permalink to this headline">¶</a></h4>
<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 <code class="docutils literal"><span class="pre">void*</span></code>. As an exception, cast to <code class="docutils literal"><span class="pre">intptr_t</span></code> is
allowed because such casts are not transferring ownership. The <a class="reference internal" href="#arc-objects-operands-casts"><span class="std std-ref">bridged
casts</span></a> may be used to perform these conversions
where necessary.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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>
<div class="section" id="conversion-to-retainable-object-pointer-type-of-expressions-with-known-semantics">
<span id="arc-objects-restrictions-conversion-with-known-semantics"></span><h4><a class="toc-backref" href="#id18">Conversion to retainable object pointer type of expressions with known semantics</a><a class="headerlink" href="#conversion-to-retainable-object-pointer-type-of-expressions-with-known-semantics" title="Permalink to this headline">¶</a></h4>
<p><span class="when-revised">[beginning Apple 4.0, LLVM 3.1]</span>
<span class="revision">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="arc-term">known retain-agnostic</span> if it is:</p>
<ul class="simple">
<li>an Objective-C string literal,</li>
<li>a load from a <code class="docutils literal"><span class="pre">const</span></code> system global variable of <a class="reference internal" href="#arc-misc-c-retainable"><span class="std std-ref">C retainable pointer
type</span></a>, or</li>
<li>a null pointer constant.</li>
</ul>
<p>An expression is <span class="arc-term">known unretained</span> if it is an rvalue of <a class="reference internal" href="#arc-misc-c-retainable"><span class="std std-ref">C
retainable pointer type</span></a> and it is:</p>
<ul class="simple">
<li>a direct call to a function, and either that function has the
<code class="docutils literal"><span class="pre">cf_returns_not_retained</span></code> attribute or it is an <a class="reference internal" href="#arc-misc-c-retainable-audit"><span class="std std-ref">audited</span></a> function that does not have the
<code class="docutils literal"><span class="pre">cf_returns_retained</span></code> attribute and does not follow the create/copy naming
convention,</li>
<li>a message send, and the declared method either has the
<code class="docutils literal"><span class="pre">cf_returns_not_retained</span></code> attribute or it has neither the
<code class="docutils literal"><span class="pre">cf_returns_retained</span></code> attribute nor a <a class="reference internal" href="#arc-method-families"><span class="std std-ref">selector family</span></a> that implies a retained result, or</li>
<li><span class="when-revised">[beginning LLVM 3.6]</span> <span class="revision">a load from a</span> <code class="docutils literal"><span class="pre">const</span></code>
<span class="revision">non-system global variable.</span></li>
</ul>
<p>An expression is <span class="arc-term">known retained</span> if it is an rvalue of <a class="reference internal" href="#arc-misc-c-retainable"><span class="std std-ref">C
retainable pointer type</span></a> and it is:</p>
<ul class="simple">
<li>a message send, and the declared method either has the
<code class="docutils literal"><span class="pre">cf_returns_retained</span></code> attribute, or it does not have the
<code class="docutils literal"><span class="pre">cf_returns_not_retained</span></code> attribute but it does have a <a class="reference internal" href="#arc-method-families"><span class="std std-ref">selector
family</span></a> that implies a retained result.</li>
</ul>
<p>Furthermore:</p>
<ul class="simple">
<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
<code class="docutils literal"><span class="pre">__bridge_transfer</span></code> cast. If the cast operand is known unretained or known
retain-agnostic, the conversion is treated as a <code class="docutils literal"><span class="pre">__bridge</span></code> cast.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p>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 <code class="docutils literal"><span class="pre">__bridge_transfer</span></code> casts. The worry is
that some code patterns — for example, creating a CF value, assigning it
to an ObjC-typed local, and then calling <code class="docutils literal"><span class="pre">CFRelease</span></code> when done — are a
bit too likely to be accidentally accepted, leading to mysterious behavior.</p>
<p class="last">For loads from <code class="docutils literal"><span class="pre">const</span></code> global variables of <a class="reference internal" href="#arc-misc-c-retainable"><span class="std std-ref">C retainable pointer type</span></a>, it is reasonable to assume that global system
constants were initialitzed with true constants (e.g. string literals), but
user constants might have been initialized with something dynamically
allocated, using a global initializer.</p>
</div>
</div>
<div class="section" id="conversion-from-retainable-object-pointer-type-in-certain-contexts">
<span id="arc-objects-restrictions-conversion-exception-contextual"></span><h4><a class="toc-backref" href="#id19">Conversion from retainable object pointer type in certain contexts</a><a class="headerlink" href="#conversion-from-retainable-object-pointer-type-in-certain-contexts" title="Permalink to this headline">¶</a></h4>
<p><span class="when-revised">[beginning Apple 4.0, LLVM 3.1]</span></p>
<p>If an expression of retainable object pointer type is explicitly cast to a
<a class="reference internal" href="#arc-misc-c-retainable"><span class="std std-ref">C retainable pointer type</span></a>, the program is
ill-formed as discussed above unless the result is immediately used:</p>
<ul class="simple">
<li>to initialize a parameter in an Objective-C message send where the parameter
is not marked with the <code class="docutils literal"><span class="pre">cf_consumed</span></code> attribute, or</li>
<li>to initialize a parameter in a direct call to an
<a class="reference internal" href="#arc-misc-c-retainable-audit"><span class="std std-ref">audited</span></a> function where the parameter is
not marked with the <code class="docutils literal"><span class="pre">cf_consumed</span></code> attribute.</li>
</ul>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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 <code class="docutils literal"><span class="pre">Release</span></code> family,
and it would be quite unfortunate for explicit releases to be silently
balanced out in this way.</p>
</div>
</div>
</div>
</div>
<div class="section" id="ownership-qualification">
<span id="arc-ownership"></span><h2><a class="toc-backref" href="#id20">Ownership qualification</a><a class="headerlink" href="#ownership-qualification" title="Permalink to this headline">¶</a></h2>
<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="arc-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="arc-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>When forming a function type, the result type is adjusted so that any
top-level ownership qualifier is deleted.</p>
<p>Except as described under the <a class="reference internal" href="#arc-ownership-inference"><span class="std std-ref">inference rules</span></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="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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 class="reference internal" href="#arc-ownership-inference-template-arguments"><span class="std std-ref">inference of __strong for template type
arguments</span></a>. Ownership qualifiers
on return types are dropped because they serve no purpose there except to
cause spurious problems with overloading and templates.</p>
</div>
<p>There are four ownership qualifiers:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">__autoreleasing</span></code></li>
<li><code class="docutils literal"><span class="pre">__strong</span></code></li>
<li><code class="docutils literal"><span class="pre">__unsafe_unretained</span></code></li>
<li><code class="docutils literal"><span class="pre">__weak</span></code></li>
</ul>
<p>A type is <span class="arc-term">nontrivially ownership-qualified</span> if it is qualified with
<code class="docutils literal"><span class="pre">__autoreleasing</span></code>, <code class="docutils literal"><span class="pre">__strong</span></code>, or <code class="docutils literal"><span class="pre">__weak</span></code>.</p>
<div class="section" id="spelling">
<span id="arc-ownership-spelling"></span><h3><a class="toc-backref" href="#id21">Spelling</a><a class="headerlink" href="#spelling" title="Permalink to this headline">¶</a></h3>
<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 <em>declaration-specifiers</em>, the
following rules apply:</p>
<ul class="simple">
<li>if the type specifier is a retainable object owner type, the qualifier
initially applies to that type;</li>
<li>otherwise, if the outermost non-array declarator is a pointer
or block pointer declarator, the qualifier initially applies to
that type;</li>
<li>otherwise the program is ill-formed.</li>
<li>If the qualifier is so applied at a position in the declaration
where the next-innermost declarator is a function declarator, and
there is an block declarator within that function declarator, then
the qualifier applies instead to that block declarator and this rule
is considered afresh beginning from the new position.</li>
</ul>
<p>If an ownership qualifier appears on the declarator name, or on the declared
object, it is applied to the innermost 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 class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">Ownership qualifiers are like <code class="docutils literal"><span class="pre">const</span></code> and <code class="docutils literal"><span class="pre">volatile</span></code> in the sense
that they may sensibly apply at multiple distinct positions within a
declarator. However, unlike those qualifiers, there are many
situations where they are not meaningful, and so we make an effort
to “move” the qualifier to a place where it will be meaningful. The
general goal is to allow the programmer to write, say, <code class="docutils literal"><span class="pre">__strong</span></code>
before the entire declaration and have it apply in the leftmost
sensible place.</p>
</div>
<div class="section" id="property-declarations">
<span id="arc-ownership-spelling-property"></span><h4><a class="toc-backref" href="#id22">Property declarations</a><a class="headerlink" href="#property-declarations" title="Permalink to this headline">¶</a></h4>
<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
<code class="docutils literal"><span class="pre">__autoreleasing</span></code> ownership.</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">assign</span></code> implies <code class="docutils literal"><span class="pre">__unsafe_unretained</span></code> ownership.</li>
<li><code class="docutils literal"><span class="pre">copy</span></code> implies <code class="docutils literal"><span class="pre">__strong</span></code> ownership, as well as the usual behavior of
copy semantics on the setter.</li>
<li><code class="docutils literal"><span class="pre">retain</span></code> implies <code class="docutils literal"><span class="pre">__strong</span></code> ownership.</li>
<li><code class="docutils literal"><span class="pre">strong</span></code> implies <code class="docutils literal"><span class="pre">__strong</span></code> ownership.</li>
<li><code class="docutils literal"><span class="pre">unsafe_unretained</span></code> implies <code class="docutils literal"><span class="pre">__unsafe_unretained</span></code> ownership.</li>
<li><code class="docutils literal"><span class="pre">weak</span></code> implies <code class="docutils literal"><span class="pre">__weak</span></code> ownership.</li>
</ul>
<p>With the exception of <code class="docutils literal"><span class="pre">weak</span></code>, 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="arc-term">associated instance variable</span> is
the instance variable which is named, possibly implicitly, by the
<code class="docutils literal"><span class="pre">@synthesize</span></code> 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="when-revised">[beginning Apple 3.1, LLVM 3.1]</span>
<span class="revision">its ownership is implicitly</span> <code class="docutils literal"><span class="pre">strong</span></code>. Prior to this revision, it
was ill-formed to synthesize such a property.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">Using <code class="docutils literal"><span class="pre">strong</span></code> by default is safe and consistent with the generic ARC rule
about <a class="reference internal" href="#arc-ownership-inference-variables"><span class="std std-ref">inferring ownership</span></a>. It is,
unfortunately, inconsistent with the non-ARC rule which states that such
properties are implicitly <code class="docutils literal"><span class="pre">assign</span></code>. 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>
<p>Applying <code class="docutils literal"><span class="pre">__attribute__((NSObject))</span></code> to a property not of retainable object
pointer type has the same behavior it does outside of ARC: it requires the
property type to be some sort of pointer and permits the use of modifiers other
than <code class="docutils literal"><span class="pre">assign</span></code>. These modifiers only affect the synthesized getter and
setter; direct accesses to the ivar (even if synthesized) still have primitive
semantics, and the value in the ivar will not be automatically released during
deallocation.</p>
</div>
</div>
<div class="section" id="semantics">
<span id="arc-ownership-semantics"></span><h3><a class="toc-backref" href="#id23">Semantics</a><a class="headerlink" href="#semantics" title="Permalink to this headline">¶</a></h3>
<p>There are five <span class="arc-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 “primitive semantics” has the same semantics as the
respective operation would have on an <code class="docutils literal"><span class="pre">void*</span></code> lvalue with the same alignment
and non-ownership qualification.</p>
<p><span class="arc-term">Reading</span> occurs when performing a lvalue-to-rvalue conversion on an
object lvalue.</p>
<ul class="simple">
<li>For <code class="docutils literal"><span class="pre">__weak</span></code> 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="arc-term">Assignment</span> occurs when evaluating an assignment operator. The
semantics vary based on the qualification:</p>
<ul class="simple">
<li>For <code class="docutils literal"><span class="pre">__strong</span></code> 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 <code class="docutils literal"><span class="pre">__weak</span></code> 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 <code class="docutils literal"><span class="pre">__unsafe_unretained</span></code> objects, the new pointee is stored into the
lvalue using primitive semantics.</li>
<li>For <code class="docutils literal"><span class="pre">__autoreleasing</span></code> objects, the new pointee is retained, autoreleased,
and stored into the lvalue using primitive semantics.</li>
</ul>
<p><span class="arc-term">Initialization</span> occurs when an object’s lifetime begins, which
depends on its storage duration. Initialization proceeds in two stages:</p>
<ol class="arabic simple">
<li>First, a null pointer is stored into the lvalue using primitive semantics.
This step is skipped if the object is <code class="docutils literal"><span class="pre">__unsafe_unretained</span></code>.</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="arc-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="arc-term">Moving</span> occurs in specific situations where an lvalue is “moved
from”, meaning that its current pointee will be used but the object may be left
in a different (but still valid) state. This arises with <code class="docutils literal"><span class="pre">__block</span></code> variables
and rvalue references in C++. For <code class="docutils literal"><span class="pre">__strong</span></code> 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>
<div class="section" id="arc-ownership-restrictions">
<span id="id1"></span><h3><a class="toc-backref" href="#id24">Restrictions</a><a class="headerlink" href="#arc-ownership-restrictions" title="Permalink to this headline">¶</a></h3>
<div class="section" id="weak-unavailable-types">
<span id="arc-ownership-restrictions-weak"></span><h4><a class="toc-backref" href="#id25">Weak-unavailable types</a><a class="headerlink" href="#weak-unavailable-types" title="Permalink to this headline">¶</a></h4>
<p>It is explicitly permitted for Objective-C classes to not support <code class="docutils literal"><span class="pre">__weak</span></code>
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 <code class="docutils literal"><span class="pre">__weak</span></code> references.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">Historically, it has been possible for a class to provide its own
reference-count implementation by overriding <code class="docutils literal"><span class="pre">retain</span></code>, <code class="docutils literal"><span class="pre">release</span></code>, 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
<code class="docutils literal"><span class="pre">objc_arc_weak_unavailable</span></code> attribute on the class’s interface declaration. A
retainable object pointer type is <strong>weak-unavailable</strong> if
is a pointer to an (optionally protocol-qualified) Objective-C class <code class="docutils literal"><span class="pre">T</span></code> where
<code class="docutils literal"><span class="pre">T</span></code> or one of its superclasses has the <code class="docutils literal"><span class="pre">objc_arc_weak_unavailable</span></code>
attribute. A program is ill-formed if it applies the <code class="docutils literal"><span class="pre">__weak</span></code> ownership
qualifier to a weak-unavailable type or if the value operand of a weak
assignment operation has a weak-unavailable type.</p>
</div>
<div class="section" id="storage-duration-of-autoreleasing-objects">
<span id="arc-ownership-restrictions-autoreleasing"></span><h4><a class="toc-backref" href="#id26">Storage duration of <code class="docutils literal"><span class="pre">__autoreleasing</span></code> objects</a><a class="headerlink" href="#storage-duration-of-autoreleasing-objects" title="Permalink to this headline">¶</a></h4>
<p>A program is ill-formed if it declares an <code class="docutils literal"><span class="pre">__autoreleasing</span></code> object of
non-automatic storage duration. A program is ill-formed if it captures an
<code class="docutils literal"><span class="pre">__autoreleasing</span></code> object in a block or, unless by reference, in a C++11
lambda.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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
<code class="docutils literal"><span class="pre">__autoreleasing</span></code> 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 class="section" id="conversion-of-pointers-to-ownership-qualified-types">
<span id="arc-ownership-restrictions-conversion-indirect"></span><h4><a class="toc-backref" href="#id27">Conversion of pointers to ownership-qualified types</a><a class="headerlink" href="#conversion-of-pointers-to-ownership-qualified-types" title="Permalink to this headline">¶</a></h4>
<p>A program is ill-formed if an expression of type <code class="docutils literal"><span class="pre">T*</span></code> is converted,
explicitly or implicitly, to the type <code class="docutils literal"><span class="pre">U*</span></code>, where <code class="docutils literal"><span class="pre">T</span></code> and <code class="docutils literal"><span class="pre">U</span></code> have
different ownership qualification, unless:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">T</span></code> is qualified with <code class="docutils literal"><span class="pre">__strong</span></code>, <code class="docutils literal"><span class="pre">__autoreleasing</span></code>, or
<code class="docutils literal"><span class="pre">__unsafe_unretained</span></code>, and <code class="docutils literal"><span class="pre">U</span></code> is qualified with both <code class="docutils literal"><span class="pre">const</span></code> and
<code class="docutils literal"><span class="pre">__unsafe_unretained</span></code>; or</li>
<li>either <code class="docutils literal"><span class="pre">T</span></code> or <code class="docutils literal"><span class="pre">U</span></code> is <code class="docutils literal"><span class="pre">cv</span> <span class="pre">void</span></code>, where <code class="docutils literal"><span class="pre">cv</span></code> is an optional sequence
of non-ownership qualifiers; or</li>
<li>the conversion is requested with a <code class="docutils literal"><span class="pre">reinterpret_cast</span></code> in Objective-C++; or</li>
<li>the conversion is a well-formed <a class="reference internal" href="#arc-ownership-restrictions-pass-by-writeback"><span class="std std-ref">pass-by-writeback</span></a>.</li>
</ul>
<p>The analogous rule applies to <code class="docutils literal"><span class="pre">T&</span></code> and <code class="docutils literal"><span class="pre">U&</span></code> in Objective-C++.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">These rules provide a reasonable level of type-safety for indirect pointers,
as long as the underlying memory is not deallocated. The conversion to
<code class="docutils literal"><span class="pre">const</span> <span class="pre">__unsafe_unretained</span></code> 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 <code class="docutils literal"><span class="pre">void*</span></code> is useful for allocating
memory or otherwise escaping the type system, but use it carefully.
<code class="docutils literal"><span class="pre">reinterpret_cast</span></code> 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-<code class="docutils literal"><span class="pre">__weak</span></code> object
may be read through an <code class="docutils literal"><span class="pre">__unsafe_unretained</span></code> lvalue.</p>
<p>It is undefined behavior if a managed operation is performed on a <code class="docutils literal"><span class="pre">__strong</span></code>
or <code class="docutils literal"><span class="pre">__weak</span></code> 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="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">ARC cannot differentiate between an assignment operator which is intended to
“initialize” 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 (<code class="docutils literal"><span class="pre">__strong</span></code> objects) and consistency errors
(<code class="docutils literal"><span class="pre">__weak</span></code> objects).</p>
</div>
<p>These requirements are followed automatically in Objective-C++ when creating
objects of retainable object owner type with <code class="docutils literal"><span class="pre">new</span></code> or <code class="docutils literal"><span class="pre">new[]</span></code> and destroying
them with <code class="docutils literal"><span class="pre">delete</span></code>, <code class="docutils literal"><span class="pre">delete[]</span></code>, 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
<code class="docutils literal"><span class="pre">new[]</span></code>‘d in ARC translation units cannot be <code class="docutils literal"><span class="pre">delete[]</span></code>‘d in non-ARC
translation units and vice-versa.</p>
</div>
<div class="section" id="passing-to-an-out-parameter-by-writeback">
<span id="arc-ownership-restrictions-pass-by-writeback"></span><h4><a class="toc-backref" href="#id28">Passing to an out parameter by writeback</a><a class="headerlink" href="#passing-to-an-out-parameter-by-writeback" title="Permalink to this headline">¶</a></h4>
<p>If the argument passed to a parameter of type <code class="docutils literal"><span class="pre">T</span> <span class="pre">__autoreleasing</span> <span class="pre">*</span></code> has type
<code class="docutils literal"><span class="pre">U</span> <span class="pre">oq</span> <span class="pre">*</span></code>, where <code class="docutils literal"><span class="pre">oq</span></code> is an ownership qualifier, then the argument is a
candidate for <span class="arc-term">pass-by-writeback`</span> if:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">oq</span></code> is <code class="docutils literal"><span class="pre">__strong</span></code> or <code class="docutils literal"><span class="pre">__weak</span></code>, and</li>
<li>it would be legal to initialize a <code class="docutils literal"><span class="pre">T</span> <span class="pre">__strong</span> <span class="pre">*</span></code> with a <code class="docutils literal"><span class="pre">U</span> <span class="pre">__strong</span> <span class="pre">*</span></code>.</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 class="simple">
<li><code class="docutils literal"><span class="pre">&var</span></code>, where <code class="docutils literal"><span class="pre">var</span></code> 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="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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
“array” 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 class="arabic simple">
<li>The argument is evaluated to yield a pointer <code class="docutils literal"><span class="pre">p</span></code> of type <code class="docutils literal"><span class="pre">U</span> <span class="pre">oq</span> <span class="pre">*</span></code>.</li>
<li>If <code class="docutils literal"><span class="pre">p</span></code> 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 <code class="docutils literal"><span class="pre">T</span> <span class="pre">__autoreleasing</span></code> is created and
initialized to a null pointer.</li>
<li>If the parameter is not an Objective-C method parameter marked <code class="docutils literal"><span class="pre">out</span></code>,
then <code class="docutils literal"><span class="pre">*p</span></code> 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 <code class="docutils literal"><span class="pre">*p</span></code>.</li>
</ol>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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 <code class="docutils literal"><span class="pre">__autoreleasing</span></code> rather than <code class="docutils literal"><span class="pre">__strong</span></code>. 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
<code class="docutils literal"><span class="pre">__autoreleasing</span></code> on all the variables they intend to use for
out-parameters. This was the least bad solution.</p>
</div>
</div>
<div class="section" id="ownership-qualified-fields-of-structs-and-unions">
<span id="arc-ownership-restrictions-records"></span><h4><a class="toc-backref" href="#id29">Ownership-qualified fields of structs and unions</a><a class="headerlink" href="#ownership-qualified-fields-of-structs-and-unions" title="Permalink to this headline">¶</a></h4>
<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="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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 <code class="docutils literal"><span class="pre">void*</span></code> or an <code class="docutils literal"><span class="pre">__unsafe_unretained</span></code> 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="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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 class="section" id="ownership-inference">
<span id="arc-ownership-inference"></span><h3><a class="toc-backref" href="#id30">Ownership inference</a><a class="headerlink" href="#ownership-inference" title="Permalink to this headline">¶</a></h3>
<div class="section" id="objects">
<span id="arc-ownership-inference-variables"></span><h4><a class="toc-backref" href="#id31">Objects</a><a class="headerlink" href="#objects" title="Permalink to this headline">¶</a></h4>
<p>If an object is declared with retainable object owner type, but without an
explicit ownership qualifier, its type is implicitly adjusted to have
<code class="docutils literal"><span class="pre">__strong</span></code> qualification.</p>
<p>As a special case, if the object’s base type is <code class="docutils literal"><span class="pre">Class</span></code> (possibly
protocol-qualified), the type is adjusted to have <code class="docutils literal"><span class="pre">__unsafe_unretained</span></code>
qualification instead.</p>
</div>
<div class="section" id="indirect-parameters">
<span id="arc-ownership-inference-indirect-parameters"></span><h4><a class="toc-backref" href="#id32">Indirect parameters</a><a class="headerlink" href="#indirect-parameters" title="Permalink to this headline">¶</a></h4>
<p>If a function or method parameter has type <code class="docutils literal"><span class="pre">T*</span></code>, where <code class="docutils literal"><span class="pre">T</span></code> is an
ownership-unqualified retainable object pointer type, then:</p>
<ul class="simple">
<li>if <code class="docutils literal"><span class="pre">T</span></code> is <code class="docutils literal"><span class="pre">const</span></code>-qualified or <code class="docutils literal"><span class="pre">Class</span></code>, then it is implicitly
qualified with <code class="docutils literal"><span class="pre">__unsafe_unretained</span></code>;</li>
<li>otherwise, it is implicitly qualified with <code class="docutils literal"><span class="pre">__autoreleasing</span></code>.</li>
</ul>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last"><code class="docutils literal"><span class="pre">__autoreleasing</span></code> exists mostly for this case, the Cocoa convention for
out-parameters. Since a pointer to <code class="docutils literal"><span class="pre">const</span></code> 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
<code class="docutils literal"><span class="pre">__autoreleasing</span></code> 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="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">The convention is very unlikely to be intentional in template code.</p>
</div>
</div>
<div class="section" id="template-arguments">
<span id="arc-ownership-inference-template-arguments"></span><h4><a class="toc-backref" href="#id33">Template arguments</a><a class="headerlink" href="#template-arguments" title="Permalink to this headline">¶</a></h4>
<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 <code class="docutils literal"><span class="pre">__strong</span></code> qualification. This adjustment occurs regardless of
whether the template argument was deduced or explicitly specified.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last"><code class="docutils literal"><span class="pre">__strong</span></code> is a useful default for containers (e.g., <code class="docutils literal"><span class="pre">std::vector<id></span></code>),
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>
</div>
</div>
<div class="section" id="method-families">
<span id="arc-method-families"></span><h2><a class="toc-backref" href="#id34">Method families</a><a class="headerlink" href="#method-families" title="Permalink to this headline">¶</a></h2>
<p>An Objective-C method may fall into a <span class="arc-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 class="simple">
<li>it has a <code class="docutils literal"><span class="pre">objc_method_family</span></code> attribute placing it in that family; or if
not that,</li>
<li>it does not have an <code class="docutils literal"><span class="pre">objc_method_family</span></code> 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, <code class="docutils literal"><span class="pre">_perform:with:</span></code> and
<code class="docutils literal"><span class="pre">performWith:</span></code> would fall into the <code class="docutils literal"><span class="pre">perform</span></code> family (if we recognized one),
but <code class="docutils literal"><span class="pre">performing:with</span></code> would not.</p>
<p>The families and their added restrictions are:</p>
<ul>
<li><p class="first"><code class="docutils literal"><span class="pre">alloc</span></code> methods must return a retainable object pointer type.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">copy</span></code> methods must return a retainable object pointer type.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">mutableCopy</span></code> methods must return a retainable object pointer type.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">new</span></code> methods must return a retainable object pointer type.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">init</span></code> 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 <code class="docutils literal"><span class="pre">init</span></code> method whose return type is neither <code class="docutils literal"><span class="pre">id</span></code> 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).</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p>There are a fair number of existing methods with <code class="docutils literal"><span class="pre">init</span></code>-like selectors
which nonetheless don’t follow the <code class="docutils literal"><span class="pre">init</span></code> conventions. Typically these
are either accidental naming collisions or helper methods called during
initialization. Because of the peculiar retain/release behavior of
<code class="docutils literal"><span class="pre">init</span></code> methods, it’s very important not to treat these methods as
<code class="docutils literal"><span class="pre">init</span></code> 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 <code class="docutils literal"><span class="pre">init</span></code> family.</p>
<p class="last">Note that a method with an <code class="docutils literal"><span class="pre">init</span></code>-family selector which returns a
non-Objective-C type (e.g. <code class="docutils literal"><span class="pre">void</span></code>) is perfectly well-formed; it simply
isn’t in the <code class="docutils literal"><span class="pre">init</span></code> 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 class="section" id="explicit-method-family-control">
<span id="arc-family-attribute"></span><h3><a class="toc-backref" href="#id35">Explicit method family control</a><a class="headerlink" href="#explicit-method-family-control" title="Permalink to this headline">¶</a></h3>
<p>A method may be annotated with the <code class="docutils literal"><span class="pre">objc_method_family</span></code> attribute to
precisely control which method family it belongs to. If a method in an
<code class="docutils literal"><span class="pre">@implementation</span></code> does not have this attribute, but there is a method
declared in the corresponding <code class="docutils literal"><span class="pre">@interface</span></code> that does, then the attribute is
copied to the declaration in the <code class="docutils literal"><span class="pre">@implementation</span></code>. The attribute is
available outside of ARC, and may be tested for with the preprocessor query
<code class="docutils literal"><span class="pre">__has_attribute(objc_method_family)</span></code>.</p>
<p>The attribute is spelled
<code class="docutils literal"><span class="pre">__attribute__((objc_method_family(</span></code> <em>family</em> <code class="docutils literal"><span class="pre">)))</span></code>. If <em>family</em> is
<code class="docutils literal"><span class="pre">none</span></code>, the method has no family, even if it would otherwise be considered to
have one based on its selector and type. Otherwise, <em>family</em> must be one of
<code class="docutils literal"><span class="pre">alloc</span></code>, <code class="docutils literal"><span class="pre">copy</span></code>, <code class="docutils literal"><span class="pre">init</span></code>, <code class="docutils literal"><span class="pre">mutableCopy</span></code>, or <code class="docutils literal"><span class="pre">new</span></code>, 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="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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
<code class="docutils literal"><span class="pre">ns_returns_retained</span></code>, this attribute allows the user to communicate
semantic intent, which is of use both to ARC (which, e.g., treats calls to
<code class="docutils literal"><span class="pre">init</span></code> specially) and the static analyzer.</p>
</div>
</div>
<div class="section" id="semantics-of-method-families">
<span id="arc-family-semantics"></span><h3><a class="toc-backref" href="#id36">Semantics of method families</a><a class="headerlink" href="#semantics-of-method-families" title="Permalink to this headline">¶</a></h3>
<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 <code class="docutils literal"><span class="pre">alloc</span></code>, <code class="docutils literal"><span class="pre">copy</span></code>, <code class="docutils literal"><span class="pre">mutableCopy</span></code>, and <code class="docutils literal"><span class="pre">new</span></code> families —
that is, methods in all the currently-defined families except <code class="docutils literal"><span class="pre">init</span></code> —
implicitly <a class="reference internal" href="#arc-object-operands-retained-return-values"><span class="std std-ref">return a retained object</span></a> as if they were annotated with
the <code class="docutils literal"><span class="pre">ns_returns_retained</span></code> attribute. This can be overridden by annotating
the method with either of the <code class="docutils literal"><span class="pre">ns_returns_autoreleased</span></code> or
<code class="docutils literal"><span class="pre">ns_returns_not_retained</span></code> attributes.</p>
<p>Properties also follow same naming rules as methods. This means that those in
the <code class="docutils literal"><span class="pre">alloc</span></code>, <code class="docutils literal"><span class="pre">copy</span></code>, <code class="docutils literal"><span class="pre">mutableCopy</span></code>, and <code class="docutils literal"><span class="pre">new</span></code> families provide access
to <a class="reference internal" href="#arc-object-operands-retained-return-values"><span class="std std-ref">retained objects</span></a>. This
can be overridden by annotating the property with <code class="docutils literal"><span class="pre">ns_returns_not_retained</span></code>
attribute.</p>
<div class="section" id="semantics-of-init">
<span id="arc-family-semantics-init"></span><h4><a class="toc-backref" href="#id37">Semantics of <code class="docutils literal"><span class="pre">init</span></code></a><a class="headerlink" href="#semantics-of-init" title="Permalink to this headline">¶</a></h4>
<p>Methods in the <code class="docutils literal"><span class="pre">init</span></code> family implicitly <a class="reference internal" href="#arc-objects-operands-consumed"><span class="std std-ref">consume</span></a> their <code class="docutils literal"><span class="pre">self</span></code> parameter and <a class="reference internal" href="#arc-object-operands-retained-return-values"><span class="std std-ref">return a
retained object</span></a>. Neither of
these properties can be altered through attributes.</p>
<p>A call to an <code class="docutils literal"><span class="pre">init</span></code> method with a receiver that is either <code class="docutils literal"><span class="pre">self</span></code> (possibly
parenthesized or casted) or <code class="docutils literal"><span class="pre">super</span></code> is called a <span class="arc-term">delegate init
call</span>. It is an error for a delegate init call to be made except from an
<code class="docutils literal"><span class="pre">init</span></code> method, and excluding blocks within such methods.</p>
<p>As an exception to the <a class="reference internal" href="#arc-misc-self"><span class="std std-ref">usual rule</span></a>, the variable <code class="docutils literal"><span class="pre">self</span></code>
is mutable in an <code class="docutils literal"><span class="pre">init</span></code> method and has the usual semantics for a <code class="docutils literal"><span class="pre">__strong</span></code>
variable. However, it is undefined behavior and the program is ill-formed, no
diagnostic required, if an <code class="docutils literal"><span class="pre">init</span></code> method attempts to use the previous value
of <code class="docutils literal"><span class="pre">self</span></code> after the completion of a delegate init call. It is conventional,
but not required, for an <code class="docutils literal"><span class="pre">init</span></code> method to return <code class="docutils literal"><span class="pre">self</span></code>.</p>
<p>It is undefined behavior for a program to cause two or more calls to <code class="docutils literal"><span class="pre">init</span></code>
methods on the same object, except that each <code class="docutils literal"><span class="pre">init</span></code> method invocation may
perform at most one delegate init call.</p>
</div>
<div class="section" id="related-result-types">
<span id="arc-family-semantics-result-type"></span><h4><a class="toc-backref" href="#id38">Related result types</a><a class="headerlink" href="#related-result-types" title="Permalink to this headline">¶</a></h4>
<p>Certain methods are candidates to have <span class="arc-term">related result types</span>:</p>
<ul class="simple">
<li>class methods in the <code class="docutils literal"><span class="pre">alloc</span></code> and <code class="docutils literal"><span class="pre">new</span></code> method families</li>
<li>instance methods in the <code class="docutils literal"><span class="pre">init</span></code> family</li>
<li>the instance method <code class="docutils literal"><span class="pre">self</span></code></li>
<li>outside of ARC, the instance methods <code class="docutils literal"><span class="pre">retain</span></code> and <code class="docutils literal"><span class="pre">autorelease</span></code></li>
</ul>
<p>If the formal result type of such a method is <code class="docutils literal"><span class="pre">id</span></code> or protocol-qualified
<code class="docutils literal"><span class="pre">id</span></code>, 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 class="simple">
<li>if it is a class method, and the receiver is a class name <code class="docutils literal"><span class="pre">T</span></code>, the message
send expression has type <code class="docutils literal"><span class="pre">T*</span></code>; otherwise</li>
<li>if it is an instance method, and the receiver has type <code class="docutils literal"><span class="pre">T</span></code>, the message
send expression has type <code class="docutils literal"><span class="pre">T</span></code>; 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="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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>
</div>
</div>
<div class="section" id="optimization">
<span id="arc-optimization"></span><h2><a class="toc-backref" href="#id39">Optimization</a><a class="headerlink" href="#optimization" title="Permalink to this headline">¶</a></h2>
<p>Within this section, the word <span class="arc-term">function</span> will be used to
refer to any structured unit of code, be it a C function, an
Objective-C method, or a block.</p>
<p>This specification describes ARC as performing specific <code class="docutils literal"><span class="pre">retain</span></code> and
<code class="docutils literal"><span class="pre">release</span></code> operations on retainable object pointers at specific
points during the execution of a program. These operations make up a
non-contiguous subsequence of the computation history of the program.
The portion of this sequence for a particular retainable object
pointer for which a specific function execution is directly
responsible is the <span class="arc-term">formal local retain history</span> of the
object pointer. The corresponding actual sequence executed is the
<cite>dynamic local retain history</cite>.</p>
<p>However, under certain circumstances, ARC is permitted to re-order and
eliminate operations in a manner which may alter the overall
computation history beyond what is permitted by the general “as if”
rule of C/C++ and the <a class="reference internal" href="#arc-objects-retains"><span class="std std-ref">restrictions</span></a> on
the implementation of <code class="docutils literal"><span class="pre">retain</span></code> and <code class="docutils literal"><span class="pre">release</span></code>.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p>Specifically, ARC is sometimes permitted to optimize <code class="docutils literal"><span class="pre">release</span></code>
operations in ways which might cause an object to be deallocated
before it would otherwise be. Without this, it would be almost
impossible to eliminate any <code class="docutils literal"><span class="pre">retain</span></code>/<code class="docutils literal"><span class="pre">release</span></code> pairs. For
example, consider the following code:</p>
<div class="highlight-objc"><div class="highlight"><pre><span></span><span class="kt">id</span> <span class="n">x</span> <span class="o">=</span> <span class="n">_ivar</span><span class="p">;</span>
<span class="p">[</span><span class="n">x</span> <span class="n">foo</span><span class="p">];</span>
</pre></div>
</div>
<p class="last">If we were not permitted in any event to shorten the lifetime of the
object in <code class="docutils literal"><span class="pre">x</span></code>, then we would not be able to eliminate this retain
and release unless we could prove that the message send could not
modify <code class="docutils literal"><span class="pre">_ivar</span></code> (or deallocate <code class="docutils literal"><span class="pre">self</span></code>). Since message sends are
opaque to the optimizer, this is not possible, and so ARC’s hands
would be almost completely tied.</p>
</div>
<p>ARC makes no guarantees about the execution of a computation history
which contains undefined behavior. In particular, ARC makes no
guarantees in the presence of race conditions.</p>
<p>ARC may assume that any retainable object pointers it receives or
generates are instantaneously valid from that point until a point
which, by the concurrency model of the host language, happens-after
the generation of the pointer and happens-before a release of that
object (possibly via an aliasing pointer or indirectly due to
destruction of a different object).</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">There is very little point in trying to guarantee correctness in the
presence of race conditions. ARC does not have a stack-scanning
garbage collector, and guaranteeing the atomicity of every load and
store operation would be prohibitive and preclude a vast amount of
optimization.</p>
</div>
<p>ARC may assume that non-ARC code engages in sensible balancing
behavior and does not rely on exact or minimum retain count values
except as guaranteed by <code class="docutils literal"><span class="pre">__strong</span></code> object invariants or +1 transfer
conventions. For example, if an object is provably double-retained
and double-released, ARC may eliminate the inner retain and release;
it does not need to guard against code which performs an unbalanced
release followed by a “balancing” retain.</p>
<div class="section" id="object-liveness">
<span id="arc-optimization-liveness"></span><h3><a class="toc-backref" href="#id40">Object liveness</a><a class="headerlink" href="#object-liveness" title="Permalink to this headline">¶</a></h3>
<p>ARC may not allow a retainable object <code class="docutils literal"><span class="pre">X</span></code> to be deallocated at a
time <code class="docutils literal"><span class="pre">T</span></code> in a computation history if:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">X</span></code> is the value stored in a <code class="docutils literal"><span class="pre">__strong</span></code> object <code class="docutils literal"><span class="pre">S</span></code> with
<a class="reference internal" href="#arc-optimization-precise"><span class="std std-ref">precise lifetime semantics</span></a>, or</li>
<li><code class="docutils literal"><span class="pre">X</span></code> is the value stored in a <code class="docutils literal"><span class="pre">__strong</span></code> object <code class="docutils literal"><span class="pre">S</span></code> with
imprecise lifetime semantics and, at some point after <code class="docutils literal"><span class="pre">T</span></code> but
before the next store to <code class="docutils literal"><span class="pre">S</span></code>, the computation history features a
load from <code class="docutils literal"><span class="pre">S</span></code> and in some way depends on the value loaded, or</li>
<li><code class="docutils literal"><span class="pre">X</span></code> is a value described as being released at the end of the
current full-expression and, at some point after <code class="docutils literal"><span class="pre">T</span></code> but before
the end of the full-expression, the computation history depends
on that value.</li>
</ul>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p>The intent of the second rule is to say that objects held in normal
<code class="docutils literal"><span class="pre">__strong</span></code> local variables may be released as soon as the value in
the variable is no longer being used: either the variable stops
being used completely or a new value is stored in the variable.</p>
<p class="last">The intent of the third rule is to say that return values may be
released after they’ve been used.</p>
</div>
<p>A computation history depends on a pointer value <code class="docutils literal"><span class="pre">P</span></code> if it:</p>
<ul class="simple">
<li>performs a pointer comparison with <code class="docutils literal"><span class="pre">P</span></code>,</li>
<li>loads from <code class="docutils literal"><span class="pre">P</span></code>,</li>
<li>stores to <code class="docutils literal"><span class="pre">P</span></code>,</li>
<li>depends on a pointer value <code class="docutils literal"><span class="pre">Q</span></code> derived via pointer arithmetic
from <code class="docutils literal"><span class="pre">P</span></code> (including an instance-variable or field access), or</li>
<li>depends on a pointer value <code class="docutils literal"><span class="pre">Q</span></code> loaded from <code class="docutils literal"><span class="pre">P</span></code>.</li>
</ul>
<p>Dependency applies only to values derived directly or indirectly from
a particular expression result and does not occur merely because a
separate pointer value dynamically aliases <code class="docutils literal"><span class="pre">P</span></code>. Furthermore, this
dependency is not carried by values that are stored to objects.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p>The restrictions on dependency are intended to make this analysis
feasible by an optimizer with only incomplete information about a
program. Essentially, dependence is carried to “obvious” uses of a
pointer. Merely passing a pointer argument to a function does not
itself cause dependence, but since generally the optimizer will not
be able to prove that the function doesn’t depend on that parameter,
it will be forced to conservatively assume it does.</p>
<p>Dependency propagates to values loaded from a pointer because those
values might be invalidated by deallocating the object. For
example, given the code <code class="docutils literal"><span class="pre">__strong</span> <span class="pre">id</span> <span class="pre">x</span> <span class="pre">=</span> <span class="pre">p->ivar;</span></code>, ARC must not
move the release of <code class="docutils literal"><span class="pre">p</span></code> to between the load of <code class="docutils literal"><span class="pre">p->ivar</span></code> and the
retain of that value for storing into <code class="docutils literal"><span class="pre">x</span></code>.</p>
<p>Dependency does not propagate through stores of dependent pointer
values because doing so would allow dependency to outlive the
full-expression which produced the original value. For example, the
address of an instance variable could be written to some global
location and then freely accessed during the lifetime of the local,
or a function could return an inner pointer of an object and store
it to a local. These cases would be potentially impossible to
reason about and so would basically prevent any optimizations based
on imprecise lifetime. There are also uncommon enough to make it
reasonable to require the precise-lifetime annotation if someone
really wants to rely on them.</p>
<p class="last">Dependency does propagate through return values of pointer type.
The compelling source of need for this rule is a property accessor
which returns an un-autoreleased result; the calling function must
have the chance to operate on the value, e.g. to retain it, before
ARC releases the original pointer. Note again, however, that
dependence does not survive a store, so ARC does not guarantee the
continued validity of the return value past the end of the
full-expression.</p>
</div>
</div>
<div class="section" id="no-object-lifetime-extension">
<span id="arc-optimization-object-lifetime"></span><h3><a class="toc-backref" href="#id41">No object lifetime extension</a><a class="headerlink" href="#no-object-lifetime-extension" title="Permalink to this headline">¶</a></h3>
<p>If, in the formal computation history of the program, an object <code class="docutils literal"><span class="pre">X</span></code>
has been deallocated by the time of an observable side-effect, then
ARC must cause <code class="docutils literal"><span class="pre">X</span></code> to be deallocated by no later than the occurrence
of that side-effect, except as influenced by the re-ordering of the
destruction of objects.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p>This rule is intended to prohibit ARC from observably extending the
lifetime of a retainable object, other than as specified in this
document. Together with the rule limiting the transformation of
releases, this rule requires ARC to eliminate retains and release
only in pairs.</p>
<p class="last">ARC’s power to reorder the destruction of objects is critical to its
ability to do any optimization, for essentially the same reason that
it must retain the power to decrease the lifetime of an object.
Unfortunately, while it’s generally poor style for the destruction
of objects to have arbitrary side-effects, it’s certainly possible.
Hence the caveat.</p>
</div>
</div>
<div class="section" id="precise-lifetime-semantics">
<span id="arc-optimization-precise"></span><h3><a class="toc-backref" href="#id42">Precise lifetime semantics</a><a class="headerlink" href="#precise-lifetime-semantics" title="Permalink to this headline">¶</a></h3>
<p>In general, ARC maintains an invariant that a retainable object pointer held in
a <code class="docutils literal"><span class="pre">__strong</span></code> object will be retained for the full formal lifetime of the
object. Objects subject to this invariant have <span class="arc-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="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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 <code class="docutils literal"><span class="pre">objc_precise_lifetime</span></code> attribute to indicate that
it should be considered to be an object with precise lifetime semantics.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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>
</div>
<div class="section" id="miscellaneous">
<span id="arc-misc"></span><h2><a class="toc-backref" href="#id43">Miscellaneous</a><a class="headerlink" href="#miscellaneous" title="Permalink to this headline">¶</a></h2>
<div class="section" id="special-methods">
<span id="arc-misc-special-methods"></span><h3><a class="toc-backref" href="#id44">Special methods</a><a class="headerlink" href="#special-methods" title="Permalink to this headline">¶</a></h3>
<div class="section" id="memory-management-methods">
<span id="arc-misc-special-methods-retain"></span><h4><a class="toc-backref" href="#id45">Memory management methods</a><a class="headerlink" href="#memory-management-methods" title="Permalink to this headline">¶</a></h4>
<p>A program is ill-formed if it contains a method definition, message send, or
<code class="docutils literal"><span class="pre">@selector</span></code> expression for any of the following selectors:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">autorelease</span></code></li>
<li><code class="docutils literal"><span class="pre">release</span></code></li>
<li><code class="docutils literal"><span class="pre">retain</span></code></li>
<li><code class="docutils literal"><span class="pre">retainCount</span></code></li>
</ul>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p><code class="docutils literal"><span class="pre">retainCount</span></code> 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><strong>Honoring</strong> 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 “unrooted” retains, i.e. retains not logically
corresponding to a strong reference in the object graph.</p>
<p><strong>Ignoring</strong> 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><strong>Banning</strong> 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 class="last">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 class="reference internal" href="#arc-objects-retains"><span class="std std-ref">semantics</span></a> laid out elsewhere in this document.</p>
</div>
</div>
<div class="section" id="dealloc">
<span id="arc-misc-special-methods-dealloc"></span><h4><a class="toc-backref" href="#id46"><code class="docutils literal"><span class="pre">dealloc</span></code></a><a class="headerlink" href="#dealloc" title="Permalink to this headline">¶</a></h4>
<p>A program is ill-formed if it contains a message send or <code class="docutils literal"><span class="pre">@selector</span></code>
expression for the selector <code class="docutils literal"><span class="pre">dealloc</span></code>.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">There are no legitimate reasons to call <code class="docutils literal"><span class="pre">dealloc</span></code> directly.</p>
</div>
<p>A class may provide a method definition for an instance method named
<code class="docutils literal"><span class="pre">dealloc</span></code>. This method will be called after the final <code class="docutils literal"><span class="pre">release</span></code> of the
object but before it is deallocated or any of its instance variables are
destroyed. The superclass’s implementation of <code class="docutils literal"><span class="pre">dealloc</span></code> will be called
automatically when the method returns.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">Even though ARC destroys instance variables automatically, there are still
legitimate reasons to write a <code class="docutils literal"><span class="pre">dealloc</span></code> method, such as freeing
non-retainable resources. Failing to call <code class="docutils literal"><span class="pre">[super</span> <span class="pre">dealloc]</span></code> in such a
method is nearly always a bug. Sometimes, the object is simply trying to
prevent itself from being destroyed, but <code class="docutils literal"><span class="pre">dealloc</span></code> 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
<code class="docutils literal"><span class="pre">free</span></code>; for now, this can only be supported with a <code class="docutils literal"><span class="pre">dealloc</span></code>
implementation outside of ARC. Such an implementation must be very careful
to do all the other work that <code class="docutils literal"><span class="pre">NSObject</span></code>‘s <code class="docutils literal"><span class="pre">dealloc</span></code> would, which is
outside the scope of this document to describe.</p>
</div>
<p>The instance variables for an ARC-compiled class will be destroyed at some
point after control enters the <code class="docutils literal"><span class="pre">dealloc</span></code> method for the root class of the
class. The ordering of the destruction of instance variables is unspecified,
both within a single class and between subclasses and superclasses.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p>The traditional, non-ARC pattern for destroying instance variables is to
destroy them immediately before calling <code class="docutils literal"><span class="pre">[super</span> <span class="pre">dealloc]</span></code>. Unfortunately,
message sends from the superclass are quite capable of reaching methods in
the subclass, and those methods may well read or write to those instance
variables. Making such message sends from dealloc is generally discouraged,
since the subclass may well rely on other invariants that were broken during
<code class="docutils literal"><span class="pre">dealloc</span></code>, but it’s not so inescapably dangerous that we felt comfortable
calling it undefined behavior. Therefore we chose to delay destroying the
instance variables to a point at which message sends are clearly disallowed:
the point at which the root class’s deallocation routines take over.</p>
<p class="last">In most code, the difference is not observable. It can, however, be observed
if an instance variable holds a strong reference to an object whose
deallocation will trigger a side-effect which must be carefully ordered with
respect to the destruction of the super class. Such code violates the design
principle that semantically important behavior should be explicit. A simple
fix is to clear the instance variable manually during <code class="docutils literal"><span class="pre">dealloc</span></code>; a more
holistic solution is to move semantically important side-effects out of
<code class="docutils literal"><span class="pre">dealloc</span></code> and into a separate teardown phase which can rely on working with
well-formed objects.</p>
</div>
</div>
</div>
<div class="section" id="autoreleasepool">
<span id="arc-misc-autoreleasepool"></span><h3><a class="toc-backref" href="#id47"><code class="docutils literal"><span class="pre">@autoreleasepool</span></code></a><a class="headerlink" href="#autoreleasepool" title="Permalink to this headline">¶</a></h3>
<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 <code class="docutils literal"><span class="pre">@autoreleasepool</span></code> followed by a <em>compound-statement</em>, 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 <code class="docutils literal"><span class="pre">return</span></code> or
<code class="docutils literal"><span class="pre">break</span></code>), 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><code class="docutils literal"><span class="pre">@autoreleasepool</span></code> may be used in non-ARC translation units, with equivalent
semantics.</p>
<p>A program is ill-formed if it refers to the <code class="docutils literal"><span class="pre">NSAutoreleasePool</span></code> class.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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>
<div class="section" id="self">
<span id="arc-misc-self"></span><h3><a class="toc-backref" href="#id48"><code class="docutils literal"><span class="pre">self</span></code></a><a class="headerlink" href="#self" title="Permalink to this headline">¶</a></h3>
<p>The <code class="docutils literal"><span class="pre">self</span></code> 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 <code class="docutils literal"><span class="pre">self</span></code> is implicitly
<code class="docutils literal"><span class="pre">const</span></code> unless the method is in the <a class="reference internal" href="#arc-family-semantics-init"><span class="std std-ref">init family</span></a>. Further, <code class="docutils literal"><span class="pre">self</span></code> is <strong>always</strong> implicitly
<code class="docutils literal"><span class="pre">const</span></code> within a class method.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">The cost of retaining <code class="docutils literal"><span class="pre">self</span></code> 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 — 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 <code class="docutils literal"><span class="pre">__unsafe_unretained</span></code>), we
chose to make this optimizing assumption and shift some amount of risk to the
user.</p>
</div>
</div>
<div class="section" id="fast-enumeration-iteration-variables">
<span id="arc-misc-enumeration"></span><h3><a class="toc-backref" href="#id49">Fast enumeration iteration variables</a><a class="headerlink" href="#fast-enumeration-iteration-variables" title="Permalink to this headline">¶</a></h3>
<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 <code class="docutils literal"><span class="pre">const</span> <span class="pre">__strong</span></code> and objects encountered during the
enumeration are not actually retained.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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 <code class="docutils literal"><span class="pre">__strong</span></code>, which will make the variable
mutable again and cause the loop to retain the objects it encounters.</p>
</div>
</div>
<div class="section" id="blocks">
<span id="arc-misc-blocks"></span><h3><a class="toc-backref" href="#id50">Blocks</a><a class="headerlink" href="#blocks" title="Permalink to this headline">¶</a></h3>
<p>The implicit <code class="docutils literal"><span class="pre">const</span></code> 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 class="reference internal" href="#arc-ownership-inference"><span class="std std-ref">inference</span></a> rules apply equally to
<code class="docutils literal"><span class="pre">__block</span></code> variables, which is a shift in semantics from non-ARC, where
<code class="docutils literal"><span class="pre">__block</span></code> variables did not implicitly retain during capture.</p>
<p><code class="docutils literal"><span class="pre">__block</span></code> 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 <code class="docutils literal"><span class="pre">__strong</span></code>
parameter variable or reading a <code class="docutils literal"><span class="pre">__weak</span></code> variable, whenever these semantics
call for retaining a value of block-pointer type, it has the effect of a
<code class="docutils literal"><span class="pre">Block_copy</span></code>. The optimizer may remove such copies when it sees that the
result is used only as an argument to a call.</p>
</div>
<div class="section" id="exceptions">
<span id="arc-misc-exceptions"></span><h3><a class="toc-backref" href="#id51">Exceptions</a><a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h3>
<p>By default in Objective C, ARC is not exception-safe for normal releases:</p>
<ul class="simple">
<li>It does not end the lifetime of <code class="docutils literal"><span class="pre">__strong</span></code> 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 <code class="docutils literal"><span class="pre">-fobjc-arc-exceptions</span></code> in order to
enable these, or with the option <code class="docutils literal"><span class="pre">-fno-objc-arc-exceptions</span></code> to explicitly
disable them, with the last such argument “winning”.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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++, <code class="docutils literal"><span class="pre">-fobjc-arc-exceptions</span></code> is enabled by default.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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 <code class="docutils literal"><span class="pre">__weak</span></code> objects when an exception terminates
their scope unless exceptions are disabled in the compiler.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">The consequence of a local <code class="docutils literal"><span class="pre">__weak</span></code> 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>
<div class="section" id="interior-pointers">
<span id="arc-misc-interior"></span><h3><a class="toc-backref" href="#id52">Interior pointers</a><a class="headerlink" href="#interior-pointers" title="Permalink to this headline">¶</a></h3>
<p>An Objective-C method returning a non-retainable pointer may be annotated with
the <code class="docutils literal"><span class="pre">objc_returns_inner_pointer</span></code> 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 class="simple">
<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="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<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 “interior” pointers, its optimizations can
cause the owning object to be reclaimed too soon. This attribute informs ARC
that it must tread lightly.</p>
<p class="last">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 “derived from” 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 <code class="docutils literal"><span class="pre">strchr</span></code>). 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 <code class="docutils literal"><span class="pre">__strong</span></code> object with <a class="reference internal" href="#arc-optimization-precise"><span class="std std-ref">precise lifetime semantics</span></a>.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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>
<div class="section" id="c-retainable-pointer-types">
<span id="arc-misc-c-retainable"></span><h3><a class="toc-backref" href="#id53">C retainable pointer types</a><a class="headerlink" href="#c-retainable-pointer-types" title="Permalink to this headline">¶</a></h3>
<p>A type is a <span class="arc-term">C retainable pointer type</span> if it is a pointer to
(possibly qualified) <code class="docutils literal"><span class="pre">void</span></code> or a pointer to a (possibly qualifier) <code class="docutils literal"><span class="pre">struct</span></code>
or <code class="docutils literal"><span class="pre">class</span></code> type.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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 class="section" id="auditing-of-c-retainable-pointer-interfaces">
<span id="arc-misc-c-retainable-audit"></span><h4><a class="toc-backref" href="#id54">Auditing of C retainable pointer interfaces</a><a class="headerlink" href="#auditing-of-c-retainable-pointer-interfaces" title="Permalink to this headline">¶</a></h4>
<p><span class="when-revised">[beginning Apple 4.0, LLVM 3.1]</span></p>
<p>A C function may be marked with the <code class="docutils literal"><span class="pre">cf_audited_transfer</span></code> 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 class="simple">
<li>A parameter of C retainable pointer type is assumed to not be consumed
unless it is marked with the <code class="docutils literal"><span class="pre">cf_consumed</span></code> attribute, and</li>
<li>A result of C retainable pointer type is assumed to not be returned retained
unless the function is either marked <code class="docutils literal"><span class="pre">cf_returns_retained</span></code> or it follows
the create/copy naming convention and is not marked
<code class="docutils literal"><span class="pre">cf_returns_not_retained</span></code>.</li>
</ul>
<p>A function obeys the <span class="arc-term">create/copy</span> naming convention if its name
contains as a substring:</p>
<ul class="simple">
<li>either “Create” or “Copy” not followed by a lowercase letter, or</li>
<li>either “create” or “copy” not followed by a lowercase letter and
not preceded by any letter, whether uppercase or lowercase.</li>
</ul>
<p>A second attribute, <code class="docutils literal"><span class="pre">cf_unknown_transfer</span></code>, 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 <code class="docutils literal"><span class="pre">cf_audited_transfer</span></code> and <code class="docutils literal"><span class="pre">cf_unknown_transfer</span></code>.</p>
<p>A pragma is provided to facilitate the mass annotation of interfaces:</p>
<div class="highlight-objc"><div class="highlight"><pre><span></span><span class="cp">#pragma clang arc_cf_code_audited begin</span>
<span class="p">...</span>
<span class="cp">#pragma clang arc_cf_code_audited end</span>
</pre></div>
</div>
<p>All C functions declared within the extent of this pragma are treated as if
annotated with the <code class="docutils literal"><span class="pre">cf_audited_transfer</span></code> attribute unless they otherwise have
the <code class="docutils literal"><span class="pre">cf_unknown_transfer</span></code> 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
<code class="docutils literal"><span class="pre">__has_feature(arc_cf_code_audited)</span></code>.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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>
</div>
</div>
<div class="section" id="runtime-support">
<span id="arc-runtime"></span><h2><a class="toc-backref" href="#id55">Runtime support</a><a class="headerlink" href="#runtime-support" title="Permalink to this headline">¶</a></h2>
<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 “Itanium” generic ABI for C++.</p>
<p>Ownership qualification does not alter the storage requirements for objects,
except that it is undefined behavior if a <code class="docutils literal"><span class="pre">__weak</span></code> object is inadequately
aligned for an object of type <code class="docutils literal"><span class="pre">id</span></code>. The other qualifiers may be used on
explicitly under-aligned memory.</p>
<p>The runtime tracks <code class="docutils literal"><span class="pre">__weak</span></code> objects which holds non-null values. It is
undefined behavior to direct modify a <code class="docutils literal"><span class="pre">__weak</span></code> object which is being tracked
by the runtime except through an
<a class="reference internal" href="#arc-runtime-objc-storeweak"><span class="std std-ref">objc_storeWeak</span></a>,
<a class="reference internal" href="#arc-runtime-objc-destroyweak"><span class="std std-ref">objc_destroyWeak</span></a>, or
<a class="reference internal" href="#arc-runtime-objc-moveweak"><span class="std std-ref">objc_moveWeak</span></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="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p>Several of these functions are semantically equivalent to a message send; we
emit calls to C functions instead because:</p>
<ul class="simple">
<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 class="last">Several other of these functions are “fused” 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 class="section" id="arc-runtime-objc-autorelease">
<span id="id-objc-autorelease-id-value"></span><h3><a class="toc-backref" href="#id56"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_autorelease(id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#arc-runtime-objc-autorelease" title="Permalink to this headline">¶</a></h3>
<p><em>Precondition:</em> <code class="docutils literal"><span class="pre">value</span></code> is null or a pointer to a valid object.</p>
<p>If <code class="docutils literal"><span class="pre">value</span></code> 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
<code class="docutils literal"><span class="pre">autorelease</span></code> message.</p>
<p>Always returns <code class="docutils literal"><span class="pre">value</span></code>.</p>
</div>
<div class="section" id="void-objc-autoreleasepoolpop-void-pool">
<span id="arc-runtime-objc-autoreleasepoolpop"></span><h3><a class="toc-backref" href="#id57"><code class="docutils literal"><span class="pre">void</span> <span class="pre">objc_autoreleasePoolPop(void</span> <span class="pre">*pool);</span></code></a><a class="headerlink" href="#void-objc-autoreleasepoolpop-void-pool" title="Permalink to this headline">¶</a></h3>
<p><em>Precondition:</em> <code class="docutils literal"><span class="pre">pool</span></code> is the result of a previous call to
<a class="reference internal" href="#arc-runtime-objc-autoreleasepoolpush"><span class="std std-ref">objc_autoreleasePoolPush</span></a> on the
current thread, where neither <code class="docutils literal"><span class="pre">pool</span></code> 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 <code class="docutils literal"><span class="pre">pool</span></code>.</p>
</div>
<div class="section" id="void-objc-autoreleasepoolpush-void">
<span id="arc-runtime-objc-autoreleasepoolpush"></span><h3><a class="toc-backref" href="#id58"><code class="docutils literal"><span class="pre">void</span> <span class="pre">*objc_autoreleasePoolPush(void);</span></code></a><a class="headerlink" href="#void-objc-autoreleasepoolpush-void" title="Permalink to this headline">¶</a></h3>
<p>Creates a new autorelease pool that is enclosed by the current pool, makes that
the current pool, and returns an opaque “handle” to it.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">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>
<div class="section" id="arc-runtime-objc-autoreleasereturnvalue">
<span id="id-objc-autoreleasereturnvalue-id-value"></span><h3><a class="toc-backref" href="#id59"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_autoreleaseReturnValue(id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#arc-runtime-objc-autoreleasereturnvalue" title="Permalink to this headline">¶</a></h3>
<p><em>Precondition:</em> <code class="docutils literal"><span class="pre">value</span></code> is null or a pointer to a valid object.</p>
<p>If <code class="docutils literal"><span class="pre">value</span></code> 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 class="reference internal" href="#arc-runtime-objc-retainautoreleasedreturnvalue"><span class="std std-ref">objc_retainAutoreleasedReturnValue</span></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 <code class="docutils literal"><span class="pre">value</span></code>.</p>
</div>
<div class="section" id="void-objc-copyweak-id-dest-id-src">
<span id="arc-runtime-objc-copyweak"></span><h3><a class="toc-backref" href="#id60"><code class="docutils literal"><span class="pre">void</span> <span class="pre">objc_copyWeak(id</span> <span class="pre">*dest,</span> <span class="pre">id</span> <span class="pre">*src);</span></code></a><a class="headerlink" href="#void-objc-copyweak-id-dest-id-src" title="Permalink to this headline">¶</a></h3>
<p><em>Precondition:</em> <code class="docutils literal"><span class="pre">src</span></code> is a valid pointer which either contains a null pointer
or has been registered as a <code class="docutils literal"><span class="pre">__weak</span></code> object. <code class="docutils literal"><span class="pre">dest</span></code> is a valid pointer
which has not been registered as a <code class="docutils literal"><span class="pre">__weak</span></code> object.</p>
<p><code class="docutils literal"><span class="pre">dest</span></code> is initialized to be equivalent to <code class="docutils literal"><span class="pre">src</span></code>, potentially registering it
with the runtime. Equivalent to the following code:</p>
<div class="highlight-objc"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">objc_copyWeak</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">dest</span><span class="p">,</span> <span class="kt">id</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
<span class="n">objc_release</span><span class="p">(</span><span class="n">objc_initWeak</span><span class="p">(</span><span class="n">dest</span><span class="p">,</span> <span class="n">objc_loadWeakRetained</span><span class="p">(</span><span class="n">src</span><span class="p">)));</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Must be atomic with respect to calls to <code class="docutils literal"><span class="pre">objc_storeWeak</span></code> on <code class="docutils literal"><span class="pre">src</span></code>.</p>
</div>
<div class="section" id="void-objc-destroyweak-id-object">
<span id="arc-runtime-objc-destroyweak"></span><h3><a class="toc-backref" href="#id61"><code class="docutils literal"><span class="pre">void</span> <span class="pre">objc_destroyWeak(id</span> <span class="pre">*object);</span></code></a><a class="headerlink" href="#void-objc-destroyweak-id-object" title="Permalink to this headline">¶</a></h3>
<p><em>Precondition:</em> <code class="docutils literal"><span class="pre">object</span></code> is a valid pointer which either contains a null
pointer or has been registered as a <code class="docutils literal"><span class="pre">__weak</span></code> object.</p>
<p><code class="docutils literal"><span class="pre">object</span></code> is unregistered as a weak object, if it ever was. The current value
of <code class="docutils literal"><span class="pre">object</span></code> is left unspecified; otherwise, equivalent to the following code:</p>
<div class="highlight-objc"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">objc_destroyWeak</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">object</span><span class="p">)</span> <span class="p">{</span>
<span class="n">objc_storeWeak</span><span class="p">(</span><span class="n">object</span><span class="p">,</span> <span class="nb">nil</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Does not need to be atomic with respect to calls to <code class="docutils literal"><span class="pre">objc_storeWeak</span></code> on
<code class="docutils literal"><span class="pre">object</span></code>.</p>
</div>
<div class="section" id="arc-runtime-objc-initweak">
<span id="id-objc-initweak-id-object-id-value"></span><h3><a class="toc-backref" href="#id62"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_initWeak(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#arc-runtime-objc-initweak" title="Permalink to this headline">¶</a></h3>
<p><em>Precondition:</em> <code class="docutils literal"><span class="pre">object</span></code> is a valid pointer which has not been registered as
a <code class="docutils literal"><span class="pre">__weak</span></code> object. <code class="docutils literal"><span class="pre">value</span></code> is null or a pointer to a valid object.</p>
<p>If <code class="docutils literal"><span class="pre">value</span></code> is a null pointer or the object to which it points has begun
deallocation, <code class="docutils literal"><span class="pre">object</span></code> is zero-initialized. Otherwise, <code class="docutils literal"><span class="pre">object</span></code> is
registered as a <code class="docutils literal"><span class="pre">__weak</span></code> object pointing to <code class="docutils literal"><span class="pre">value</span></code>. Equivalent to the
following code:</p>
<div class="highlight-objc"><div class="highlight"><pre><span></span><span class="kt">id</span> <span class="nf">objc_initWeak</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">object</span><span class="p">,</span> <span class="kt">id</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
<span class="o">*</span><span class="n">object</span> <span class="o">=</span> <span class="nb">nil</span><span class="p">;</span>
<span class="k">return</span> <span class="n">objc_storeWeak</span><span class="p">(</span><span class="n">object</span><span class="p">,</span> <span class="n">value</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Returns the value of <code class="docutils literal"><span class="pre">object</span></code> after the call.</p>
<p>Does not need to be atomic with respect to calls to <code class="docutils literal"><span class="pre">objc_storeWeak</span></code> on
<code class="docutils literal"><span class="pre">object</span></code>.</p>
</div>
<div class="section" id="arc-runtime-objc-loadweak">
<span id="id-objc-loadweak-id-object"></span><h3><a class="toc-backref" href="#id63"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_loadWeak(id</span> <span class="pre">*object);</span></code></a><a class="headerlink" href="#arc-runtime-objc-loadweak" title="Permalink to this headline">¶</a></h3>
<p><em>Precondition:</em> <code class="docutils literal"><span class="pre">object</span></code> is a valid pointer which either contains a null
pointer or has been registered as a <code class="docutils literal"><span class="pre">__weak</span></code> object.</p>
<p>If <code class="docutils literal"><span class="pre">object</span></code> is registered as a <code class="docutils literal"><span class="pre">__weak</span></code> object, and the last value stored
into <code class="docutils literal"><span class="pre">object</span></code> 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>
<div class="highlight-objc"><div class="highlight"><pre><span></span><span class="kt">id</span> <span class="nf">objc_loadWeak</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">object</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">objc_autorelease</span><span class="p">(</span><span class="n">objc_loadWeakRetained</span><span class="p">(</span><span class="n">object</span><span class="p">));</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Must be atomic with respect to calls to <code class="docutils literal"><span class="pre">objc_storeWeak</span></code> on <code class="docutils literal"><span class="pre">object</span></code>.</p>
<div class="admonition-rationale admonition">
<p class="first admonition-title">Rationale</p>
<p class="last">Loading weak references would be inherently prone to race conditions without
the retain.</p>
</div>
</div>
<div class="section" id="arc-runtime-objc-loadweakretained">
<span id="id-objc-loadweakretained-id-object"></span><h3><a class="toc-backref" href="#id64"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_loadWeakRetained(id</span> <span class="pre">*object);</span></code></a><a class="headerlink" href="#arc-runtime-objc-loadweakretained" title="Permalink to this headline">¶</a></h3>
<p><em>Precondition:</em> <code class="docutils literal"><span class="pre">object</span></code> is a valid pointer which either contains a null
pointer or has been registered as a <code class="docutils literal"><span class="pre">__weak</span></code> object.</p>
<p>If <code class="docutils literal"><span class="pre">object</span></code> is registered as a <code class="docutils literal"><span class="pre">__weak</span></code> object, and the last value stored
into <code class="docutils literal"><span class="pre">object</span></code> 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 <code class="docutils literal"><span class="pre">objc_storeWeak</span></code> on <code class="docutils literal"><span class="pre">object</span></code>.</p>
</div>
<div class="section" id="void-objc-moveweak-id-dest-id-src">
<span id="arc-runtime-objc-moveweak"></span><h3><a class="toc-backref" href="#id65"><code class="docutils literal"><span class="pre">void</span> <span class="pre">objc_moveWeak(id</span> <span class="pre">*dest,</span> <span class="pre">id</span> <span class="pre">*src);</span></code></a><a class="headerlink" href="#void-objc-moveweak-id-dest-id-src" title="Permalink to this headline">¶</a></h3>
<p><em>Precondition:</em> <code class="docutils literal"><span class="pre">src</span></code> is a valid pointer which either contains a null pointer
or has been registered as a <code class="docutils literal"><span class="pre">__weak</span></code> object. <code class="docutils literal"><span class="pre">dest</span></code> is a valid pointer
which has not been registered as a <code class="docutils literal"><span class="pre">__weak</span></code> object.</p>
<p><code class="docutils literal"><span class="pre">dest</span></code> is initialized to be equivalent to <code class="docutils literal"><span class="pre">src</span></code>, potentially registering it
with the runtime. <code class="docutils literal"><span class="pre">src</span></code> may then be left in its original state, in which
case this call is equivalent to <a class="reference internal" href="#arc-runtime-objc-copyweak"><span class="std std-ref">objc_copyWeak</span></a>, or it may be left as null.</p>
<p>Must be atomic with respect to calls to <code class="docutils literal"><span class="pre">objc_storeWeak</span></code> on <code class="docutils literal"><span class="pre">src</span></code>.</p>
</div>
<div class="section" id="void-objc-release-id-value">
<span id="arc-runtime-objc-release"></span><h3><a class="toc-backref" href="#id66"><code class="docutils literal"><span class="pre">void</span> <span class="pre">objc_release(id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#void-objc-release-id-value" title="Permalink to this headline">¶</a></h3>
<p><em>Precondition:</em> <code class="docutils literal"><span class="pre">value</span></code> is null or a pointer to a valid object.</p>
<p>If <code class="docutils literal"><span class="pre">value</span></code> is null, this call has no effect. Otherwise, it performs a
release operation exactly as if the object had been sent the <code class="docutils literal"><span class="pre">release</span></code>
message.</p>
</div>
<div class="section" id="arc-runtime-objc-retain">
<span id="id-objc-retain-id-value"></span><h3><a class="toc-backref" href="#id67"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retain(id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#arc-runtime-objc-retain" title="Permalink to this headline">¶</a></h3>
<p><em>Precondition:</em> <code class="docutils literal"><span class="pre">value</span></code> is null or a pointer to a valid object.</p>
<p>If <code class="docutils literal"><span class="pre">value</span></code> is null, this call has no effect. Otherwise, it performs a retain
operation exactly as if the object had been sent the <code class="docutils literal"><span class="pre">retain</span></code> message.</p>
<p>Always returns <code class="docutils literal"><span class="pre">value</span></code>.</p>
</div>
<div class="section" id="arc-runtime-objc-retainautorelease">
<span id="id-objc-retainautorelease-id-value"></span><h3><a class="toc-backref" href="#id68"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutorelease(id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#arc-runtime-objc-retainautorelease" title="Permalink to this headline">¶</a></h3>
<p><em>Precondition:</em> <code class="docutils literal"><span class="pre">value</span></code> is null or a pointer to a valid object.</p>
<p>If <code class="docutils literal"><span class="pre">value</span></code> is null, this call has no effect. Otherwise, it performs a retain
operation followed by an autorelease operation. Equivalent to the following
code:</p>
<div class="highlight-objc"><div class="highlight"><pre><span></span><span class="kt">id</span> <span class="nf">objc_retainAutorelease</span><span class="p">(</span><span class="kt">id</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">objc_autorelease</span><span class="p">(</span><span class="n">objc_retain</span><span class="p">(</span><span class="n">value</span><span class="p">));</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Always returns <code class="docutils literal"><span class="pre">value</span></code>.</p>
</div>
<div class="section" id="arc-runtime-objc-retainautoreleasereturnvalue">
<span id="id-objc-retainautoreleasereturnvalue-id-value"></span><h3><a class="toc-backref" href="#id69"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutoreleaseReturnValue(id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#arc-runtime-objc-retainautoreleasereturnvalue" title="Permalink to this headline">¶</a></h3>
<p><em>Precondition:</em> <code class="docutils literal"><span class="pre">value</span></code> is null or a pointer to a valid object.</p>
<p>If <code class="docutils literal"><span class="pre">value</span></code> is null, this call has no effect. Otherwise, it performs a retain
operation followed by the operation described in
<a class="reference internal" href="#arc-runtime-objc-autoreleasereturnvalue"><span class="std std-ref">objc_autoreleaseReturnValue</span></a>.
Equivalent to the following code:</p>
<div class="highlight-objc"><div class="highlight"><pre><span></span><span class="kt">id</span> <span class="nf">objc_retainAutoreleaseReturnValue</span><span class="p">(</span><span class="kt">id</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">objc_autoreleaseReturnValue</span><span class="p">(</span><span class="n">objc_retain</span><span class="p">(</span><span class="n">value</span><span class="p">));</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Always returns <code class="docutils literal"><span class="pre">value</span></code>.</p>
</div>
<div class="section" id="arc-runtime-objc-retainautoreleasedreturnvalue">
<span id="id-objc-retainautoreleasedreturnvalue-id-value"></span><h3><a class="toc-backref" href="#id70"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutoreleasedReturnValue(id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#arc-runtime-objc-retainautoreleasedreturnvalue" title="Permalink to this headline">¶</a></h3>
<p><em>Precondition:</em> <code class="docutils literal"><span class="pre">value</span></code> is null or a pointer to a valid object.</p>
<p>If <code class="docutils literal"><span class="pre">value</span></code> is null, this call has no effect. Otherwise, it attempts to
accept a hand off of a retain count from a call to
<a class="reference internal" href="#arc-runtime-objc-autoreleasereturnvalue"><span class="std std-ref">objc_autoreleaseReturnValue</span></a> on
<code class="docutils literal"><span class="pre">value</span></code> in a recently-called function or something it calls. If that fails,
it performs a retain operation exactly like <a class="reference internal" href="#arc-runtime-objc-retain"><span class="std std-ref">objc_retain</span></a>.</p>
<p>Always returns <code class="docutils literal"><span class="pre">value</span></code>.</p>
</div>
<div class="section" id="arc-runtime-objc-retainblock">
<span id="id-objc-retainblock-id-value"></span><h3><a class="toc-backref" href="#id71"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainBlock(id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#arc-runtime-objc-retainblock" title="Permalink to this headline">¶</a></h3>
<p><em>Precondition:</em> <code class="docutils literal"><span class="pre">value</span></code> is null or a pointer to a valid block object.</p>
<p>If <code class="docutils literal"><span class="pre">value</span></code> is null, this call has no effect. Otherwise, if the block pointed
to by <code class="docutils literal"><span class="pre">value</span></code> 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 <code class="docutils literal"><span class="pre">retain</span></code> message.</p>
</div>
<div class="section" id="arc-runtime-objc-storestrong">
<span id="id-objc-storestrong-id-object-id-value"></span><h3><a class="toc-backref" href="#id72"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_storeStrong(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#arc-runtime-objc-storestrong" title="Permalink to this headline">¶</a></h3>
<p><em>Precondition:</em> <code class="docutils literal"><span class="pre">object</span></code> is a valid pointer to a <code class="docutils literal"><span class="pre">__strong</span></code> object which is
adequately aligned for a pointer. <code class="docutils literal"><span class="pre">value</span></code> is null or a pointer to a valid
object.</p>
<p>Performs the complete sequence for assigning to a <code class="docutils literal"><span class="pre">__strong</span></code> object of
non-block type <a class="footnote-reference" href="#id3" id="id2">[*]</a>. Equivalent to the following code:</p>
<div class="highlight-objc"><div class="highlight"><pre><span></span><span class="kt">id</span> <span class="nf">objc_storeStrong</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">object</span><span class="p">,</span> <span class="kt">id</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
<span class="n">value</span> <span class="o">=</span> <span class="p">[</span><span class="n">value</span> <span class="k">retain</span><span class="p">];</span>
<span class="kt">id</span> <span class="n">oldValue</span> <span class="o">=</span> <span class="o">*</span><span class="n">object</span><span class="p">;</span>
<span class="o">*</span><span class="n">object</span> <span class="o">=</span> <span class="n">value</span><span class="p">;</span>
<span class="p">[</span><span class="n">oldValue</span> <span class="k">release</span><span class="p">];</span>
<span class="k">return</span> <span class="n">value</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Always returns <code class="docutils literal"><span class="pre">value</span></code>.</p>
<table class="docutils footnote" frame="void" id="id3" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2">[*]</a></td><td>This does not imply that a <code class="docutils literal"><span class="pre">__strong</span></code> object of block type is an
invalid argument to this function. Rather it implies that an <code class="docutils literal"><span class="pre">objc_retain</span></code>
and not an <code class="docutils literal"><span class="pre">objc_retainBlock</span></code> operation will be emitted if the argument is
a block.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="arc-runtime-objc-storeweak">
<span id="id-objc-storeweak-id-object-id-value"></span><h3><a class="toc-backref" href="#id73"><code class="docutils literal"><span class="pre">id</span> <span class="pre">objc_storeWeak(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></code></a><a class="headerlink" href="#arc-runtime-objc-storeweak" title="Permalink to this headline">¶</a></h3>
<p><em>Precondition:</em> <code class="docutils literal"><span class="pre">object</span></code> is a valid pointer which either contains a null
pointer or has been registered as a <code class="docutils literal"><span class="pre">__weak</span></code> object. <code class="docutils literal"><span class="pre">value</span></code> is null or a
pointer to a valid object.</p>
<p>If <code class="docutils literal"><span class="pre">value</span></code> is a null pointer or the object to which it points has begun
deallocation, <code class="docutils literal"><span class="pre">object</span></code> is assigned null and unregistered as a <code class="docutils literal"><span class="pre">__weak</span></code>
object. Otherwise, <code class="docutils literal"><span class="pre">object</span></code> is registered as a <code class="docutils literal"><span class="pre">__weak</span></code> object or has its
registration updated to point to <code class="docutils literal"><span class="pre">value</span></code>.</p>
<p>Returns the value of <code class="docutils literal"><span class="pre">object</span></code> after the call.</p>
</div>
</div>
</div>
</div>
<div class="bottomnav" role="navigation" aria-label="bottom navigation">
<p>
«  <a href="Block-ABI-Apple.html">Block Implementation Specification</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="AttributeReference.html">Attributes in Clang</a>  »
</p>
</div>
<div class="footer" role="contentinfo">
© Copyright 2007-2017, The Clang Team.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.9.
</div>
</body>
</html>
|