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
//! 通过裸指针手动管理内存。
//!
//! *[See also the pointer primitive types](pointer).*
//!
//! # Safety
//!
//! 该模块中的许多函数都将裸指针作为参数,并对其进行读取或写入。为了安全起见,这些指针必须是 *valid*。
//! 指针是否有效取决于指针用于 (读或写) 的操作以及所访问的内存范围 (即 read/written 多少个字节)。
//! 大多数函数使用 `*mut T` 和 `*const T` 来访问单个值,在这种情况下,文档将忽略该大小,并隐式地假定其为 `size_of::<T>()` 字节。
//!
//! 有效性的确切规则尚未确定。此时提供的保证非常小:
//!
//! * [null] 指针从来都是无效的,甚至对于 [大小为零][zst] 的访问也是无效的。
//! * 为了使指针有效,有必要 (但并不总是足够) 使指针 *可引用*: 从指针开始的给定大小的内存范围必须全部在单个已分配对象的范围内。
//!
//! 请注意,在 Rust 中,每个 (stack-allocated) 变量都被视为一个单独的分配对象。
//! * 即使对于 [大小为零][zst] 的操作,指针也不得指向已释放的内存,即,即使对于大小为零的操作,释放也会使指针无效。
//! 但是,将任何非零整数 *字面量* 强制转换为指针对于零大小的访问都是有效的,即使该地址恰好存在一些内存并被释放了。
//! 这相当于编写自己的分配器:分配零大小的对象不是很困难。
//! 获得对零大小访问有效的指针的规范方法是 [`NonNull::dangling`]。
//!
//!
//!
//!
//!
//!
//!
//!
// FIXME: 上面提到 `ptr::invalid`,一旦它稳定了。
//! * 在用于在线程之间同步的 [原子操作][atomic operations] 的意义上,此模块中的函数执行的所有访问都是非原子的。这意味着从两个不同的线程对同一位置执行两次并发访问是一种未定义的行为,除非两个访问均仅从内存中读取。
//! 请注意,这明确包含 [`read_volatile`] 和 [`write_volatile`]: 易失性访问不能用于线程间同步。
//! * 只要底层对象处于活动状态,并且不使用引用 (仅仅是裸指针) 来访问同一内存,则转换对指针的引用的结果就是有效的。也就是说,引用和指针访问不能交错。
//!
//! 这些公理,以及仔细地使用 [`offset`] 进行指针运算,足以在不安全的代码中正确实现许多有用的东西。随着 [aliasing] 规则的确定,最终将提供更强有力的保证。有关更多信息,请参见 [书籍][book] 以及专门针对 [未定义的行为][ub] 的引用中的部分。
//!
//! ## Alignment
//!
//! 上面定义的有效裸指针不一定正确对齐 (其中 "proper" 对齐由 pointee 类型定义,即 `*const T` 必须与 `mem::align_of::<T>()` 对齐)。但是,大多数函数要求其参数正确对齐,并将在其文档中明确说明此要求。
//! [`read_unaligned`] 和 [`write_unaligned`] 除外。
//!
//! 当一个函数需要适当的对齐时,即使访问的大小为 0,即实际上没有触摸到内存,它也需要进行适当的对齐。在这种情况下,请考虑使用 [`NonNull::dangling`]。
//!
//! ## 分配对象
//!
//! 对于一些操作,例如 [`offset`] 或 projection (`expr.field`),"allocated object" 的概念变得相关。分配的对象是一个连续的内存区域。
//! 分配对象的常见示例包括栈分配变量 (每个变量都是一个单独的分配对象)、堆分配 (每个分配器创建的分配都是一个单独的分配对象) 和 `static` 变量。
//!
//! # Strict Provenance
//!
//! **以下文本是非规范性的,不够正式,并且是对 Provenance 的极其严格的解释。如果您的代码没有严格遵循它,那也没关系。**
//!
//! [Strict Provenance][] 是一组实验性 API,可帮助工具尝试验证程序执行的内存安全性。值得注意的是,这包括 [Miri][] 和 [CHERI][],它们可以检测您何时访问越界内存或以其他方式违反 Rust 的内存模型。
//!
//! 任何为现代计算机架构编译的编程语言都必须以某种形式存在 Provenance,但是以对编译器和程序员都有用的方式指定 Provenance 模型是一个持续的挑战。
//! [Strict Provenance][] 实验旨在探索这个问题: 如果我们只是说您不能做所有使 provenance 如此混乱的讨厌的操作,那会怎么样?
//!
//! 必须删除哪些 API? 必须添加哪些 API? 代码需要改变多少,现在是更糟还是更好? 任何模式都会变得真正无法表达吗?
//! 我们可以为这些模式开辟特殊的例外吗? 我们应该吗?
//!
//! 这个项目的第二个目标是看看我们是否可以消除指针 <-> 整数转换的许多函数的歧义,以便放宽 `usize` 的定义,使其不是 *pointer* 大小而是 address-space/offset/allocation-sized (我们可能会继续混淆这些概念)。
//! 这可能会更有效地定位指针大于偏移量的平台,例如 CHERI 和一些分段架构。
//!
//! ## Provenance
//!
//! **这部分是非规范性的,是 [Strict Provenance][] 实验的一部分。**
//!
//! 指针并不是简单的 "integer" 或 "address"。例如,可以毫无争议地说,释放后使用显然是未定义的行为,即使你运气好,并且释放的内存在读或写之前得到了重新分配 (事实上,这是最坏的情况,如果不发生这种情况,UAFs 也不会太担心!)。
//! 为了使这种说法合理化,指针需要以某种方式不仅仅是它们的地址:
//! 他们必须有 provenance。
//!
//! 创建分配时,该分配具有唯一的原始指针。对于 alloc API,这实际上是调用返回的指针,对于本地变量和静态变量,这是变量或静态的名称。为了简洁明了起见,这稍微过多地使用了 "pointer" 这个术语。
//!
//! 保证分配的原始指针对整个分配具有唯一的访问权限,并且只对该分配具有唯一的访问权。从这个意义上说,分配可以被认为是一个不能被打破的 "sandbox"。*Provenance* 是访问分配沙箱的权限,并具有 *spatial* 和 *temporal* 组件:
//!
//! * Spatial: 允许指针访问的字节范围。
//! * Temporal: 访问这些字节相关的 (分配的) 生命周期。
//!
//! Spatial provenance 确保您不会超出沙盒,而时间 provenance 确保您在访问某些内存的权限被撤销 (通过释放或借用到期) 后不能侥幸成功。
//!
//! 通过 [`offset`]、借用和指针转换等操作从原始指针传递派生的所有指针隐式共享 provenance。
//! 一些操作可能会收缩派生的 provenance,从而限制它可以访问多少内存或它的有效期有多长 (即借用一个子字段和子切片)。
//!
//! 收缩的 provenance 无法撤消: 即使您知道有一个更大的分配,你也不能派生一个具有更大起源的指针。同样,您不能 "recombine" 将两个连续的 provenances 重新合二为一 (即使用 `fn merge(&[T], &[T]) -> &[T]`).
//!
//! 对某个值的引用始终具有该字段占用的内存的确切来源。
//! 对切片的引用总是在切片描述的范围内 provenances。
//!
//! 如果一个分配被释放,所有指向该分配的指针都会失效,并且实际上失去了它们的出处。
//!
//! strict provenance 实验主要只对探索更严格的 *空间* provenance 感兴趣。从这个意义上说,它可以被认为是更雄心勃勃和正式的 [Stacked Borrows][] 研究项目的一个子集,这是 [Miri][] 等工具的基础。
//! 特别是,堆叠借用对于正确描述允许借用做什么以及何时失效是必要的。这必然涉及比简单地识别分配更复杂的*时间*推理。为 strict provenance 实验调整 API 和代码也将极大地帮助 Stacked 借用。
//!
//! ## 指针与地址
//!
//! **这部分是非规范性的,是 [Strict Provenance][] 实验的一部分。**
//!
//! 试图定义 provenance 的最大历史问题之一是程序员在指针和整数之间自由转换。一旦您允许这一点,通常就不可能准确地跟踪和保存 provenance 信息,您需要求助于非常复杂和不可靠的启发式方法。
//! 但是当然,指针和整数之间的转换是非常有用的,那么我们能做什么呢?
//!
//! 您还知道 WASM 实际上是 "Harvard Architecture" 吗? 正如函数指针与数据指针的处理方式完全不同? 而且我们只是在 WASM 上发布了 Rust 并没有真正解决我们让您在函数指针和数据指针之间自由转换的事实,因为它主要是 Just Works? 让我们把它放在 "指针强制转换是可疑的" 堆上。
//!
//!
//! Strict Provenance 试图通过解耦 Rust 的指针和 `usize` (和 `isize`) 的传统合并,并定义一个指向语义上包含以下信息的指针来解决这些问题:
//!
//! * **address-space** 它是它的一部分 (例如 "data" 与 WASM 中的 "code")。
//! * 它指向的 **地址**,可以用 `usize` 表示。
//! * 它拥有所有权的 **出处**,定义了它有权访问的内存。
//!
//! 在 Strict Provenance 下,usize *不能* 准确地表示指针,从指针转换为 usize 通常是 *only* 提取地址的操作。因此*不可能*从一个 usize 创建一个有效的指针,因为没有办法恢复地址空间和 provenance。
//! 换句话说,指针 - 整数 - 指针往返是不可能的 (在某种意义上,生成的指针是不可解引用的)。
//!
//! 使这个模型 *完全* 可行的关键见解是 [`with_addr`][] 方法:
//!
//! ```text
//! /// 使用给定地址创建一个新指针。
//! ///
//! /// 这执行与 `addr as ptr` 强制转换相同的操作,但将 `self` 的 *address-space* 和 *provenance* 复制到新指针。
//! /// 这使我们能够动态地保存和传播这些重要信息,而这在其他情况下使用一元强制转换是不可能的。
//! ///
//! /// 这相当于使用 `wrapping_offset` 将 `self` 偏移到给定地址,因此具有所有相同的功能和限制。
//! ///
//! ///
//! ///
//! pub fn with_addr(self, addr: usize) -> Self;
//! ```
//!
//! 所以您仍然可以丢弃一个地址表示并做任何您想要的聪明的技巧 *只要* 您能够将指针保持在您关心的分配中,可以 "reconstitute" 指针的其他部分.
//! 通常这很容易,因为您只需要一个指针,弄乱地址,然后立即转换回指针。
//! 为了使这个用例更符合人体工程学,我们提供了 [`map_addr`][] 方法。
//!
//! 为了清楚地表明代码是 "following" Strict Provenance 语义,我们还提供了一个 [`addr`][] 方法,该方法 promises 返回的地址不是指针使用指针往返的一部分。在 future 中,我们可以为指针 <-> 整数转换提供 lint,以帮助您审核您的代码是否符合严格的 provenance。
//!
//! ## 使用 Strict Provenance
//!
//! 大多数代码不需要更改以符合 strict provenance,因为 *不是* 显然已经存在未定义行为的唯一真正相关的操作是从 usize 强制转换为指针。对于 *does* 将 usize 转换为指针的代码,更改的作用域取决于您正在做什么。
//!
//! 通常,您只需要确保如果要将使用地址转换为指针,然后使用该指针指向 read/write 内存,则需要保留一个具有足够来源来执行 read/write 本身的指针。这样,从地址到指针的所有强制转换基本上都只是应用 offsets/indexing。
//!
//! 对于像标记指针 *as 这样的简单情况,只要将标记指针表示为实际指针而不是 usize*,这通常是微不足道的。例如:
//!
//! ```
//! #![feature(strict_provenance)]
//!
//! unsafe {
//! // 我们要打包到指针中的标志
//! static HAS_DATA: usize = 0x1;
//! static FLAG_MASK: usize = !HAS_DATA;
//!
//! // 我们的值,它必须有足够的对齐,以便有备用的最低有效位。
//! let my_precious_data: u32 = 17;
//! assert!(core::mem::align_of::<u32>() > 1);
//!
//! // 创建一个标记指针
//! let ptr = &my_precious_data as *const u32;
//! let tagged = ptr.map_addr(|addr| addr | HAS_DATA);
//!
//! // 检查标志:
//! if tagged.addr() & HAS_DATA != 0 {
//! // 取消标记并读取指针
//! let data = *tagged.map_addr(|addr| addr & FLAG_MASK);
//! assert_eq!(data, 17);
//! } else {
//! unreachable!()
//! }
//! }
//! ```
//!
//! (是的,如果您一直使用 AtomicUsize 作为同步数据结构中的指针,则应该改用 AtomicPtr。
//! 如果这弄乱了您以原子方式操作指针的方式,我们想知道原因,以及需要做些什么来修复它。)
//!
//! 像 XOR 列表这样更复杂且通常 *evil* 的东西需要更重大的更改,例如在预分配的 Vec 或 Arena 中分配所有节点,并使用指向整个分配的指针来重构 XORed 地址。
//!
//! 必须从一个地址创建有效指针的情况,例如访问固定地址的内存映射接口的裸机代码,是一个关于如何支持的悬而未决的问题。
//! 这些情况仍然是允许的,但我们可能需要某种 "I know what I'm doing" 注解来向编译器解释这种情况。也有可能它们根本不需要特别注意,因为它们通常在 "the abstract machine" 的作用域之外访问内存,或者已经像 "volatile" 一样使用 "I know what I'm doing" 注解。
//!
//! 在 [Strict Provenance] 下,未定义行为:
//!
//! * 通过与该内存没有 provenance 的指针访问内存。
//!
//! * [`offset`] 指向或来自没有 provenance 的地址的指针。
//! 这意味着它总是 UB 来偏移一个指针,这个指针是从一个被释放的对象中派生出来的,即使这个偏移量是 0。请注意,其 provenance 的指针 "one past the end" 实际上并不在其 provenance 之外,它只有 0 个字节可以 load/store。
//!
//! 但它仍然听起来像是:
//!
//! * 仅从地址创建无效指针 (请参见 [`ptr::invalid`][])。这可用于 `null`*或*之类的标记值,以表示永远不可解引用的标记指针。通常,只要您不对整数使用要求它有效的操作 (偏移、读取、写入等),将整数伪装成指针 "for fun" 总是合理的。
//!
//! * 在任何充分对齐的非空地址处伪造大小为零的分配。
//! 即通常的 "ST 是假的,做你想做的事" 规则适用 *但是* 这仅适用于实际伪造 (整数转换为指针)。如果您借用一些结构体的字段,它 *碰巧* 是零大小,则结果指针将与该分配相关联,如果分配被释放,它仍然会失效。
//! 在 future 中,我们可能会引入一个 API 来明确这种伪造的分配。
//!
//! * [`wrapping_offset`][] 指向其 provenance 之外的指针。这包括具有 "no" provenance 的无效指针。不幸的是,对于特定平台,这可能存在实际限制,如何指定它 (如果有的话) 是一个悬而未决的问题。
//! 值得注意的是,[CHERI][] 依赖于一种压缩方案,该方案无法处理使偏移量 "too far" 越界的指针。如果发生这种情况,`addr` 返回的地址将是您期望的值,但 provenance 将失效,并且将其用于 read/write 会出错。
//! 这方面的细节是特定于架构的并且基于对齐,但是指针范围两侧的缓冲区非常大 (想想千字节,而不是字节)。
//!
//! * 按地址比较任意指针。地址是只是整数,因此总是有一个连贯的答案,即使指针无效或来自不同的 address-spaces/provenances。当然,比较来自不同地址空间的地址通常 *毫无意义*,但是将千克与米进行比较也是如此,并且 Rust 也不会阻止这种情况。
//! 类似地,如果您得到 "lucky",并且注意到一个指针过去是 "same" 地址作为不相关分配的开始,那么您对这个事实所做的任何事情都是 *可能* 会是莫名其妙的。
//! 由于两个指针仍然不允许访问另一个指针的分配 (bytes),因为它们仍然有不同的 provenance,所以这种莫名其妙的范围受到控制。
//!
//! * 执行指针标记技巧。这不属于 [`wrapping_offset`],但由于 [CHERI][] 的局限性,值得更详细地提及。低位标记非常健壮,并且通常甚至不会越界,因为类型确保大小 >= 对齐 (并且过度对齐实际上给了 CHERI 更大的灵活性)。
//! 任何比这更复杂的东西都会迅速进入 "extremely platform-specific" 领域,因为根据特定支持的操作可能会或可能不会允许某些事情。
//! 例如,ARM 明确支持高位标记,因此 ARM 上的 CHERI 继承了它并且应该支持它。
//!
//! ## 指针使用大小指针往返和 'exposed' 出处
//!
//! **本节*非规范*,是 [Strict Provenance] 实验的一部分。**
//!
//! 如上所述,在 [Strict Provenance] 下,指针 - 使用 - 指针往返是不可能的。
//! 但是,存在充满此类往返的遗留 Rust 代码,并且遗留平台 API 通常假设 `usize` 可以捕获构成指针的所有信息。也可能存在无法移植到 Strict Provenance 的代码 (我们会使用 [like to hear about][Strict Provenance])。
//!
//! 对于这种情况,有一个后备计划,一种 `选择退出` 严格来源的方法。
//! 但是,请注意,这会使您的代码更难指定,并且代码在 (well) 中无法与 [Miri] 和 [CHERI] 等工具一起使用。
//!
//! 此回退计划由 [`expose_addr`] 和 [`from_exposed_addr`] 方法 (相当于指针和整数之间的 `as` 转换) 提供。[`expose_addr`] 与 [`addr`] 很相似,但还添加了指向 'exposed' 的证明列表的指针。
//! (此列表纯粹是概念性的,它的存在是为了指定 Rust,但在实际执行中并未具体化,除非在 [Miri] 之类的工具中。) [`from_exposed_addr`] 可用于构造具有这些先前 'exposed' 出处之一的指针。
//! [`from_exposed_addr`] 仅将 `addr: usize` 作为参数,因此与 [`with_addr`] 不同,没有指示返回指针的正确出处是什么 -- 这正是指针 - 使用 - 指针往返如此难以严格指定的原因! 没有算法可以决定使用哪个出处。
//! 您可以将其视为 "guessing" 正确的出处,并且猜测将是 "maximally in your favor",从某种意义上说,如果有任何方法可以避免未定义的行为,那么这就是将要进行的猜测。
//! 但是,如果 *no* 以前的 'exposed' 出处证明返回的指针的使用方式是正确的,则程序具有未定义的行为。
//!
//! 使用 [`expose_addr`] 或 [`from_exposed_addr`] (或等效的 `as` 强制转换) 意味着代码*不*遵循严格的出处规则。Strict Provenance 实验的目标是确定是否可以在没有 [`expose_addr`] 和 [`from_exposed_addr`] 的情况下使用 Rust。
//! 如果这成功了,这将是避免规范复杂性和促进采用 [CHERI] 和 [Miri] 等工具的重大胜利,这对于提高对 (unsafe) Rust 代码的信心有很大帮助。
//!
//! [aliasing]: ../../nomicon/aliasing.html
//! [book]: ../../book/ch19-01-unsafe-rust.html#dereferencing-a-raw-pointer
//! [ub]: ../../reference/behavior-considered-undefined.html
//! [zst]: ../../nomicon/exotic-sizes.html#zero-sized-types-zsts
//! [atomic operations]: crate::sync::atomic
//! [`offset`]: pointer::offset
//! [`wrapping_offset`]: pointer::wrapping_offset
//! [`with_addr`]: pointer::with_addr
//! [`map_addr`]: pointer::map_addr
//! [`addr`]: pointer::addr
//! [`ptr::invalid`]: core::ptr::invalid
//! [`expose_addr`]: pointer::expose_addr
//! [`from_exposed_addr`]: from_exposed_addr
//! [Miri]: https://github.com/rust-lang/miri
//! [CHERI]: https://www.cl.cam.ac.uk/research/security/ctsrd/cheri/
//! [Strict Provenance]: https://github.com/rust-lang/rust/issues/95228
//! [Stacked Borrows]: https://plv.mpi-sws.org/rustbelt/stacked-borrows/
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
#![stable(feature = "rust1", since = "1.0.0")]
use crate::cmp::Ordering;
use crate::fmt;
use crate::hash;
use crate::intrinsics::{
self, assert_unsafe_precondition, is_aligned_and_not_null, is_nonoverlapping,
};
use crate::marker::FnPtr;
use crate::mem::{self, MaybeUninit};
mod alignment;
#[unstable(feature = "ptr_alignment_type", issue = "102070")]
pub use alignment::Alignment;
#[stable(feature = "rust1", since = "1.0.0")]
#[doc(inline)]
pub use crate::intrinsics::copy_nonoverlapping;
#[stable(feature = "rust1", since = "1.0.0")]
#[doc(inline)]
pub use crate::intrinsics::copy;
#[stable(feature = "rust1", since = "1.0.0")]
#[doc(inline)]
pub use crate::intrinsics::write_bytes;
mod metadata;
#[unstable(feature = "ptr_metadata", issue = "81513")]
pub use metadata::{from_raw_parts, from_raw_parts_mut, metadata, DynMetadata, Pointee, Thin};
mod non_null;
#[stable(feature = "nonnull", since = "1.25.0")]
pub use non_null::NonNull;
mod unique;
#[unstable(feature = "ptr_internals", issue = "none")]
pub use unique::Unique;
mod const_ptr;
mod mut_ptr;
/// 执行指向值的析构函数 (如果有)。
///
/// 从语义上讲,这等效于调用 [`ptr::read`] 并丢弃结果,但是具有以下优点:
///
/// * 强制要求使用 `drop_in_place` 丢弃未定义大小的类型 (例如 trait 对象),因为它们无法被读取到栈上并且无法正常丢弃。
///
/// * 当丢弃手动分配的内存时 (例如,在 `Box`/`Rc`/`Vec` 的实现中),通过 [`ptr::read`] 进行此操作对优化器来说更友好,因为编译器不需要证明丢弃副本是合理的。
///
///
/// * 当 `T` 不是 `repr(packed)` 时,可用于丢弃 [固定][pinned] 数据 (在丢弃固定的数据之前,不得移动固定的数据)。
///
/// 未对齐的值不能被直接丢弃,必须先使用 [`ptr::read_unaligned`] 将它们复制到对齐的位置。对于包装的结构体,此移动由编译器自动完成。
/// 这意味着已打包结构的字段不会被原地丢弃。
///
/// [`ptr::read`]: self::read
/// [`ptr::read_unaligned`]: self::read_unaligned
/// [pinned]: crate::pin
///
/// # Safety
///
/// 如果违反以下任一条件,则行为是未定义的:
///
/// * 对于读取和写入,`to_drop` 必须是 [有效][valid]。
///
/// * `to_drop` 必须正确对齐,即使 `T` 有大小 0.
///
/// * `to_drop` 必须是非空的,即使 `T` 有大小 0.
///
/// * `to_drop` 指向的值必须对抛弃有效,这可能意味着它必须支持额外的不,变体。这些不变体,取决于丢弃的值的类型。
/// 例如,当丢弃一个 Box 时,box 的,指向堆的指针必须是有效的。
///
/// * 当 `drop_in_place` 正在执行时,访问 `to_drop` 部分的唯一方法是通过提供给 `drop_in_place` 调用的 `Drop::drop` 方法的 `&mut self` 引用。
///
/// 此外,如果 `T` 不是 [`Copy`],则在调用 `drop_in_place` 之后使用指向的值可能会导致未定义的行为。请注意,`*to_drop = foo` 被视为使用,因为它将导致该值再次被丢弃。
/// [`write()`] 可用于覆盖数据,而不会导致数据被丢弃。
///
/// [valid]: self#safety
///
/// # Examples
///
/// 从 vector 手动删除最后一个项:
///
/// ```
/// use std::ptr;
/// use std::rc::Rc;
///
/// let last = Rc::new(1);
/// let weak = Rc::downgrade(&last);
///
/// let mut v = vec![Rc::new(0), last];
///
/// unsafe {
/// // 获取指向 `v` 中最后一个元素的裸指针。
/// let ptr = &mut v[1] as *mut _;
/// // 缩短 `v`,以防止丢弃最后一个项。
/// // 我们首先这样做是为了防止 `drop_in_place` 低于 panics。
/// v.set_len(1);
/// // 如果没有调用 `drop_in_place`,则最后一个项将永远不会被删除,并且它管理的内存也会泄漏。
/////
/// ptr::drop_in_place(ptr);
/// }
///
/// assert_eq!(v, &[0.into()]);
///
/// // 确保丢弃了最后一项。
/// assert!(weak.upgrade().is_none());
/// ```
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
#[stable(feature = "drop_in_place", since = "1.8.0")]
#[lang = "drop_in_place"]
#[allow(unconditional_recursion)]
pub unsafe fn drop_in_place<T: ?Sized>(to_drop: *mut T) {
// 这里的代码并不重要 - 编译器会将其替换为真正的 drop glue。
//
// SAFETY: 请看上面的注释
unsafe { drop_in_place(to_drop) }
}
/// 创建一个空的裸指针。
///
/// # Examples
///
/// ```
/// use std::ptr;
///
/// let p: *const i32 = ptr::null();
/// assert!(p.is_null());
/// ```
#[inline(always)]
#[must_use]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_promotable]
#[rustc_const_stable(feature = "const_ptr_null", since = "1.24.0")]
#[rustc_allow_const_fn_unstable(ptr_metadata)]
#[rustc_diagnostic_item = "ptr_null"]
pub const fn null<T: ?Sized + Thin>() -> *const T {
from_raw_parts(invalid(0), ())
}
/// 创建一个空的可变裸露指针。
///
/// # Examples
///
/// ```
/// use std::ptr;
///
/// let p: *mut i32 = ptr::null_mut();
/// assert!(p.is_null());
/// ```
#[inline(always)]
#[must_use]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_promotable]
#[rustc_const_stable(feature = "const_ptr_null", since = "1.24.0")]
#[rustc_allow_const_fn_unstable(ptr_metadata)]
#[rustc_diagnostic_item = "ptr_null_mut"]
pub const fn null_mut<T: ?Sized + Thin>() -> *mut T {
from_raw_parts_mut(invalid_mut(0), ())
}
/// 创建具有给定地址的无效指针。
///
/// 这与 `addr as *const T` 不同,`addr as *const T` 创建一个指针来获取先前公开的出处。有关该操作的更多详细信息,请参见 [`from_exposed_addr`]。
///
/// 该模块的顶层文档讨论了 "invalid" 指针的确切含义,但本质上这表示该指针与任何实际分配无关,只不过是一个伪装的 usize 地址。
///
///
/// 该指针将没有与之关联的 provenance,因此 read/write/offset 是 UB 的。这主要是为了促进像 `ptr::null` 和 `NonNull::dangling` 这样的东西,它们会产生无效的指针。
///
/// (标准 "Zero-Sized-Types get to cheat and lie" 的警告是适用的,尽管可能需要为它们提供自己的 API,以便 100% 清楚地说明这一点。)
///
/// 此 API 及其声明的语义是 Strict Provenance 实验的一部分,有关详细信息,请参见 [模块文档][crate::ptr]。
///
///
///
///
///
///
#[inline(always)]
#[must_use]
#[rustc_const_stable(feature = "stable_things_using_strict_provenance", since = "1.61.0")]
#[unstable(feature = "strict_provenance", issue = "95228")]
pub const fn invalid<T>(addr: usize) -> *const T {
// FIXME(strict_provenance_magic): 我是魔法,应该是编译器内部函数。
// 我们使用 transmute 而不是 cast,所以像 Miri 这样的工具可以判断这与 from_exposed_addr*不*相同。
//
// SAFETY: 每个有效的整数也是一个有效的指针 (只要您不解引用那个指针)。
//
unsafe { mem::transmute(addr) }
}
/// 用给定的地址创建一个无效的可变指针。
///
/// 这与 `addr as *mut T` 不同,`addr as *mut T` 创建一个指针来获取先前公开的出处。有关该操作的更多详细信息,请参见 [`from_exposed_addr_mut`]。
///
/// 该模块的顶层文档讨论了 "invalid" 指针的确切含义,但本质上这表示该指针与任何实际分配无关,只不过是一个伪装的 usize 地址。
///
///
/// 该指针将没有与之关联的 provenance,因此 read/write/offset 是 UB 的。这主要是为了促进像 `ptr::null` 和 `NonNull::dangling` 这样的东西,它们会产生无效的指针。
///
/// (标准 "Zero-Sized-Types get to cheat and lie" 的警告是适用的,尽管可能需要为它们提供自己的 API,以便 100% 清楚地说明这一点。)
///
/// 此 API 及其声明的语义是 Strict Provenance 实验的一部分,有关详细信息,请参见 [模块文档][crate::ptr]。
///
///
///
///
///
///
#[inline(always)]
#[must_use]
#[rustc_const_stable(feature = "stable_things_using_strict_provenance", since = "1.61.0")]
#[unstable(feature = "strict_provenance", issue = "95228")]
pub const fn invalid_mut<T>(addr: usize) -> *mut T {
// FIXME(strict_provenance_magic): 我是魔法,应该是编译器内部函数。
// 我们使用 transmute 而不是 cast,所以像 Miri 这样的工具可以判断这与 from_exposed_addr*不*相同。
//
// SAFETY: 每个有效的整数也是一个有效的指针 (只要您不解引用那个指针)。
//
unsafe { mem::transmute(addr) }
}
/// 将地址转换回指针,获取以前的 'exposed' 出处。
///
/// 这相当于 `addr as *const T`。返回指针的出处是先前通过将其传递给 [`expose_addr`][pointer::expose_addr] 或 `ptr as usize` 强制转换而暴露的 *any* 指针的出处。
/// 此外,不受 Rust 抽象机控制的内存 (例如 MMIO 寄存器) 总是被认为是暴露的,只要该内存与抽象机将使用的内存 (例如栈) 不相交,堆和静态。
///
///
/// 如果没有 'exposed' 出处证明该指针的使用方式是正确的,则程序具有未定义的行为。
/// 特别是,别名规则仍然适用: 由于别名访问而失效的指针和引用不能再使用,即使它们已经暴露!
///
/// 请注意,没有算法可以决定使用哪个出处。
/// 您可以将此视为 "guessing" 正确的出处,并且猜测将是 "maximally in your favor",因为如果有任何方法可以避免未定义的行为 (同时支持所有别名要求),那么这就是将要进行的猜测。
///
/// 在具有多个地址空间的平台上,您有责任确保该地址在该指针将使用的地址空间中有意义。
///
/// 使用这种方法意味着代码没有遵循严格的出处规则。
/// "Guessing" 合适的出处使规范和推理复杂化,并且可能不受帮助您与 Rust 内存模型保持一致的工具的支持,因此建议尽可能使用 [`with_addr`][pointer::with_addr]。
///
/// 在大多数平台上,这将产生一个与地址具有相同字节的值。
/// 需要在指针中存储附加信息的平台可能不支持此操作,因为通常不可能实际*计算*返回的指针必须拾取哪个出处。
///
/// 此 API 及其声明的语义是 Strict Provenance 实验的一部分,有关详细信息,请参见 [模块文档][crate::ptr]。
///
///
///
///
///
///
///
///
///
///
///
///
///
#[must_use]
#[inline(always)]
#[unstable(feature = "strict_provenance", issue = "95228")]
#[cfg_attr(miri, track_caller)] // 即使没有 panic,这也有助于 Miri 回溯
#[allow(fuzzy_provenance_casts)] // 这是 * 应该使用的严格出处 API
pub fn from_exposed_addr<T>(addr: usize) -> *const T
where
T: Sized,
{
// FIXME(strict_provenance_magic): 我是魔法,应该是编译器内部函数。
addr as *const T
}
/// 将地址转换回错误指针,获取以前的 'exposed' 出处。
///
/// 这相当于 `addr as *mut T`。返回指针的出处是先前传递给 [`expose_addr`][pointer::expose_addr] 或 `ptr as usize` 强制转换的 *any* 指针的出处。
/// 如果没有以前的 'exposed' 出处证明该指针的使用方式是正确的,则程序具有未定义的行为。
/// 请注意,没有算法可以决定使用哪个出处。
/// 您可以将其视为 "guessing" 正确的出处,并且猜测将是 "maximally in your favor",从某种意义上说,如果有任何方法可以避免未定义的行为,那么这就是将要进行的猜测。
///
/// 在具有多个地址空间的平台上,您有责任确保该地址在该指针将使用的地址空间中有意义。
///
/// 使用这种方法意味着代码没有遵循严格的出处规则。
/// "Guessing" 合适的出处使规范和推理复杂化,并且可能不受帮助您与 Rust 内存模型保持一致的工具的支持,因此建议尽可能使用 [`with_addr`][pointer::with_addr]。
///
///
/// 在大多数平台上,这将产生一个与地址具有相同字节的值。
/// 需要在指针中存储附加信息的平台可能不支持此操作,因为通常不可能实际*计算*返回的指针必须拾取哪个出处。
///
/// 此 API 及其声明的语义是 Strict Provenance 实验的一部分,有关详细信息,请参见 [模块文档][crate::ptr]。
///
///
///
///
///
///
///
///
#[must_use]
#[inline(always)]
#[unstable(feature = "strict_provenance", issue = "95228")]
#[cfg_attr(miri, track_caller)] // 即使没有 panic,这也有助于 Miri 回溯
#[allow(fuzzy_provenance_casts)] // 这是 * 应该使用的严格出处 API
pub fn from_exposed_addr_mut<T>(addr: usize) -> *mut T
where
T: Sized,
{
// FIXME(strict_provenance_magic): 我是魔法,应该是编译器内部函数。
addr as *mut T
}
/// 将引用转换为裸指针。
///
/// 这等同于 `r as *const T`,但更安全一些,因为它永远不会默默地更改类型或可变性,尤其是在重构代码的情况下。
///
#[inline(always)]
#[must_use]
#[unstable(feature = "ptr_from_ref", issue = "106116")]
pub const fn from_ref<T: ?Sized>(r: &T) -> *const T {
r
}
/// 将可变引用转换为裸指针。
///
/// 这等同于 `r as *mut T`,但更安全一些,因为它永远不会默默地更改类型或可变性,尤其是在重构代码的情况下。
///
#[inline(always)]
#[must_use]
#[unstable(feature = "ptr_from_ref", issue = "106116")]
pub const fn from_mut<T: ?Sized>(r: &mut T) -> *mut T {
r
}
/// 根据指针和长度形成原始切片。
///
/// `len` 参数是 **元素** 的数量,而不是字节数。
///
/// 此函数是安全的,但实际上使用返回值是不安全的。
/// 有关切片的安全要求,请参见 [`slice::from_raw_parts`] 的文档。
///
/// [`slice::from_raw_parts`]: crate::slice::from_raw_parts
///
/// # Examples
///
/// ```rust
/// use std::ptr;
///
/// // 从指向第一个元素的指针开始创建切片指针
/// let x = [5, 6, 7];
/// let raw_pointer = x.as_ptr();
/// let slice = ptr::slice_from_raw_parts(raw_pointer, 3);
/// assert_eq!(unsafe { &*slice }[2], 7);
/// ```
#[inline]
#[stable(feature = "slice_from_raw_parts", since = "1.42.0")]
#[rustc_const_stable(feature = "const_slice_from_raw_parts", since = "1.64.0")]
#[rustc_allow_const_fn_unstable(ptr_metadata)]
pub const fn slice_from_raw_parts<T>(data: *const T, len: usize) -> *const [T] {
from_raw_parts(data.cast(), len)
}
/// 执行与 [`slice_from_raw_parts`] 相同的功能,但返回的是原始可变切片,而不是原始的不可变切片。
///
///
/// 有关更多详细信息,请参见 [`slice_from_raw_parts`] 的文档。
///
/// 此函数是安全的,但实际上使用返回值是不安全的。
/// 有关切片的安全要求,请参见 [`slice::from_raw_parts_mut`] 的文档。
///
/// [`slice::from_raw_parts_mut`]: crate::slice::from_raw_parts_mut
///
/// # Examples
///
/// ```rust
/// use std::ptr;
///
/// let x = &mut [5, 6, 7];
/// let raw_pointer = x.as_mut_ptr();
/// let slice = ptr::slice_from_raw_parts_mut(raw_pointer, 3);
///
/// unsafe {
/// (*slice)[2] = 99; // 在切片中的索引处分配值
/// };
///
/// assert_eq!(unsafe { &*slice }[2], 99);
/// ```
#[inline]
#[stable(feature = "slice_from_raw_parts", since = "1.42.0")]
#[rustc_const_unstable(feature = "const_slice_from_raw_parts_mut", issue = "67456")]
pub const fn slice_from_raw_parts_mut<T>(data: *mut T, len: usize) -> *mut [T] {
from_raw_parts_mut(data.cast(), len)
}
/// 在相同类型的两个可变位置交换值,而无需取消初始化任何一个。
///
/// 但对于以下例外,这个函数在语义上等价于 [`mem::swap`]:
///
/// * 它对裸指针而不是引用进行操作。
/// 如果引用可用,则应首选 [`mem::swap`]。
///
/// * 两个指向的值可能会重叠。
/// 如果值确实重叠,则将使用 `x` 的内存重叠区域。
/// 在下面的第二个示例中对此进行了演示。
///
/// * 该操作是 "untyped",因为数据可能未初始化或违反 `T` 的要求。
///
/// 初始化状态被完全保留。
///
/// # Safety
///
/// 如果违反以下任一条件,则行为是未定义的:
///
/// * 对于读取和写入,`x` 和 `y` 都必须为 [有效][valid] 的。
///
/// * `x` 和 `y` 必须正确对齐。
///
/// 请注意,即使 `T` 的大小为 `0`,指针也必须非空且正确对齐。
///
/// [valid]: self#safety
///
/// # Examples
///
/// 交换两个不重叠的区域:
///
/// ```
/// use std::ptr;
///
/// let mut array = [0, 1, 2, 3];
///
/// let (x, y) = array.split_at_mut(2);
/// let x = x.as_mut_ptr().cast::<[u32; 2]>(); // 这是 `array[0..2]`
/// let y = y.as_mut_ptr().cast::<[u32; 2]>(); // 这是 `array[2..4]`
///
/// unsafe {
/// ptr::swap(x, y);
/// assert_eq!([2, 3, 0, 1], array);
/// }
/// ```
///
/// 交换两个重叠的区域:
///
/// ```
/// use std::ptr;
///
/// let mut array: [i32; 4] = [0, 1, 2, 3];
///
/// let array_ptr: *mut i32 = array.as_mut_ptr();
///
/// let x = array_ptr as *mut [i32; 3]; // 这是 `array[0..3]`
/// let y = unsafe { array_ptr.add(1) } as *mut [i32; 3]; // 这是 `array[1..4]`
///
/// unsafe {
/// ptr::swap(x, y);
/// // 切片的索引 `1..3` 在 `x` 和 `y` 之间重叠。
/// // 合理的结果将是 `[2, 3]`,因此索引 `0..3` 为 `[1, 2, 3]` (与 `swap` 匹配的 `y`) ; 或将它们设为 `[0, 1]`,以使索引 `1..4` 为 `[0, 1, 2]` (与 `swap` 之前的 `x` 匹配)。
/////
/// // 定义此实现是为了做出后一种选择。
/////
/// assert_eq!([1, 0, 1, 2], array);
/// }
/// ```
///
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_const_unstable(feature = "const_swap", issue = "83163")]
pub const unsafe fn swap<T>(x: *mut T, y: *mut T) {
// 给自己一些工作的空间。
// 我们不必担心丢弃: `MaybeUninit` 在丢弃时什么也不做。
let mut tmp = MaybeUninit::<T>::uninit();
// 执行交换
// SAFETY: 调用者必须保证 `x` 和 `y` 对写入有效并且正确对齐。
// `tmp` 不能与 `x` 或 `y` 重叠,因为 `tmp` 只是作为单独的分配对象在栈上分配。
//
//
unsafe {
copy_nonoverlapping(x, tmp.as_mut_ptr(), 1);
copy(y, x, 1); // `x` 和 `y` 可能重叠
copy_nonoverlapping(tmp.as_ptr(), y, 1);
}
}
/// 从 `x` 和 `y` 开始在两个内存区域之间交换 `count * size_of::<T>()` 字节。
/// 这两个区域必须 *不能* 重叠。
///
/// 该操作是 "untyped",因为数据可能未初始化或违反 `T` 的要求。
/// 初始化状态被完全保留。
///
/// # Safety
///
/// 如果违反以下任一条件,则行为是未定义的:
///
/// * `x` 和 `y` 都必须 [有效][valid] 才能读取和写入 `count *
/// size_of::<T>()` 个字节。
///
/// * `x` 和 `y` 必须正确对齐。
///
/// * 从 `x` 开始的内存区域,大小为 `count *
/// size_of::<T>()` 字节不得与以 `y` 开始且大小相同的内存区域重叠。
///
/// 请注意,即使有效复制的大小 (`count * size_of::<T>()`) 是 `0`,指针也必须非空的并且正确对齐。
///
///
/// [valid]: self#safety
///
/// # Examples
///
/// 基本用法:
///
/// ```
/// use std::ptr;
///
/// let mut x = [1, 2, 3, 4];
/// let mut y = [7, 8, 9];
///
/// unsafe {
/// ptr::swap_nonoverlapping(x.as_mut_ptr(), y.as_mut_ptr(), 2);
/// }
///
/// assert_eq!(x, [7, 8, 3, 4]);
/// assert_eq!(y, [1, 2, 9]);
/// ```
///
#[inline]
#[stable(feature = "swap_nonoverlapping", since = "1.27.0")]
#[rustc_const_unstable(feature = "const_swap", issue = "83163")]
pub const unsafe fn swap_nonoverlapping<T>(x: *mut T, y: *mut T, count: usize) {
#[allow(unused)]
macro_rules! attempt_swap_as_chunks {
($ChunkTy:ty) => {
if mem::align_of::<T>() >= mem::align_of::<$ChunkTy>()
&& mem::size_of::<T>() % mem::size_of::<$ChunkTy>() == 0
{
let x: *mut $ChunkTy = x.cast();
let y: *mut $ChunkTy = y.cast();
let count = count * (mem::size_of::<T>() / mem::size_of::<$ChunkTy>());
// SAFETY: 这些是调用者承诺的相同字节,只是输入为 `MaybeUninit<ChunkTy>`s 而不是 `T`s。
// 上面的 `if` 条件确保我们没有违反对齐要求,并且划分是准确的,这样我们就不会丢失任何最后的字节。
//
//
//
return unsafe { swap_nonoverlapping_simple_untyped(x, y, count) };
}
};
}
// SAFETY: 调用者必须保证 `x` 和 `y` 对写入有效并且正确对齐。
//
unsafe {
assert_unsafe_precondition!(
"ptr::swap_nonoverlapping requires that both pointer arguments are aligned and non-null \
and the specified memory ranges do not overlap",
[T](x: *mut T, y: *mut T, count: usize) =>
is_aligned_and_not_null(x)
&& is_aligned_and_not_null(y)
&& is_nonoverlapping(x, y, count)
);
}
// 将切片拆分为 LLVM 能够向量化的 2 次幂大小的小块 (除非它是具有多于指针对齐的特殊类型,因为我们不想悲观 SIMD vectors 的切片之类的东西。)
//
//
if mem::align_of::<T>() <= mem::size_of::<usize>()
&& (!mem::size_of::<T>().is_power_of_two()
|| mem::size_of::<T>() > mem::size_of::<usize>() * 2)
{
attempt_swap_as_chunks!(usize);
attempt_swap_as_chunks!(u8);
}
// SAFETY: 与此函数相同的前提条件
unsafe { swap_nonoverlapping_simple_untyped(x, y, count) }
}
/// 与 [`swap_nonoverlapping`] 相同的行为和安全条件
///
/// LLVM 可以对其进行矢量化 (至少它可以用于 `swap_nonoverlapping` 尝试使用的两倍大小的类型),因此无需手动对其进行 SIMD。
///
#[inline]
#[rustc_const_unstable(feature = "const_swap", issue = "83163")]
const unsafe fn swap_nonoverlapping_simple_untyped<T>(x: *mut T, y: *mut T, count: usize) {
let x = x.cast::<MaybeUninit<T>>();
let y = y.cast::<MaybeUninit<T>>();
let mut i = 0;
while i < count {
// SAFETY: 根据前提条件,`i` 是在界内,因为它低于 `n`
let x = unsafe { &mut *x.add(i) };
// SAFETY: 根据前提条件,`i` 是在界内,因为它低于 `n`,并且它不同于 `x`,因为范围不重叠
//
let y = unsafe { &mut *y.add(i) };
mem::swap_simple::<MaybeUninit<T>>(x, y);
i += 1;
}
}
/// 将 `src` 移至指定的 `dst`,返回先前的 `dst` 值。
///
/// 这两个值都不会被丢弃。
///
/// 该函数在语义上等效于 [`mem::replace`],除了它在裸指针上而不是在引用上运行。
/// 如果引用可用,则应首选 [`mem::replace`]。
///
/// # Safety
///
/// 如果违反以下任一条件,则行为是未定义的:
///
/// * 对于读取和写入,`dst` 必须是 [有效的][valid]。
///
/// * `dst` 必须正确对齐。
///
/// * `dst` 必须指向 `T` 类型的正确初始化值。
///
/// 请注意,即使 `T` 的大小为 `0`,指针也必须非空且正确对齐。
///
/// [valid]: self#safety
///
/// # Examples
///
/// ```
/// use std::ptr;
///
/// let mut rust = vec!['b', 'u', 's', 't'];
///
/// // `mem::replace` 将具有相同的效果,而无需 unsafe 块。
/////
/// let b = unsafe {
/// ptr::replace(&mut rust[0], 'r')
/// };
///
/// assert_eq!(b, 'b');
/// assert_eq!(rust, &['r', 'u', 's', 't']);
/// ```
///
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_const_unstable(feature = "const_replace", issue = "83164")]
pub const unsafe fn replace<T>(dst: *mut T, mut src: T) -> T {
// SAFETY: 调用者必须保证 `dst` 有效,可以强制转换为变量引用 (对写入,对齐,初始化有效),并且不能与 `src` 重叠,因为 `dst` 必须指向不同的分配对象。
//
//
//
unsafe {
assert_unsafe_precondition!(
"ptr::replace requires that the pointer argument is aligned and non-null",
[T](dst: *mut T) => is_aligned_and_not_null(dst)
);
mem::swap(&mut *dst, &mut src); // 不能重叠
}
src
}
/// 从 `src` 读取值而不移动它。这将使 `src` 中的内存保持不变。
///
/// # Safety
///
/// 如果违反以下任一条件,则行为是未定义的:
///
/// * `src` 必须是 [有效的][valid] 才能读取。
///
/// * `src` 必须正确对齐。如果不是这种情况,请使用 [`read_unaligned`]。
///
/// * `src` 必须指向 `T` 类型的正确初始化值。
///
/// 请注意,即使 `T` 的大小为 `0`,指针也必须非空且正确对齐。
///
/// # Examples
///
/// 基本用法:
///
/// ```
/// let x = 12;
/// let y = &x as *const i32;
///
/// unsafe {
/// assert_eq!(std::ptr::read(y), 12);
/// }
/// ```
///
/// 手动实现 [`mem::swap`]:
///
/// ```
/// use std::ptr;
///
/// fn swap<T>(a: &mut T, b: &mut T) {
/// unsafe {
/// // 在 `tmp` 中的 `a` 处创建值的按位副本。
/// let tmp = ptr::read(a);
///
/// // 此时退出 (通过显式返回或调用 panics 的函数) 将导致 `tmp` 中的值被丢弃,而 `a` 仍引用相同的值。
/// // 如果 `T` 不是 `Copy`,则可能触发未定义的行为。
/////
/////
///
/// // 在 `a` 中的 `b` 处创建值的按位副本。
/// // 这是安全的,因为可变引用不能使用别名。
/// ptr::copy_nonoverlapping(b, a, 1);
///
/// // 如上所述,退出此处可能会触发未定义的行为,因为 `a` 和 `b` 引用了相同的值。
/////
///
/// // 将 `tmp` 移至 `b`。
/// ptr::write(b, tmp);
///
/// // `tmp` 已移动 (`write` 对其第二个参数的所有权),因此这里没有隐含地丢弃任何东西。
/////
/// }
/// }
///
/// let mut foo = "foo".to_owned();
/// let mut bar = "bar".to_owned();
///
/// swap(&mut foo, &mut bar);
///
/// assert_eq!(foo, "bar");
/// assert_eq!(bar, "foo");
/// ```
///
/// ## 归还值的所有权
///
/// `read` 创建 `T` 的按位副本,无论 `T` 是否为 [`Copy`]。
/// 如果 `T` 不是 [`Copy`],则同时使用返回的值和 `*src` 的值可能会违反内存安全性。
/// 请注意,将分配给 `*src` 视为一种用途,因为它将尝试丢弃 `*src` 处的值。
///
/// [`write()`] 可用于覆盖数据,而不会导致数据被丢弃。
///
/// ```
/// use std::ptr;
///
/// let mut s = String::from("foo");
/// unsafe {
/// // `s2` 现在指向与 `s` 相同的底层内存。
/// let mut s2: String = ptr::read(&s);
///
/// assert_eq!(s2, "foo");
///
/// // 分配给 `s2` 会导致其原始值被丢弃。
/// // 除此之外,由于已释放底层内存,因此不能再使用 `s`。
/////
/// s2 = String::default();
/// assert_eq!(s2, "");
///
/// // 分配给 `s` 将导致旧值再次被丢弃,从而导致未定义的行为。
/////
/// // s = String::from("bar"); // 错误
///
/// // `ptr::write` 可用于覆盖一个值而无需丢弃它。
/// ptr::write(&mut s, String::from("bar"));
/// }
///
/// assert_eq!(s, "bar");
/// ```
///
/// [valid]: self#safety
///
///
///
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_const_stable(feature = "const_ptr_read", since = "1.71.0")]
#[rustc_allow_const_fn_unstable(const_mut_refs, const_maybe_uninit_as_mut_ptr)]
#[cfg_attr(miri, track_caller)] // 即使没有 panic,这也有助于 Miri 回溯
pub const unsafe fn read<T>(src: *const T) -> T {
// 通过 `copy_nonoverlapping` 和 `MaybeUninit` 实现它在语义上是正确的,就像在 PR #109035 之前所做的那样。
// 调用 `assume_init` 提供了足够的信息来知道这是一个类型化操作。
//
// 但是,截至 2023 年 3 月,编译器无法利用该信息。
// 因此,这里的实现切换到一个内部函数,它在 MIR 中降低到 `_0 = *src`,以解决一些问题:
//
// - 在 `copy_nonoverlapping` 之后使用 `MaybeUninit::assume_init` 不会将未类型化的副本变成类型化的负载。因此,在 LLVM 中生成的 `load` 没有获得各种元数据,例如 `!range` (#73258)、`!nonnull` 和 `!noundef`,导致优化较差。
// - 通过额外的本地会导致多个额外的副本,即使在优化的 MIR 中也是如此。
// (忽略 StorageLive/Dead,内部函数是一个 MIR 语句,而之前的实现是八个。) LLVM 有时可以优化它们,但是因为 `read` 是很多东西的核心,所以首先没有它们可以改善我们手头的东西关闭到后端。
//
// 例如,`mem::replace::<Big>` 之前发出了 4 个 `alloca` 和 6 个 `memcpy`,但现在是 1 个 `alloc` 和 3 个 `memcpy`。
// - 一般来说,这种方法可以防止我们得到更多归结为 "`read(p)` is worse than `*p`" 的错误 (如 #106369),因为这使它们看起来与后端 (或其他 MIR 消费者) 相同。
//
// Future 对 MIR 优化的增强很可能允许它返回到以前的实现,而不是使用内部函数。
//
//
//
//
//
//
//
//
//
//
// SAFETY: 调用者必须保证 `src` 对于读取有效。
unsafe {
assert_unsafe_precondition!(
"ptr::read requires that the pointer argument is aligned and non-null",
[T](src: *const T) => is_aligned_and_not_null(src)
);
crate::intrinsics::read_via_copy(src)
}
}
/// 从 `src` 读取值而不移动它。这将使 `src` 中的内存保持不变。
///
/// 与 [`read`] 不同,`read_unaligned` 使用未对齐的指针。
///
/// # Safety
///
/// 如果违反以下任一条件,则行为是未定义的:
///
/// * `src` 必须是 [有效的][valid] 才能读取。
///
/// * `src` 必须指向 `T` 类型的正确初始化值。
///
/// 与 [`read`] 一样,无论 `T` 是否为 [`Copy`],`read_unaligned` 都会创建 `T` 的按位副本。
/// 如果 `T` 不是 [`Copy`],则同时使用返回值和 `*src` 处的值都可以 [违反内存安全][read-ownership]。
///
/// 请注意,即使 `T` 的大小为 `0`,指针也必须非空。
///
/// [read-ownership]: read#ownership-of-the-returned-value
/// [valid]: self#safety
///
/// ## 在 `packed` 结构体上
///
/// 尝试使用诸如 `&packed.unaligned as *const FieldType` 的表达式创建指向 `unaligned` 结构体字段的裸指针,然后再将其转换为裸指针,这会产生一个中间未对齐的引用。
///
/// 引用是临时的并且立即强制转换是无关紧要的,因为编译器始终希望引用正确对齐。
/// 结果,使用 `&packed.unaligned as *const FieldType` 会在程序中立即导致* undefined 行为 *。
///
/// 相反,您必须使用 [`ptr::addr_of!`](addr_of) 宏来创建指针。您可以将返回的指针与此函数一起使用。
///
/// 一个不执行的操作以及它与 `read_unaligned` 的关系的示例是:
///
/// ```
/// #[repr(packed, C)]
/// struct Packed {
/// _padding: u8,
/// unaligned: u32,
/// }
///
/// let packed = Packed {
/// _padding: 0x00,
/// unaligned: 0x01020304,
/// };
///
/// // 取一个未对齐的 32 位整数的地址。
/// // 与 `&packed.unaligned as *const _` 相比,它没有未定义的行为。
/// let unaligned = std::ptr::addr_of!(packed.unaligned);
///
/// let v = unsafe { std::ptr::read_unaligned(unaligned) };
/// assert_eq!(v, 0x01020304);
/// ```
///
/// 但是,例如使用 `packed.unaligned` 直接访问未对齐的字段是安全的。
///
/// # Examples
///
/// 从字节缓冲区读取 usize 值:
///
/// ```
/// use std::mem;
///
/// fn read_usize(x: &[u8]) -> usize {
/// assert!(x.len() >= mem::size_of::<usize>());
///
/// let ptr = x.as_ptr() as *const usize;
///
/// unsafe { ptr.read_unaligned() }
/// }
/// ```
///
///
///
///
///
///
///
#[inline]
#[stable(feature = "ptr_unaligned", since = "1.17.0")]
#[rustc_const_stable(feature = "const_ptr_read", since = "1.71.0")]
#[rustc_allow_const_fn_unstable(const_mut_refs, const_maybe_uninit_as_mut_ptr)]
#[cfg_attr(miri, track_caller)] // 即使没有 panic,这也有助于 Miri 回溯
pub const unsafe fn read_unaligned<T>(src: *const T) -> T {
let mut tmp = MaybeUninit::<T>::uninit();
// SAFETY: 调用者必须保证 `src` 对于读取有效。
// `src` 不能与 `tmp` 重叠,因为 `tmp` 只是作为单独的分配对象在栈上分配的。
//
//
// 另外,由于我们只是将有效值写入 `tmp`,因此可以确保正确初始化它。
//
unsafe {
copy_nonoverlapping(src as *const u8, tmp.as_mut_ptr() as *mut u8, mem::size_of::<T>());
tmp.assume_init()
}
}
/// 用给定值覆盖存储位置,而无需读取或丢弃旧值。
///
/// `write` 不会丢弃 `dst` 的内容。
/// 这是安全的,但可能会泄漏分配或资源,因此应注意不要覆盖应丢弃的对象。
///
///
/// 此外,它不会丢弃 `src`。在语义上,`src` 被移到 `dst` 指向的位置。
///
/// 这适用于初始化未初始化的内存,或覆盖以前是 [`read`] 的内存。
///
/// # Safety
///
/// 如果违反以下任一条件,则行为是未定义的:
///
/// * `dst` 必须是 [有效的][valid] 才能写入。
///
/// * `dst` 必须正确对齐。如果不是这种情况,请使用 [`write_unaligned`]。
///
/// 请注意,即使 `T` 的大小为 `0`,指针也必须非空且正确对齐。
///
/// [valid]: self#safety
///
/// # Examples
///
/// 基本用法:
///
/// ```
/// let mut x = 0;
/// let y = &mut x as *mut i32;
/// let z = 12;
///
/// unsafe {
/// std::ptr::write(y, z);
/// assert_eq!(std::ptr::read(y), 12);
/// }
/// ```
///
/// 手动实现 [`mem::swap`]:
///
/// ```
/// use std::ptr;
///
/// fn swap<T>(a: &mut T, b: &mut T) {
/// unsafe {
/// // 在 `tmp` 中的 `a` 处创建值的按位副本。
/// let tmp = ptr::read(a);
///
/// // 此时退出 (通过显式返回或调用 panics 的函数) 将导致 `tmp` 中的值被丢弃,而 `a` 仍引用相同的值。
/// // 如果 `T` 不是 `Copy`,则可能触发未定义的行为。
/////
/////
///
/// // 在 `a` 中的 `b` 处创建值的按位副本。
/// // 这是安全的,因为可变引用不能使用别名。
/// ptr::copy_nonoverlapping(b, a, 1);
///
/// // 如上所述,退出此处可能会触发未定义的行为,因为 `a` 和 `b` 引用了相同的值。
/////
///
/// // 将 `tmp` 移至 `b`。
/// ptr::write(b, tmp);
///
/// // `tmp` 已移动 (`write` 对其第二个参数的所有权),因此这里没有隐含地丢弃任何东西。
/////
/// }
/// }
///
/// let mut foo = "foo".to_owned();
/// let mut bar = "bar".to_owned();
///
/// swap(&mut foo, &mut bar);
///
/// assert_eq!(foo, "bar");
/// assert_eq!(bar, "foo");
/// ```
///
///
///
///
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_const_unstable(feature = "const_ptr_write", issue = "86302")]
#[cfg_attr(miri, track_caller)] // 即使没有 panic,这也有助于 Miri 回溯
pub const unsafe fn write<T>(dst: *mut T, src: T) {
// 从语义上讲,将其实现为 `copy_nonoverlapping` 并适当丢弃抑制 `src` 会很好。
//
// 然而,通过目前的方式实现会产生比理想情况更多的 MIR。
// 使用内部函数可以将其简化为 MIR 中的简单 `*dst = move src` (在撰写本文时缩短了 11 个语句),并且还允许 `src` 在 codegen_ssa 中保留 SSA 值,而不是内存值。
//
//
// SAFETY: 调用者必须保证 `dst` 对写入有效。
// `dst` 不能与 `dst` 重叠,因为调用者拥有 `dst` 的权限,而 `src` 是这个函数拥有所有权的。
//
unsafe {
assert_unsafe_precondition!(
"ptr::write requires that the pointer argument is aligned and non-null",
[T](dst: *mut T) => is_aligned_and_not_null(dst)
);
intrinsics::write_via_move(dst, src)
}
}
/// 用给定值覆盖存储位置,而无需读取或丢弃旧值。
///
/// 与 [`write()`] 不同,指针可能未对齐。
///
/// `write_unaligned` 不会丢弃 `dst` 的内容。这是安全的,但可能会泄漏分配或资源,因此应注意不要覆盖应丢弃的对象。
///
/// 此外,它不会丢弃 `src`。在语义上,`src` 被移到 `dst` 指向的位置。
///
/// 这适用于初始化未初始化的内存,或覆盖以前用 [`read_unaligned`] 读取的内存。
///
/// # Safety
///
/// 如果违反以下任一条件,则行为是未定义的:
///
/// * `dst` 必须是 [有效的][valid] 才能写入。
///
/// 请注意,即使 `T` 的大小为 `0`,指针也必须非空。
///
/// [valid]: self#safety
///
/// ## 在 `packed` 结构体上
///
/// 尝试使用诸如 `&packed.unaligned as *const FieldType` 的表达式创建指向 `unaligned` 结构体字段的裸指针,然后再将其转换为裸指针,这会产生一个中间未对齐的引用。
///
/// 引用是临时的并且立即强制转换是无关紧要的,因为编译器始终希望引用正确对齐。
/// 结果,使用 `&packed.unaligned as *const FieldType` 会在程序中立即导致* undefined 行为 *。
///
/// 相反,您必须使用 [`ptr::addr_of_mut!`](addr_of_mut) 宏来创建指针。您可以将返回的指针与此函数一起使用。
///
/// 如何做到这一点以及这与 `write_unaligned` 的关系的一个例子是:
///
/// ```
/// #[repr(packed, C)]
/// struct Packed {
/// _padding: u8,
/// unaligned: u32,
/// }
///
/// let mut packed: Packed = unsafe { std::mem::zeroed() };
///
/// // 取一个未对齐的 32 位整数的地址。
/// // 与 `&packed.unaligned as *mut _` 相比,它没有未定义的行为。
/// let unaligned = std::ptr::addr_of_mut!(packed.unaligned);
///
/// unsafe { std::ptr::write_unaligned(unaligned, 42) };
///
/// assert_eq!({packed.unaligned}, 42); // `{...}` 强制复制字段而不是创建引用。
/// ```
///
/// 然而,直接使用例如 `packed.unaligned` 访问未对齐的字段是安全的 (如上面的 `assert_eq!` 所示)。
///
/// # Examples
///
/// 将 usize 值写入字节缓冲区:
///
/// ```
/// use std::mem;
///
/// fn write_usize(x: &mut [u8], val: usize) {
/// assert!(x.len() >= mem::size_of::<usize>());
///
/// let ptr = x.as_mut_ptr() as *mut usize;
///
/// unsafe { ptr.write_unaligned(val) }
/// }
/// ```
///
///
///
///
///
///
///
///
///
///
///
#[inline]
#[stable(feature = "ptr_unaligned", since = "1.17.0")]
#[rustc_const_unstable(feature = "const_ptr_write", issue = "86302")]
#[cfg_attr(miri, track_caller)] // 即使没有 panic,这也有助于 Miri 回溯
pub const unsafe fn write_unaligned<T>(dst: *mut T, src: T) {
// SAFETY: 调用者必须保证 `dst` 对写入有效。
// `dst` 不能与 `dst` 重叠,因为调用者拥有 `dst` 的权限,而 `src` 是这个函数拥有所有权的。
//
unsafe {
copy_nonoverlapping(&src as *const T as *const u8, dst as *mut u8, mem::size_of::<T>());
// 我们直接调用内部函数以避免在生成的代码中进行函数调用。
intrinsics::forget(src);
}
}
/// 对 `src` 的值进行易失性读取,而无需移动它。这将使 `src` 中的内存保持不变。
///
/// 易失性操作旨在作用于 I/O 存储器,并保证编译器不会在其他易失性操作中对易失性操作进行清除或重新排序。
///
/// # Notes
///
/// Rust 当前没有严格和正式定义的内存模型,因此 "volatile" 此处所指的确切语义会随时间而变化。
/// 话虽如此,其语义几乎总是以与 [C11 对 volatile 的定义][c11] 相似的方式结束。
///
/// 编译器不应更改易失性存储器操作的相对顺序或数量。
/// 但是,零大小类型 (例如,如果将零大小类型传递给 `read_volatile`) 上的易失性存储器操作为无操作,可以忽略。
///
/// [c11]: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf
///
/// # Safety
///
/// 如果违反以下任一条件,则行为是未定义的:
///
/// * `src` 必须是 [有效的][valid] 才能读取。
///
/// * `src` 必须正确对齐。
///
/// * `src` 必须指向 `T` 类型的正确初始化值。
///
/// 与 [`read`] 一样,无论 `T` 是否为 [`Copy`],`read_volatile` 都会创建 `T` 的按位副本。
/// 如果 `T` 不是 [`Copy`],则同时使用返回值和 `*src` 处的值都可以 [违反内存安全][read-ownership]。
/// 但是,几乎可以肯定地将非 [`Copy`] 类型存储在易失性存储器中。
///
/// 请注意,即使 `T` 的大小为 `0`,指针也必须非空且正确对齐。
///
/// [valid]: self#safety
/// [read-ownership]: read#ownership-of-the-returned-value
///
/// 就像在 C 语言中一样,操作是否易失性与涉及从多个线程进行并发访问的问题无关。在这方面,易失性访问的行为与非原子访问完全相同。
///
/// 特别是,`read_volatile` 与任何对同一位置的写操作之间的争夺是未定义的行为。
///
/// # Examples
///
/// 基本用法:
///
/// ```
/// let x = 12;
/// let y = &x as *const i32;
///
/// unsafe {
/// assert_eq!(std::ptr::read_volatile(y), 12);
/// }
/// ```
///
///
///
///
///
///
///
///
///
///
///
#[inline]
#[stable(feature = "volatile", since = "1.9.0")]
#[cfg_attr(miri, track_caller)] // 即使没有 panic,这也有助于 Miri 回溯
pub unsafe fn read_volatile<T>(src: *const T) -> T {
// SAFETY: 调用者必须遵守 `volatile_load` 的安全保证。
unsafe {
assert_unsafe_precondition!(
"ptr::read_volatile requires that the pointer argument is aligned and non-null",
[T](src: *const T) => is_aligned_and_not_null(src)
);
intrinsics::volatile_load(src)
}
}
/// 使用给定值对存储单元执行易失性写操作,而无需读取或丢弃旧值。
///
/// 易失性操作旨在作用于 I/O 存储器,并保证编译器不会在其他易失性操作中对易失性操作进行清除或重新排序。
///
/// `write_volatile` 不会丢弃 `dst` 的内容。这是安全的,但可能会泄漏分配或资源,因此应注意不要覆盖应丢弃的对象。
///
/// 此外,它不会丢弃 `src`。在语义上,`src` 被移到 `dst` 指向的位置。
///
/// # Notes
///
/// Rust 当前没有严格和正式定义的内存模型,因此 "volatile" 此处所指的确切语义会随时间而变化。
/// 话虽如此,其语义几乎总是以与 [C11 对 volatile 的定义][c11] 相似的方式结束。
///
/// 编译器不应更改易失性存储器操作的相对顺序或数量。
/// 但是,零大小类型 (例如,如果将零大小类型传递给 `write_volatile`) 上的易失性存储器操作为无操作,可以忽略。
///
/// [c11]: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf
///
/// # Safety
///
/// 如果违反以下任一条件,则行为是未定义的:
///
/// * `dst` 必须是 [有效的][valid] 才能写入。
///
/// * `dst` 必须正确对齐。
///
/// 请注意,即使 `T` 的大小为 `0`,指针也必须非空且正确对齐。
///
/// [valid]: self#safety
///
/// 就像在 C 语言中一样,操作是否易失性与涉及从多个线程进行并发访问的问题无关。在这方面,易失性访问的行为与非原子访问完全相同。
///
/// 特别是,`write_volatile` 与同一位置上的任何其他操作 (读取或写入) 之间的争夺是未定义的行为。
///
/// # Examples
///
/// 基本用法:
///
/// ```
/// let mut x = 0;
/// let y = &mut x as *mut i32;
/// let z = 12;
///
/// unsafe {
/// std::ptr::write_volatile(y, z);
/// assert_eq!(std::ptr::read_volatile(y), 12);
/// }
/// ```
///
///
///
///
///
///
///
///
///
///
///
///
#[inline]
#[stable(feature = "volatile", since = "1.9.0")]
#[cfg_attr(miri, track_caller)] // 即使没有 panic,这也有助于 Miri 回溯
pub unsafe fn write_volatile<T>(dst: *mut T, src: T) {
// SAFETY: 调用者必须遵守 `volatile_store` 的安全保证。
unsafe {
assert_unsafe_precondition!(
"ptr::write_volatile requires that the pointer argument is aligned and non-null",
[T](dst: *mut T) => is_aligned_and_not_null(dst)
);
intrinsics::volatile_store(dst, src);
}
}
/// 对齐指针 `p`。
///
/// 计算必须应用于指针 `p` 的偏移量 (根据 `size_of::<T>()` 步长的元素),以便指针 `p` 与 `a` 对齐。
///
/// # Safety
/// `a` 必须是 2 的幂。
///
/// # Notes
/// 此实现已针对非 panic 进行了精心设计。到 panic 是 UB。
/// 此处唯一可以进行的更改是 `INV_TABLE_MOD_16` 及其关联常量的更改。
///
/// 如果我们决定可以使用不是二次幂的 `a` 来调用内部函数,那么可能更谨慎的做法是只更改为一个简单的实现,而不是尝试调整它以适应这种更改。
///
///
/// 如有任何疑问,请发送至 @nagisa。
///
///
///
#[lang = "align_offset"]
pub(crate) const unsafe fn align_offset<T: Sized>(p: *const T, a: usize) -> usize {
// FIXME(#75598): 直接使用这些内部函数在 opt-level 显着提高 codegen <=
// 1,其中未内联这些操作的方法版本。
use intrinsics::{
assume, cttz_nonzero, exact_div, mul_with_overflow, unchecked_rem, unchecked_shl,
unchecked_shr, unchecked_sub, wrapping_add, wrapping_mul, wrapping_sub,
};
/// 计算 `x` 模 `m` 的乘法模逆。
///
/// 此实现是针对 `align_offset` 量身定制的,并具有以下先决条件:
///
/// * `m` 是二的幂;
/// * `x < m`; (如果使用 `x ≥ m`,请改为传入 `x % m`)
///
/// 此函数的实现不得为 panic。Ever.
#[inline]
const unsafe fn mod_inv(x: usize, m: usize) -> usize {
/// 乘模逆矩阵模 2⁴=16。
///
/// 注意,该表不包含不存在反值的值 (例如,对于 `0⁻¹ mod 16`,`2⁻¹ mod 16` 等)。
///
const INV_TABLE_MOD_16: [u8; 8] = [1, 11, 13, 7, 9, 3, 5, 15];
/// `INV_TABLE_MOD_16` 的模数。
const INV_TABLE_MOD: usize = 16;
// SAFETY: `m` 必须为 2 的幂,因此不能为零。
let m_minus_one = unsafe { unchecked_sub(m, 1) };
let mut inverse = INV_TABLE_MOD_16[(x & (INV_TABLE_MOD - 1)) >> 1] as usize;
let mut mod_gate = INV_TABLE_MOD;
// 我们使用以下公式迭代 "up":
//
// $$ xy ≡ 1 (mod 2ⁿ) → xy (2 - xy) ≡ 1 (mod 2²ⁿ) $$
//
// 此应用程序至少需要应用到 `2²ⁿ ≥ m`,此时我们可以通过取 `inverse mod m` 最终将计算减少到我们想要的 `m`。
//
//
// 这个计算是 `O(log log m)`,也就是说,在 64 位机器上,这个循环总是最多完成 4 次迭代。
//
loop {
// y = y * (2 - xy) mod n
//
// 注意,这里我们有意使用包装操作 - 原始公式使用减法 `mod n`。
// 改用 `mod usize::MAX` 完全可以,因为无论如何我们将结果 `mod n` 放在最后。
//
//
if mod_gate >= m {
break;
}
inverse = wrapping_mul(inverse, wrapping_sub(2usize, wrapping_mul(x, inverse)));
let (new_gate, overflow) = mul_with_overflow(mod_gate, mod_gate);
if overflow {
break;
}
mod_gate = new_gate;
}
inverse & m_minus_one
}
let stride = mem::size_of::<T>();
// SAFETY: 这只是一个内联的 `p.addr()` (不是 `const fn`,所以我们不能调用它)。
// 在 const eval 期间,我们,钩子,这个函数以确保指针永远不会有出处,从而发出这个声音。
//
//
let addr: usize = unsafe { mem::transmute(p) };
// SAFETY: `a` 为 2 的幂,因此非零。
let a_minus_one = unsafe { unchecked_sub(a, 1) };
if stride == 0 {
// SPECIAL_CASE: 处理 0 大小的类型。
// 无论我们步进多少次,地址都将保持不变,因此除非指针已经对齐,否则没有偏移量能够对齐指针。
// 这个分支将被优化,因为 `stride` 在编译时是已知的。
let p_mod_a = addr & a_minus_one;
return if p_mod_a == 0 { 0 } else { usize::MAX };
}
// SAFETY: `stride == 0` 案例已由上述特例处理。
let a_mod_stride = unsafe { unchecked_rem(a, stride) };
if a_mod_stride == 0 {
// SPECIAL_CASE: 在 `a` 可被 `stride` 整除的情况下,对齐指针的字节偏移可以通过 `-p (mod a)` 更简单地计算。
// 如果字节偏移量不是 `stride` 的倍数,则输入指针未对齐,并且没有指针偏移量将能够产生与指定 `a` 对齐的 `p`。
//
// 朴素的 `-p (mod a)` 等式抑制了 LLVM 选择像 `lea` 这样的指令的能力。我们改为计算 `(round_up_to_next_alignment(p, a) - p)`。
// 这将围绕承载重新分配操作,但对 `and` 指令的悲观程度足以使 LLVM 能够利用它所知道的各种优化。
//
// LLVM 在这里特别好地处理分支。
// 如果需要在运行时评估此分支,它将以无分支方式生成掩码 `if addr_mod_stride == 0 { 0 } else { usize::MAX }`,然后将其与 `-p mod a` 计算产生的任何结果进行按位或运算。
//
//
//
//
//
//
let aligned_address = wrapping_add(addr, a_minus_one) & wrapping_sub(0, a);
let byte_offset = wrapping_sub(aligned_address, addr);
// FIXME: 删除 <https://github.com/llvm/llvm-project/issues/62502> 之后的假设
// SAFETY: `-a` 屏蔽只能影响低位,因此减少的值不能超过 `a-1`,因此即使中间值可能已经回绕,byte_offset 始终在 `[0, a)` 中。
//
//
unsafe { assume(byte_offset < a) };
// SAFETY: `stride == 0` 案例已由上述特例处理。
let addr_mod_stride = unsafe { unchecked_rem(addr, stride) };
return if addr_mod_stride == 0 {
// SAFETY: `stride` 非零。
// 这也保证了精确划分,因为 addr 已被验证与原始类型的对齐要求对齐。
unsafe { exact_div(byte_offset, stride) }
} else {
usize::MAX
};
}
// GENERAL_CASE: 从这里开始,我们正在处理 `addr` 可能未对齐的非常一般的情况,`stride` 和 `a` 之间没有我们可以利用的明显关系等。
//
// 与上述特殊情况相比,这种情况产生的机器代码质量不是特别高。
// 考虑到本案必须处理的情况,此处生成的代码仍属于奇迹领域。
//
// SAFETY: a 是 2 的幂,因此非零。stride == 0 情况已在上面处理。
// FIXME(const-hack) 替换为最小值
let gcdpow = unsafe {
let x = cttz_nonzero(stride);
let y = cttz_nonzero(a);
if x < y { x } else { y }
};
// SAFETY: gcdpow 有一个上限,最多是 usize 中的位数。
let gcd = unsafe { unchecked_shl(1usize, gcdpow) };
// SAFETY: gcd 总是大于或等于 1.
if addr & unsafe { unchecked_sub(gcd, 1) } == 0 {
// 该分支求解以下线性同余方程:
//
// ` p + so = 0 mod a `
//
// 这里的 `p` 是指针值,`s`-`T` 的步幅,`T` 中的 `o` 偏移量,以及 `a` - 请求的对齐方式。
//
// 使用 `g = gcd(a, s)`,并且上面的条件断言 `p` 也可以被 `g` 整除,我们可以表示 `a' = a/g`,`s' = s/g`,`p' = p/g`,那么它等效于:
//
// ` p' + s'o = 0 mod a' `
// ` o = (a' - (p' mod a')) * (s'^-1 mod a') `
//
// 第一项是 "the relative alignment of `p` to `a`" (除以 `g`),第二项是 "how does incrementing `p` by `s` bytes change the relative alignment of `p`" (再次除以 `g`)。
// 如果 `a` 和 `s` 不是互质的,则 `g` 的除法对于使逆结构良好是必要的。
//
// 此外,此解决方案产生的结果不是 "minimal",因此必须获得结果 `o mod lcm(s, a)`。此 `lcm(s, a)` 与 `a'` 相同。
//
//
//
//
//
// SAFETY: `gcdpow` 的上限不大于 `a` 的尾随 0 位的数量。
//
let a2 = unsafe { unchecked_shr(a, gcdpow) };
// SAFETY: `a2` 不为零。
// 将 `a` 移位 `gcdpow` 不能移出 `a` 中的任何设置位 (其中只有一位)。
let a2minus1 = unsafe { unchecked_sub(a2, 1) };
// SAFETY: `gcdpow` 的上限不大于 `a` 的尾随 0 位的数量。
//
let s2 = unsafe { unchecked_shr(stride & a_minus_one, gcdpow) };
// SAFETY: `gcdpow` 的上限不大于 `a` 的尾随 0 位的数量。
// 此外,减法不会溢出,因为 `a2 = a >> gcdpow` 将始终严格大于 `(p % a) >> gcdpow`。
//
let minusp2 = unsafe { unchecked_sub(a2, unchecked_shr(addr & a_minus_one, gcdpow)) };
// SAFETY: 如上所述,`a2` 是 2 的幂。
// `s2` 严格小于 `a2`,因为 `(s % a) >> gcdpow` 严格小于 `a >> gcdpow`。
return wrapping_mul(minusp2, unsafe { mod_inv(s2, a2) }) & a2minus1;
}
// 根本无法对齐。
usize::MAX
}
/// 比较裸指针是否相等。
///
/// 这与使用 `==` 运算符相同,但泛型较少:
/// 参数必须是 `*const T` 裸指针,而不是任何实现 `PartialEq` 的东西。
///
/// 这可用于按地址比较 `&T` 引用 (隐式强制为 `*const T`),而不是比较它们指向的值 (`PartialEq for &T` 实现的作用)。
///
/// 在比较宽指针时,地址和元数据都被测试是否相等。
/// 但是,请注意比较 trait 对象指针 (`*const dyn Trait`) 是不可靠的: 指向相同底层类型的值的指针可以比较不相等 (因为 vtables 在多个 codegen 单元中重复),而指向*不同*底层类型的值的指针可以比较相等 (因为相同 vtables 可以在 codegen 元中进行重复数据删除)。
///
///
/// # Examples
///
/// ```
/// use std::ptr;
///
/// let five = 5;
/// let other_five = 5;
/// let five_ref = &five;
/// let same_five_ref = &five;
/// let other_five_ref = &other_five;
///
/// assert!(five_ref == same_five_ref);
/// assert!(ptr::eq(five_ref, same_five_ref));
///
/// assert!(five_ref == other_five_ref);
/// assert!(!ptr::eq(five_ref, other_five_ref));
/// ```
///
/// 切片还通过它们的长度 (胖指针) 进行比较:
///
/// ```
/// let a = [1, 2, 3];
/// assert!(std::ptr::eq(&a[..3], &a[..3]));
/// assert!(!std::ptr::eq(&a[..2], &a[..3]));
/// assert!(!std::ptr::eq(&a[0..2], &a[1..3]));
/// ```
///
///
///
///
///
#[stable(feature = "ptr_eq", since = "1.17.0")]
#[inline(always)]
pub fn eq<T: ?Sized>(a: *const T, b: *const T) -> bool {
a == b
}
/// 散列一个裸指针。
///
/// 这可用于通过其地址而不是其指向的值 (`Hash for &T` 实现的作用) 对 `&T` 引用 (隐式强制为 `*const T`) 进行哈希处理。
///
///
/// # Examples
///
/// ```
/// use std::collections::hash_map::DefaultHasher;
/// use std::hash::{Hash, Hasher};
/// use std::ptr;
///
/// let five = 5;
/// let five_ref = &five;
///
/// let mut hasher = DefaultHasher::new();
/// ptr::hash(five_ref, &mut hasher);
/// let actual = hasher.finish();
///
/// let mut hasher = DefaultHasher::new();
/// (five_ref as *const i32).hash(&mut hasher);
/// let expected = hasher.finish();
///
/// assert_eq!(actual, expected);
/// ```
///
#[stable(feature = "ptr_hash", since = "1.35.0")]
pub fn hash<T: ?Sized, S: hash::Hasher>(hashee: *const T, into: &mut S) {
use crate::hash::Hash;
hashee.hash(into);
}
#[stable(feature = "fnptr_impls", since = "1.4.0")]
impl<F: FnPtr> PartialEq for F {
#[inline]
fn eq(&self, other: &Self) -> bool {
self.addr() == other.addr()
}
}
#[stable(feature = "fnptr_impls", since = "1.4.0")]
impl<F: FnPtr> Eq for F {}
#[stable(feature = "fnptr_impls", since = "1.4.0")]
impl<F: FnPtr> PartialOrd for F {
#[inline]
fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
self.addr().partial_cmp(&other.addr())
}
}
#[stable(feature = "fnptr_impls", since = "1.4.0")]
impl<F: FnPtr> Ord for F {
#[inline]
fn cmp(&self, other: &Self) -> Ordering {
self.addr().cmp(&other.addr())
}
}
#[stable(feature = "fnptr_impls", since = "1.4.0")]
impl<F: FnPtr> hash::Hash for F {
fn hash<HH: hash::Hasher>(&self, state: &mut HH) {
state.write_usize(self.addr() as _)
}
}
#[stable(feature = "fnptr_impls", since = "1.4.0")]
impl<F: FnPtr> fmt::Pointer for F {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
fmt::pointer_fmt_inner(self.addr() as _, f)
}
}
#[stable(feature = "fnptr_impls", since = "1.4.0")]
impl<F: FnPtr> fmt::Debug for F {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
fmt::pointer_fmt_inner(self.addr() as _, f)
}
}
/// 创建一个 `const` 裸指针到一个位置,而无需创建中间引用。
///
/// 仅当指针正确对齐并指向初始化数据时,才允许使用 `&`/`&mut` 创建引用。
/// 对于那些不满足要求的情况,应改用裸指针。
/// 但是,`&expr as *const _` 在将其强制转换为裸指针之前会创建一个引用,并且该引用与所有其他引用都遵循相同的规则。
///
/// 该宏可以创建一个裸指针,而无需先创建一个引用。
///
/// 但是请注意,`addr_of!(expr)` 中的 `expr` 仍受所有常规规则的约束。
/// 特别是,`addr_of!(*ptr::null())` 是未定义行为,因为它解引用空指针。
///
/// # Example
///
/// ```
/// use std::ptr;
///
/// #[repr(packed)]
/// struct Packed {
/// f1: u8,
/// f2: u16,
/// }
///
/// let packed = Packed { f1: 1, f2: 2 };
/// // `&packed.f2` 会创建一个未对齐的引用,因此是未定义的行为!
/// let raw_f2 = ptr::addr_of!(packed.f2);
/// assert_eq!(unsafe { raw_f2.read_unaligned() }, 2);
/// ```
///
/// 有关如何创建指向未初始化数据的指针,请参见 [`addr_of_mut`]。
/// 用 `addr_of` 这样做没有多大意义,因为人们只能读取数据,这将是未定义行为。
///
///
///
#[stable(feature = "raw_ref_macros", since = "1.51.0")]
#[rustc_macro_transparency = "semitransparent"]
#[allow_internal_unstable(raw_ref_op)]
pub macro addr_of($place:expr) {
&raw const $place
}
/// 创建一个 `mut` 裸指针到一个位置,而无需创建中间引用。
///
/// 仅当指针正确对齐并指向初始化数据时,才允许使用 `&`/`&mut` 创建引用。
/// 对于那些不满足要求的情况,应改用裸指针。
/// 但是,`&mut expr as *mut _` 在将其强制转换为裸指针之前会创建一个引用,并且该引用与所有其他引用都遵循相同的规则。
///
/// 该宏可以创建一个裸指针,而无需先创建一个引用。
///
/// 但请注意,`addr_of_mut!(expr)` 中的 `expr` 仍受所有常规规则的约束。
/// 特别是,`addr_of_mut!(*ptr::null_mut())` 是未定义行为,因为它解引用空指针。
///
/// # Examples
///
/// **创建指向未对齐数据的指针:**
///
/// ```
/// use std::ptr;
///
/// #[repr(packed)]
/// struct Packed {
/// f1: u8,
/// f2: u16,
/// }
///
/// let mut packed = Packed { f1: 1, f2: 2 };
/// // `&mut packed.f2` 会创建一个未对齐的引用,因此是未定义的行为!
/// let raw_f2 = ptr::addr_of_mut!(packed.f2);
/// unsafe { raw_f2.write_unaligned(42); }
/// assert_eq!({packed.f2}, 42); // `{...}` 强制复制字段而不是创建引用。
/// ```
///
/// **创建指向未初始化数据的指针:**
///
/// ```rust
/// use std::{ptr, mem::MaybeUninit};
///
/// struct Demo {
/// field: bool,
/// }
///
/// let mut uninit = MaybeUninit::<Demo>::uninit();
/// // `&uninit.as_mut().field` 会创建一个对未初始化的 `bool` 的引用,因此是未定义的行为!
/////
/// let f1_ptr = unsafe { ptr::addr_of_mut!((*uninit.as_mut_ptr()).field) };
/// unsafe { f1_ptr.write(true); }
/// let init = unsafe { uninit.assume_init() };
/// ```
///
///
#[stable(feature = "raw_ref_macros", since = "1.51.0")]
#[rustc_macro_transparency = "semitransparent"]
#[allow_internal_unstable(raw_ref_op)]
pub macro addr_of_mut($place:expr) {
&raw mut $place
}