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
}