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
//! 多生产者,单消费者 FIFO 队列通信原语。
//!
//! 该模块通过通道提供基于消息的通信,具体定义为以下三种类型:
//!
//! * [`Sender`]
//! * [`SyncSender`]
//! * [`Receiver`]
//!
//! [`Sender`] 或 [`SyncSender`] 用于将数据发送到 [`Receiver`]。
//! 两个发送者都是可克隆的 (multi-producer),因此许多线程可以同时发送到一个接收者 (single-consumer)。
//!
//! 这些通道有两种口味:
//!
//! 1. 异步,无限缓冲的通道。
//! [`channel`] 函数将返回 `(Sender, Receiver)` 元组,其中所有发送都是异步的 (它们从不阻塞)。
//! 通道在概念上具有无限的缓冲区。
//!
//! 2. 同步的有界通道。
//! [`sync_channel`] 函数将返回 `(SyncSender, Receiver)` 元组,其中待处理消息的存储是固定大小的预分配缓冲区。
//! 所有的发送都将被阻塞,直到有可用的缓冲区空间。
//! 请注意,允许的界限为 0,从而使通道成为 "rendezvous" 通道,每个发送者在该通道上原子地将消息传递给接收者。
//!
//! [`send`]: Sender::send
//!
//! ## Disconnection
//!
//! 通道上的发送和接收操作都将返回 [`Result`],指示该操作是否成功。
//! 不成功的操作通常通过将其丢弃在相应线程中来指示具有 "hung up" 的通道的另一半。
//!
//! 释放通道的一半后,大多数操作将不再继续进行,因此将返回 [`Err`]。
//! 许多应用程序将继续对该模块返回的结果进行 [`unwrap`] 处理,如果一个线程意外死亡,则会导致线程之间传播失败。
//!
//!
//! [`unwrap`]: Result::unwrap
//!
//! # Examples
//!
//! 简单用法:
//!
//! ```
//! use std::thread;
//! use std::sync::mpsc::channel;
//!
//! // 创建一个简单的流通道
//! let (tx, rx) = channel();
//! thread::spawn(move|| {
//!     tx.send(10).unwrap();
//! });
//! assert_eq!(rx.recv().unwrap(), 10);
//! ```
//!
//! 共享用法:
//!
//! ```
//! use std::thread;
//! use std::sync::mpsc::channel;
//!
//! // 创建一个可以从许多线程一起发送的共享通道,其中 tx 是发送一半 (用于传输的 tx),rx 是接收一半 (用于接收的 rx)。
//! //
//! //
//! let (tx, rx) = channel();
//! for i in 0..10 {
//!     let tx = tx.clone();
//!     thread::spawn(move|| {
//!         tx.send(i).unwrap();
//!     });
//! }
//!
//! for _ in 0..10 {
//!     let j = rx.recv().unwrap();
//!     assert!(0 <= j && j < 10);
//! }
//! ```
//!
//! 传播 panics:
//!
//! ```
//! use std::sync::mpsc::channel;
//!
//! // 调用 recv() 将返回错误,因为通道已挂起 (或已释放)
//! //
//! let (tx, rx) = channel::<i32>();
//! drop(tx);
//! assert!(rx.recv().is_err());
//! ```
//!
//! 同步通道:
//!
//! ```
//! use std::thread;
//! use std::sync::mpsc::sync_channel;
//!
//! let (tx, rx) = sync_channel::<i32>(0);
//! thread::spawn(move|| {
//!     // 这将等待父线程开始接收
//!     tx.send(53).unwrap();
//! });
//! rx.recv().unwrap();
//! ```
//!
//! 无限接收循环:
//!
//! ```
//! use std::sync::mpsc::sync_channel;
//! use std::thread;
//!
//! let (tx, rx) = sync_channel(3);
//!
//! for _ in 0..3 {
//!     // 这里没有线程和克隆也是一样的,因为仍然会剩下一个 `tx`。
//!     //
//!     let tx = tx.clone();
//!     // 克隆的 tx 丢弃在线程中
//!     thread::spawn(move || tx.send("ok").unwrap());
//! }
//!
//! // 删除最后一个发送者停止 `rx` 等待消息。
//! // 如果我们将其注释掉,程序将无法完成。
//! // 所有需要为 `rx` 排除 `tx` 才能拥有 `Err`。
//! drop(tx);
//!
//! // 无限接收者等待所有发送者完成。
//! while let Ok(msg) = rx.recv() {
//!     println!("{}", msg);
//! }
//!
//! println!("completed");
//! ```
//!
//!
//!
//!
//!
//!
//!
//!

#![stable(feature = "rust1", since = "1.0.0")]

#[cfg(all(test, not(target_os = "emscripten")))]
mod tests;

#[cfg(all(test, not(target_os = "emscripten")))]
mod sync_tests;

// Rust 的通道实现的工作方式的描述
//
// 通道应该是 Rust 中使用的所有其他并发原语的基本构建块。因此,通道类型需要高度优化,灵活并且足够广泛以在任何地方使用。
//
// 所有通道的实现选择都将基于无锁数据结构。因此,通道本身也是无锁数据结构。
// 与使用无锁代码一样,这是一个非常 "here be dragons" 的领域,特别是因为我不知道有任何关于这些风格的通道的学术论文。
//
// ## 风格的通道
//
// 从该库的使用者的角度来看,只有一种通道。此通道可以用作流,并可以克隆以允许多个发送者。
// 然而,在幕后,实际上有三种风格的通道在起作用。
//
// * Flavor::Oneshots - 这些通道针对单次发送用例进行了高度优化。它们包含尽可能少的原子,并且涉及一个且恰好是一个分配。
// * 流 - 这些通道针对非共享用例进行了优化。他们使用了一个更适合此用例的不同并发队列。这种风格的通道初始分配没有得到优化。
// * 共享 - 这是此模块提供的最通用的通道形式,即具有多个发送者的通道。这种类型已尽可能地进行了优化,但是前面提到的两种类型在其用例方面要快得多。
//
// ## 并发队列
//
// Rust 的 Sender/Receiver 类型的基本思想是 send() 永远不会阻塞,但 recv() 显然会阻塞。这意味着在后台必须有一些共享和并发队列保存所有实际数据。
//
// 对于两种通道,还使用两种队列。
// 我们选择使用一位著名作者的队列 (简称为 SPSC 和 MPSC) 的队列 (单生产者、单消费者和多生产者、单消费者)。
// SPSC 队列用于流,而 MPSC 队列用于共享通道。
//
// ### SPSC 优化
//
// 在线找到的 SPSC 队列实质上是节点的链表,其中一半节点是 "数据队列",另一半节点是未使用节点的缓存。
// 使用未使用的节点,这样就不需要在每个 push() 上进行分配,并且不需要在每个 pop() 上进行分配。
//
// 然而,正如在网上发现的那样,节点的缓存是无限大的。这意味着,如果某个通道在其生命周期的某一点上有 50k 项,那么该队列将始终具有 50k 项的容量。
// 我认为这是对实现的不必要限制,因此我更改了队列以有选择地对缓存大小进行限制。
//
// 默认情况下,流将具有无限制的 SPSC 队列,且缓存大小较小。
// 希望缓存仍然足够大,可以进行非常快速的 send() 操作,而又不要太大,以至于数以百万计的通道可以一次共存。
//
// ### MPSC 优化
//
// 目前,MPSC 队列尚未优化。像 SPSC 队列一样,它使用引擎盖下的链表来获取其无限制的内容,但是我并没有花太多精力来使节点的缓存类似于 SPSC 队列。
//
// 现在,我认为这是 "ok",因为共享通道不是最常见的类型,但是不久之后,我们不妨重新访问此队列选择,并确定另一个用于共享通道的后端存储的候选对象。
//
// ## 实现概述
//
// 既然使用的并发队列有一些背景知识,那么有必要进一步详细介绍通道本身。send/recv 的基本伪代码为:
//
//      send(t)                             recv() queue.push(t)                       return if queue.pop() if increment() == -1                deschedule { wakeup()                            if decrement() > 0
//                                                cancel_deschedule()
//                                            }
//                                            queue.pop()
//
// 如前所述,此实现中没有锁,仅使用原子指令。
//
// ### 内部原子计数器
//
// 每个通道都有一个共享的计数器,每个通道都有一个计数器,以跟踪队列的大小。该计数器用于接收方终止调度,并知道何时在发送方唤醒。
//
// 从伪代码中可以看出,发送者将增加该计数,接收者将减少该计数。其背后的理论是,如果发送者看到
// -1 计数,它将唤醒接收器,如果接收器看到 1+ 计数,那么它就不需要阻塞。
//
// recv() 方法从 pop() 开始调用,如果成功,则需要减少计数。这是一个至关重要的实现细节,此减量不会 * 发生在共享计数器上。
// 如果是这样,那么在没有等待接收者的情况下,计数器可能会变得非常负数,在这种情况下,发送者将不得不确定何时真正适合唤醒接收者。
//
//
// 取而代之的是,"steal count" 被分开跟踪 (不是原子地,因为它仅由接收者使用),然后在调度时将 decrement() 调用将最近的所有窃取都归为一个大的递减。
//
// 这意味着如果发送方看到 -1 计数,那么肯定有一个等待者在等!
//
// ## 原生实现
//
// 这些通道的主要目标是在运行时上上下下无缝工作。
// 以前的所有竞争状态都用调度程序表述 (显然,没有运行时就无法使用)。
//
// 目前,通道的原生用法 (在运行时关闭) 将回退到 mutexes/cond 变量上进行 descheduling/atomic 决策。
// 无争用路径仍然是完全无锁的,上面的 "deschedule" 块被互斥锁包围,而 "wakeup" 块涉及获取互斥锁并在条件变量上发出信号。
//
// ## Select
//
// 能够支持通过通道进行选择极大地影响了该设计,选择不仅需要在运行时内部进行,而且还需要在运行时外部进行。
//
// 该实现非常简单。select() 的目标不是返回某些数据,而只是返回哪个通道可以无阻塞地接收数据。
// 该实现实质上是整个阻塞进程,随后在其唤醒后立即进行递增。
// 取消进程涉及一个增量,并交换出 to_wake 来获取要解锁的线程的所有权。
//
// 可悲的是,当前的实现需要多个分配,因此我已经看到 select() 的吞吐量比应该的要差得多。
// 我认为,为了支持更高效的 select(),不需要对这些通道进行任何根本性的更改。
//
// FIXME: Select 现在已删除,因此可以清除这些因素!
//
// # Conclusion
//
// 现在,您已经看到了我发现并尝试解决的所有问题,下面是为您找到更多代码的代码!
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//

use crate::cell::UnsafeCell;
use crate::error;
use crate::fmt;
use crate::mem;
use crate::sync::Arc;
use crate::time::{Duration, Instant};

mod blocking;
mod mpsc_queue;
mod oneshot;
mod shared;
mod spsc_queue;
mod stream;
mod sync;

mod cache_aligned;

/// Rust 的 [`channel`] (或 [`sync_channel`]) 类型的接收一半。
/// 这一半只能由一个线程拥有。
///
/// 可以使用 [`recv`] 检索发送到通道的消息。
///
/// [`recv`]: Receiver::recv
///
/// # Examples
///
/// ```rust
/// use std::sync::mpsc::channel;
/// use std::thread;
/// use std::time::Duration;
///
/// let (send, recv) = channel();
///
/// thread::spawn(move || {
///     send.send("Hello world!").unwrap();
///     thread::sleep(Duration::from_secs(2)); // 阻塞两秒钟
///     send.send("Delayed for 2 seconds").unwrap();
/// });
///
/// println!("{}", recv.recv().unwrap()); // 立即收到
/// println!("Waiting...");
/// println!("{}", recv.recv().unwrap()); // 2 秒后收到
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "Receiver")]
pub struct Receiver<T> {
    inner: UnsafeCell<Flavor<T>>,
}

// 接收者端口可以在任何地方发送,只要它不用于接收不可发送的东西即可。
//
#[stable(feature = "rust1", since = "1.0.0")]
unsafe impl<T: Send> Send for Receiver<T> {}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> !Sync for Receiver<T> {}

/// [`iter`] 在 [`Receiver`] 上创建的消息上的迭代器。
///
/// 每当调用 [`next`],等待新消息时,此迭代器将阻塞,并且在相应的通道挂起时,将返回 [`None`]。
///
///
/// [`iter`]: Receiver::iter
/// [`next`]: Iterator::next
///
/// # Examples
///
/// ```rust
/// use std::sync::mpsc::channel;
/// use std::thread;
///
/// let (send, recv) = channel();
///
/// thread::spawn(move || {
///     send.send(1u8).unwrap();
///     send.send(2u8).unwrap();
///     send.send(3u8).unwrap();
/// });
///
/// for x in recv.iter() {
///     println!("Got: {}", x);
/// }
/// ```
///
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Debug)]
pub struct Iter<'a, T: 'a> {
    rx: &'a Receiver<T>,
}

/// 尝试产生 [`try_iter`] 创建的 [`Receiver`] 的所有挂起值的迭代器。
///
/// 当没有剩余的挂起的值或对应的通道已挂断时,将返回 [`None`]。
///
///
/// 该迭代器永远不会阻塞调用者,以等待数据可用。
/// 相反,它将返回 [`None`]。
///
/// [`try_iter`]: Receiver::try_iter
///
/// # Examples
///
/// ```rust
/// use std::sync::mpsc::channel;
/// use std::thread;
/// use std::time::Duration;
///
/// let (sender, receiver) = channel();
///
/// // 缓冲区什么都没有了
/// assert!(receiver.try_iter().next().is_none());
/// println!("Nothing in the buffer...");
///
/// thread::spawn(move || {
///     sender.send(1).unwrap();
///     sender.send(2).unwrap();
///     sender.send(3).unwrap();
/// });
///
/// println!("Going to sleep...");
/// thread::sleep(Duration::from_secs(2)); // 阻塞两秒钟
///
/// for x in receiver.try_iter() {
///     println!("Got: {}", x);
/// }
/// ```
///
#[stable(feature = "receiver_try_iter", since = "1.15.0")]
#[derive(Debug)]
pub struct TryIter<'a, T: 'a> {
    rx: &'a Receiver<T>,
}

/// [`Receiver`] 上由消息接收者拥有的迭代器,该迭代器由 **Receiver::into_iter** 创建。
///
/// 每当调用 [`next`],等待新消息时,此迭代器将阻塞,如果相应的通道已挂起,则将返回 [`None`]。
///
///
/// [`next`]: Iterator::next
///
/// # Examples
///
/// ```rust
/// use std::sync::mpsc::channel;
/// use std::thread;
///
/// let (send, recv) = channel();
///
/// thread::spawn(move || {
///     send.send(1u8).unwrap();
///     send.send(2u8).unwrap();
///     send.send(3u8).unwrap();
/// });
///
/// for x in recv.into_iter() {
///     println!("Got: {}", x);
/// }
/// ```
///
///
#[stable(feature = "receiver_into_iter", since = "1.1.0")]
#[derive(Debug)]
pub struct IntoIter<T> {
    rx: Receiver<T>,
}

/// Rust 的异步 [`channel`] 类型的发送一半。
/// 这一半只能由一个线程拥有,但可以克隆以发送给其他线程。
///
/// 可以使用 [`send`] 通过此通道发送消息。
///
/// Note: 所有发送者 (原始和克隆) 都需要被接收者去除,以停止阻止接收带有 [`Receiver::recv`] 的消息。
///
///
/// [`send`]: Sender::send
///
/// # Examples
///
/// ```rust
/// use std::sync::mpsc::channel;
/// use std::thread;
///
/// let (sender, receiver) = channel();
/// let sender2 = sender.clone();
///
/// // 第一个线程拥有发送者
/// thread::spawn(move || {
///     sender.send(1).unwrap();
/// });
///
/// // 第二个线程拥有 sender2
/// thread::spawn(move || {
///     sender2.send(2).unwrap();
/// });
///
/// let msg = receiver.recv().unwrap();
/// let msg2 = receiver.recv().unwrap();
///
/// assert_eq!(3, msg + msg2);
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Sender<T> {
    inner: UnsafeCell<Flavor<T>>,
}

// 只要不用于发送不可发送的东西,发送端口就可以从一个地方发送到另一个地方。
//
#[stable(feature = "rust1", since = "1.0.0")]
unsafe impl<T: Send> Send for Sender<T> {}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> !Sync for Sender<T> {}

/// Rust 的同步 [`sync_channel`] 类型的发送一半。
///
/// 可以使用 [`send`] 或 [`try_send`] 通过此通道发送消息。
///
/// 如果内部缓冲区没有空间,[`send`] 将阻塞。
///
/// [`send`]: SyncSender::send
/// [`try_send`]: SyncSender::try_send
///
/// # Examples
///
/// ```rust
/// use std::sync::mpsc::sync_channel;
/// use std::thread;
///
/// // 创建一个缓冲区大小为 2 的 sync_channel
/// let (sync_sender, receiver) = sync_channel(2);
/// let sync_sender2 = sync_sender.clone();
///
/// // 第一个线程拥有 sync_sender
/// thread::spawn(move || {
///     sync_sender.send(1).unwrap();
///     sync_sender.send(2).unwrap();
/// });
///
/// // 第二个线程拥有 sync_sender2
/// thread::spawn(move || {
///     sync_sender2.send(3).unwrap();
///     // 由于缓冲区已满,线程现在将阻塞
///     println!("Thread unblocked!");
/// });
///
/// let mut msg;
///
/// msg = receiver.recv().unwrap();
/// println!("message {} received", msg);
///
/// // 现在将打印 "Thread unblocked!"
///
/// msg = receiver.recv().unwrap();
/// println!("message {} received", msg);
///
/// msg = receiver.recv().unwrap();
///
/// println!("message {} received", msg);
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub struct SyncSender<T> {
    inner: Arc<sync::Packet<T>>,
}

#[stable(feature = "rust1", since = "1.0.0")]
unsafe impl<T: Send> Send for SyncSender<T> {}

/// 从 **通道** 上的 [`Sender::send`] 或 [`SyncSender::send`] 函数返回错误。
///
/// 仅当通道的接收端断开连接时,发送操作才会失败,这意味着永远无法接收到数据。
/// 该错误包含作为有效载荷发送的数据,因此可以对其进行恢复。
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(PartialEq, Eq, Clone, Copy)]
pub struct SendError<T>(#[stable(feature = "rust1", since = "1.0.0")] pub T);

/// [`Receiver`] 上的 [`recv`] 函数返回错误。
///
/// 仅当 [`channel`] (或 [`sync_channel`]) 的发送半部断开连接时,[`recv`] 操作才会失败,这意味着将再也不会收到任何消息。
///
///
/// [`recv`]: Receiver::recv
///
#[derive(PartialEq, Eq, Clone, Copy, Debug)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct RecvError;

/// 该枚举是 [`try_recv`] 在调用时无法返回数据的可能原因的列表。
/// [`channel`] 和 [`sync_channel`] 都可能发生这种情况。
///
/// [`try_recv`]: Receiver::try_recv
///
#[derive(PartialEq, Eq, Clone, Copy, Debug)]
#[stable(feature = "rust1", since = "1.0.0")]
pub enum TryRecvError {
    /// 该 **通道** 当前为空,但 **发送者** 尚未断开连接,因此数据可能仍可用。
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    Empty,

    /// **通道** 的发送一半已断开,并且永远不会再收到任何数据。
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    Disconnected,
}

/// 该枚举是导致 [`recv_timeout`] 在调用时无法返回数据的可能错误的列表。
/// [`channel`] 和 [`sync_channel`] 都可能发生这种情况。
///
/// [`recv_timeout`]: Receiver::recv_timeout
///
#[derive(PartialEq, Eq, Clone, Copy, Debug)]
#[stable(feature = "mpsc_recv_timeout", since = "1.12.0")]
pub enum RecvTimeoutError {
    /// 该 **通道** 当前为空,但 **发送者** 尚未断开连接,因此数据可能仍可用。
    ///
    #[stable(feature = "mpsc_recv_timeout", since = "1.12.0")]
    Timeout,
    /// **通道** 的发送一半已断开,并且永远不会再收到任何数据。
    ///
    #[stable(feature = "mpsc_recv_timeout", since = "1.12.0")]
    Disconnected,
}

/// 此枚举是 [`try_send`] 方法可能的错误结果的列表。
///
///
/// [`try_send`]: SyncSender::try_send
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(PartialEq, Eq, Clone, Copy)]
pub enum TrySendError<T> {
    /// 无法在 [`sync_channel`] 上发送数据,因为它需要被调用者阻止发送数据。
    ///
    ///
    /// 如果这是一个缓冲的通道,则此时缓冲区已满。
    /// 如果这不是缓冲的通道,则没有 [`Receiver`] 可用于获取数据。
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    Full(#[stable(feature = "rust1", since = "1.0.0")] T),

    /// 此 [`sync_channel`] 的接收部分已断开连接,因此无法发送数据。
    /// 在这种情况下,数据将返回给被调用者。
    #[stable(feature = "rust1", since = "1.0.0")]
    Disconnected(#[stable(feature = "rust1", since = "1.0.0")] T),
}

enum Flavor<T> {
    Oneshot(Arc<oneshot::Packet<T>>),
    Stream(Arc<stream::Packet<T>>),
    Shared(Arc<shared::Packet<T>>),
    Sync(Arc<sync::Packet<T>>),
}

#[doc(hidden)]
trait UnsafeFlavor<T> {
    fn inner_unsafe(&self) -> &UnsafeCell<Flavor<T>>;
    unsafe fn inner_mut(&self) -> &mut Flavor<T> {
        &mut *self.inner_unsafe().get()
    }
    unsafe fn inner(&self) -> &Flavor<T> {
        &*self.inner_unsafe().get()
    }
}
impl<T> UnsafeFlavor<T> for Sender<T> {
    fn inner_unsafe(&self) -> &UnsafeCell<Flavor<T>> {
        &self.inner
    }
}
impl<T> UnsafeFlavor<T> for Receiver<T> {
    fn inner_unsafe(&self) -> &UnsafeCell<Flavor<T>> {
        &self.inner
    }
}

/// 创建一个新的异步通道,返回 sender/receiver 一半。
/// 在 [`Sender`] 上发送的所有数据将以与发送时相同的顺序在 [`Receiver`] 上可用,并且没有 [`send`] 将阻塞调用线程 (此通道具有一个 "无限缓冲区",与 [`sync_channel`] 不同,它将在达到其缓冲区限制后阻塞)。
/// [`recv`] 将阻塞直到消息可用,同时至少有一个 [`Sender`] 活着 (包括克隆)。
///
/// [`Sender`] 可以多次克隆到 [`send`] 到同一通道,但是仅支持一个 [`Receiver`]。
///
/// 如果在尝试使用 [`Sender`] 进行 [`send`] 时断开 [`Receiver`] 的连接,则 [`send`] 方法将返回 [`SendError`]。同样,如果在尝试 [`recv`] 时断开 [`Sender`] 的连接,则 [`recv`] 方法将返回 [`RecvError`]。
///
/// [`send`]: Sender::send
/// [`recv`]: Receiver::recv
///
/// # Examples
///
/// ```
/// use std::sync::mpsc::channel;
/// use std::thread;
///
/// let (sender, receiver) = channel();
///
/// // Spawn 关闭昂贵的计算
/// thread::spawn(move|| {
/// #   fn expensive_computation() {}
///     sender.send(expensive_computation()).unwrap();
/// });
///
/// // 暂时做一些有用的工作
///
/// // 让我们看看答案是什么
/// println!("{:?}", receiver.recv().unwrap());
/// ```
///
///
///
///
///
///
///
#[must_use]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn channel<T>() -> (Sender<T>, Receiver<T>) {
    let a = Arc::new(oneshot::Packet::new());
    (Sender::new(Flavor::Oneshot(a.clone())), Receiver::new(Flavor::Oneshot(a)))
}

/// 创建一个新的同步有界通道。
/// [`SyncSender`] 上发送的所有数据将以与发送相同的顺序在 [`Receiver`] 上可用。
/// 像异步 [`channel`] 一样,[`Receiver`] 将阻塞直到消息可用为止。
/// 然而,`sync_channel` 在发送者的语义上有很大不同。
///
/// 该通道具有内部缓冲区,消息将在该缓冲区上排队。
/// `bound` 指定缓冲区大小。
/// 当内部缓冲区已满时,future 将发送 *block*,等待缓冲区打开。
/// 请注意,缓冲区大小为 0 是有效的,在这种情况下,它变为 "会合通道",其中每个 [`send`] 在与 [`recv`] 配对之前不会返回。
///
/// [`SyncSender`] 可以多次克隆到 [`send`] 到同一通道,但是仅支持一个 [`Receiver`]。
///
/// 与异步通道一样,如果在尝试使用 [`SyncSender`] 进行 [`send`] 时断开 [`Receiver`],则 [`send`] 方法将返回 [`SendError`]。
///
/// 同样,如果在尝试 [`recv`] 时断开 [`SyncSender`] 的连接,则 [`recv`] 方法将返回 [`RecvError`]。
///
/// [`send`]: SyncSender::send
/// [`recv`]: Receiver::recv
///
/// # Examples
///
/// ```
/// use std::sync::mpsc::sync_channel;
/// use std::thread;
///
/// let (sender, receiver) = sync_channel(1);
///
/// // 这立即返回
/// sender.send(1).unwrap();
///
/// thread::spawn(move|| {
///     // 这将阻塞,直到收到上一条消息为止
///     sender.send(2).unwrap();
/// });
///
/// assert_eq!(receiver.recv().unwrap(), 1);
/// assert_eq!(receiver.recv().unwrap(), 2);
/// ```
///
///
///
///
#[must_use]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn sync_channel<T>(bound: usize) -> (SyncSender<T>, Receiver<T>) {
    let a = Arc::new(sync::Packet::new(bound));
    (SyncSender::new(a.clone()), Receiver::new(Flavor::Sync(a)))
}

////////////////////////////////////////////////////////////////////////////////
// Sender
////////////////////////////////////////////////////////////////////////////////

impl<T> Sender<T> {
    fn new(inner: Flavor<T>) -> Sender<T> {
        Sender { inner: UnsafeCell::new(inner) }
    }

    /// 尝试在此通道上发送值,如果无法发送,则将其返回。
    ///
    /// 当确定通道的另一端尚未挂断时,发送成功。
    /// 不成功的发送将是相应的接收者已被重新分配的发送。
    /// 请注意,返回值 [`Err`] 表示将永远不会接收到数据,但是 [`Ok`] 的返回值 *不是* 意味着将接收到数据。
    ///
    /// 此函数返回 [`Ok`] 之后,相应的接收者有可能立即挂断。
    ///
    /// 此方法永远不会阻塞当前线程。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::mpsc::channel;
    ///
    /// let (tx, rx) = channel();
    ///
    /// // 此发送始终成功
    /// tx.send(1).unwrap();
    ///
    /// // 由于接收者不见了,因此发送失败
    /// drop(rx);
    /// assert_eq!(tx.send(1).unwrap_err().0, 1);
    /// ```
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn send(&self, t: T) -> Result<(), SendError<T>> {
        let (new_inner, ret) = match *unsafe { self.inner() } {
            Flavor::Oneshot(ref p) => {
                if !p.sent() {
                    return p.send(t).map_err(SendError);
                } else {
                    let a = Arc::new(stream::Packet::new());
                    let rx = Receiver::new(Flavor::Stream(a.clone()));
                    match p.upgrade(rx) {
                        oneshot::UpSuccess => {
                            let ret = a.send(t);
                            (a, ret)
                        }
                        oneshot::UpDisconnected => (a, Err(t)),
                        oneshot::UpWoke(token) => {
                            // 此发送不能 panic,因为线程处于睡眠状态 (我们正在查看它),因此接收者无法消失。
                            //
                            //
                            a.send(t).ok().unwrap();
                            token.signal();
                            (a, Ok(()))
                        }
                    }
                }
            }
            Flavor::Stream(ref p) => return p.send(t).map_err(SendError),
            Flavor::Shared(ref p) => return p.send(t).map_err(SendError),
            Flavor::Sync(..) => unreachable!(),
        };

        unsafe {
            let tmp = Sender::new(Flavor::Stream(new_inner));
            mem::swap(self.inner_mut(), tmp.inner_mut());
        }
        ret.map_err(SendError)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> Clone for Sender<T> {
    /// 克隆发送者以发送到其他线程。
    ///
    /// 请注意,请注意发送方的生命周期,因为所有发送方 (包括原始发送方) 都需要丢弃,以便 [`Receiver::recv`] 停止阻塞。
    ///
    ///
    fn clone(&self) -> Sender<T> {
        let packet = match *unsafe { self.inner() } {
            Flavor::Oneshot(ref p) => {
                let a = Arc::new(shared::Packet::new());
                {
                    let guard = a.postinit_lock();
                    let rx = Receiver::new(Flavor::Shared(a.clone()));
                    let sleeper = match p.upgrade(rx) {
                        oneshot::UpSuccess | oneshot::UpDisconnected => None,
                        oneshot::UpWoke(task) => Some(task),
                    };
                    a.inherit_blocker(sleeper, guard);
                }
                a
            }
            Flavor::Stream(ref p) => {
                let a = Arc::new(shared::Packet::new());
                {
                    let guard = a.postinit_lock();
                    let rx = Receiver::new(Flavor::Shared(a.clone()));
                    let sleeper = match p.upgrade(rx) {
                        stream::UpSuccess | stream::UpDisconnected => None,
                        stream::UpWoke(task) => Some(task),
                    };
                    a.inherit_blocker(sleeper, guard);
                }
                a
            }
            Flavor::Shared(ref p) => {
                p.clone_chan();
                return Sender::new(Flavor::Shared(p.clone()));
            }
            Flavor::Sync(..) => unreachable!(),
        };

        unsafe {
            let tmp = Sender::new(Flavor::Shared(packet.clone()));
            mem::swap(self.inner_mut(), tmp.inner_mut());
        }
        Sender::new(Flavor::Shared(packet))
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> Drop for Sender<T> {
    fn drop(&mut self) {
        match *unsafe { self.inner() } {
            Flavor::Oneshot(ref p) => p.drop_chan(),
            Flavor::Stream(ref p) => p.drop_chan(),
            Flavor::Shared(ref p) => p.drop_chan(),
            Flavor::Sync(..) => unreachable!(),
        }
    }
}

#[stable(feature = "mpsc_debug", since = "1.8.0")]
impl<T> fmt::Debug for Sender<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Sender").finish_non_exhaustive()
    }
}

////////////////////////////////////////////////////////////////////////////////
// SyncSender
////////////////////////////////////////////////////////////////////////////////

impl<T> SyncSender<T> {
    fn new(inner: Arc<sync::Packet<T>>) -> SyncSender<T> {
        SyncSender { inner }
    }

    /// 在此同步通道上发送一个值。
    ///
    /// 该函数将阻塞,直到内部缓冲区中的空间可用或接收者可以将消息传递给它为止。
    ///
    /// 请注意,如果此通道上有缓冲区,则成功发送并不能保证接收者会看到数据。
    /// 该项可能会排队在内部缓冲区中,以供接收者在以后的时间接收。
    /// 但是,如果缓冲区大小为 0,则通道成为集合通道,并且如果此函数返回成功,则它保证接收者确实已接收到数据。
    ///
    ///
    /// 此函数永远不会 panic,但是如果 [`Receiver`] 已断开连接并且不再能够接收信息,则它可能返回 [`Err`]。
    ///
    /// # Examples
    ///
    /// ```rust
    /// use std::sync::mpsc::sync_channel;
    /// use std::thread;
    ///
    /// // 创建一个缓冲区大小为 0 的集合点 sync_channel
    /// let (sync_sender, receiver) = sync_channel(0);
    ///
    /// thread::spawn(move || {
    ///    println!("sending message...");
    ///    sync_sender.send(1).unwrap();
    ///    // 现在线程被阻塞,直到收到消息为止
    ///
    ///    println!("...message received!");
    /// });
    ///
    /// let msg = receiver.recv().unwrap();
    /// assert_eq!(1, msg);
    /// ```
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn send(&self, t: T) -> Result<(), SendError<T>> {
        self.inner.send(t).map_err(SendError)
    }

    /// 尝试在此通道上发送值而不会阻塞。
    ///
    /// 此方法不同于 [`send`],如果通道的缓冲区已满或没有接收者正在等待获取某些数据,则立即返回。
    /// 与 [`send`] 相比,此函数有两种故障情况,而不是一种情况 (一种情况是断开连接,一种情况是完整的缓冲区)。
    ///
    /// 请参见 [`send`],以获取有关确保此函数成功后接收方是否已接收到数据的说明。
    ///
    /// [`send`]: Self::send
    ///
    /// # Examples
    ///
    /// ```rust
    /// use std::sync::mpsc::sync_channel;
    /// use std::thread;
    ///
    /// // 创建一个缓冲区大小为 1 的 sync_channel
    /// let (sync_sender, receiver) = sync_channel(1);
    /// let sync_sender2 = sync_sender.clone();
    ///
    /// // 第一个线程拥有 sync_sender
    /// thread::spawn(move || {
    ///     sync_sender.send(1).unwrap();
    ///     sync_sender.send(2).unwrap();
    ///     // 线程被阻塞
    /// });
    ///
    /// // 第二个线程拥有 sync_sender2
    /// thread::spawn(move || {
    ///     // 如果缓冲区已满,这将返回错误并且不发送任何消息
    /////
    ///     let _ = sync_sender2.try_send(3);
    /// });
    ///
    /// let mut msg;
    /// msg = receiver.recv().unwrap();
    /// println!("message {} received", msg);
    ///
    /// msg = receiver.recv().unwrap();
    /// println!("message {} received", msg);
    ///
    /// // 第三条消息可能从未发送过
    /// match receiver.try_recv() {
    ///     Ok(msg) => println!("message {} received", msg),
    ///     Err(_) => println!("the third message was never sent"),
    /// }
    /// ```
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn try_send(&self, t: T) -> Result<(), TrySendError<T>> {
        self.inner.try_send(t)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> Clone for SyncSender<T> {
    fn clone(&self) -> SyncSender<T> {
        self.inner.clone_chan();
        SyncSender::new(self.inner.clone())
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> Drop for SyncSender<T> {
    fn drop(&mut self) {
        self.inner.drop_chan();
    }
}

#[stable(feature = "mpsc_debug", since = "1.8.0")]
impl<T> fmt::Debug for SyncSender<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("SyncSender").finish_non_exhaustive()
    }
}

////////////////////////////////////////////////////////////////////////////////
// Receiver
////////////////////////////////////////////////////////////////////////////////

impl<T> Receiver<T> {
    fn new(inner: Flavor<T>) -> Receiver<T> {
        Receiver { inner: UnsafeCell::new(inner) }
    }

    /// 尝试在不阻塞的情况下在此接收者上返回挂起的值。
    ///
    /// 此方法决不会阻塞调用者,以等待数据可用。
    /// 取而代之的是,它总是立即返回,并可能在通道上保留未决数据。
    ///
    /// 在决定阻塞接收者之前,这对于 "optimistic check" 很有用。
    ///
    /// 与 [`recv`] 相比,此函数有两种故障情况,而不是一种情况 (一种情况是断开连接,一种情况是空缓冲区)。
    ///
    ///
    /// [`recv`]: Self::recv
    ///
    /// # Examples
    ///
    /// ```rust
    /// use std::sync::mpsc::{Receiver, channel};
    ///
    /// let (_, receiver): (_, Receiver<i32>) = channel();
    ///
    /// assert!(receiver.try_recv().is_err());
    /// ```
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn try_recv(&self) -> Result<T, TryRecvError> {
        loop {
            let new_port = match *unsafe { self.inner() } {
                Flavor::Oneshot(ref p) => match p.try_recv() {
                    Ok(t) => return Ok(t),
                    Err(oneshot::Empty) => return Err(TryRecvError::Empty),
                    Err(oneshot::Disconnected) => return Err(TryRecvError::Disconnected),
                    Err(oneshot::Upgraded(rx)) => rx,
                },
                Flavor::Stream(ref p) => match p.try_recv() {
                    Ok(t) => return Ok(t),
                    Err(stream::Empty) => return Err(TryRecvError::Empty),
                    Err(stream::Disconnected) => return Err(TryRecvError::Disconnected),
                    Err(stream::Upgraded(rx)) => rx,
                },
                Flavor::Shared(ref p) => match p.try_recv() {
                    Ok(t) => return Ok(t),
                    Err(shared::Empty) => return Err(TryRecvError::Empty),
                    Err(shared::Disconnected) => return Err(TryRecvError::Disconnected),
                },
                Flavor::Sync(ref p) => match p.try_recv() {
                    Ok(t) => return Ok(t),
                    Err(sync::Empty) => return Err(TryRecvError::Empty),
                    Err(sync::Disconnected) => return Err(TryRecvError::Disconnected),
                },
            };
            unsafe {
                mem::swap(self.inner_mut(), new_port.inner_mut());
            }
        }
    }

    /// 尝试等待此接收者上的值,如果相应的通道已挂起,则返回错误。
    ///
    /// 如果没有可用数据并且有可能发送更多数据 (至少一个发送者仍然存在),此函数将始终阻塞当前线程。
    /// 一旦消息发送到相应的 [`Sender`] (或 [`SyncSender`]),该接收者将唤醒并返回该消息。
    ///
    /// 如果相应的 [`Sender`] 断开连接,或者在此调用阻塞时断开连接,则此调用将唤醒并返回 [`Err`],以指示该通道上再也不会收到任何消息。
    ///
    /// 但是,由于缓冲了通道,因此在断开连接之前发送的消息仍将被正确接收。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::mpsc;
    /// use std::thread;
    ///
    /// let (send, recv) = mpsc::channel();
    /// let handle = thread::spawn(move || {
    ///     send.send(1u8).unwrap();
    /// });
    ///
    /// handle.join().unwrap();
    ///
    /// assert_eq!(Ok(1), recv.recv());
    /// ```
    ///
    /// 缓冲行为:
    ///
    /// ```
    /// use std::sync::mpsc;
    /// use std::thread;
    /// use std::sync::mpsc::RecvError;
    ///
    /// let (send, recv) = mpsc::channel();
    /// let handle = thread::spawn(move || {
    ///     send.send(1u8).unwrap();
    ///     send.send(2).unwrap();
    ///     send.send(3).unwrap();
    ///     drop(send);
    /// });
    ///
    /// // 等待线程加入,因此我们确保发送者已被丢弃
    /// handle.join().unwrap();
    ///
    /// assert_eq!(Ok(1), recv.recv());
    /// assert_eq!(Ok(2), recv.recv());
    /// assert_eq!(Ok(3), recv.recv());
    /// assert_eq!(Err(RecvError), recv.recv());
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn recv(&self) -> Result<T, RecvError> {
        loop {
            let new_port = match *unsafe { self.inner() } {
                Flavor::Oneshot(ref p) => match p.recv(None) {
                    Ok(t) => return Ok(t),
                    Err(oneshot::Disconnected) => return Err(RecvError),
                    Err(oneshot::Upgraded(rx)) => rx,
                    Err(oneshot::Empty) => unreachable!(),
                },
                Flavor::Stream(ref p) => match p.recv(None) {
                    Ok(t) => return Ok(t),
                    Err(stream::Disconnected) => return Err(RecvError),
                    Err(stream::Upgraded(rx)) => rx,
                    Err(stream::Empty) => unreachable!(),
                },
                Flavor::Shared(ref p) => match p.recv(None) {
                    Ok(t) => return Ok(t),
                    Err(shared::Disconnected) => return Err(RecvError),
                    Err(shared::Empty) => unreachable!(),
                },
                Flavor::Sync(ref p) => return p.recv(None).map_err(|_| RecvError),
            };
            unsafe {
                mem::swap(self.inner_mut(), new_port.inner_mut());
            }
        }
    }

    /// 尝试等待此接收器上的值,如果相应的通道已挂起,或者等待的时间超过 `timeout`,则返回错误。
    ///
    /// 如果没有可用数据并且有可能发送更多数据 (至少一个发送者仍然存在),此函数将始终阻塞当前线程。
    /// 一旦消息发送到相应的 [`Sender`] (或 [`SyncSender`]),该接收者将唤醒并返回该消息。
    ///
    /// 如果相应的 [`Sender`] 断开连接,或者在此调用阻塞时断开连接,则此调用将唤醒并返回 [`Err`],以指示该通道上再也不会收到任何消息。
    ///
    /// 但是,由于缓冲了通道,因此在断开连接之前发送的消息仍将被正确接收。
    ///
    /// # 已知的问题
    ///
    /// 当前存在一个已知问题 (请参见 [`#39364`]),以下示例导致 `recv_timeout` 意外变为 panic:
    ///
    /// ```no_run
    /// use std::sync::mpsc::channel;
    /// use std::thread;
    /// use std::time::Duration;
    ///
    /// let (tx, rx) = channel::<String>();
    ///
    /// thread::spawn(move || {
    ///     let d = Duration::from_millis(10);
    ///     loop {
    ///         println!("recv");
    ///         let _r = rx.recv_timeout(d);
    ///     }
    /// });
    ///
    /// thread::sleep(Duration::from_millis(100));
    /// let _c1 = tx.clone();
    ///
    /// thread::sleep(Duration::from_secs(1));
    /// ```
    ///
    /// [`#39364`]: https://github.com/rust-lang/rust/issues/39364
    ///
    /// # Examples
    ///
    /// 在遇到超时之前成功获得值:
    ///
    /// ```no_run
    /// use std::thread;
    /// use std::time::Duration;
    /// use std::sync::mpsc;
    ///
    /// let (send, recv) = mpsc::channel();
    ///
    /// thread::spawn(move || {
    ///     send.send('a').unwrap();
    /// });
    ///
    /// assert_eq!(
    ///     recv.recv_timeout(Duration::from_millis(400)),
    ///     Ok('a')
    /// );
    /// ```
    ///
    /// 到达超时时收到错误:
    ///
    /// ```no_run
    /// use std::thread;
    /// use std::time::Duration;
    /// use std::sync::mpsc;
    ///
    /// let (send, recv) = mpsc::channel();
    ///
    /// thread::spawn(move || {
    ///     thread::sleep(Duration::from_millis(800));
    ///     send.send('a').unwrap();
    /// });
    ///
    /// assert_eq!(
    ///     recv.recv_timeout(Duration::from_millis(400)),
    ///     Err(mpsc::RecvTimeoutError::Timeout)
    /// );
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "mpsc_recv_timeout", since = "1.12.0")]
    pub fn recv_timeout(&self, timeout: Duration) -> Result<T, RecvTimeoutError> {
        // 进行乐观的 try_recv 以避免全通道情况下 Instant::now () 的性能影响。
        //
        match self.try_recv() {
            Ok(result) => Ok(result),
            Err(TryRecvError::Disconnected) => Err(RecvTimeoutError::Disconnected),
            Err(TryRecvError::Empty) => match Instant::now().checked_add(timeout) {
                Some(deadline) => self.recv_deadline(deadline),
                // 到目前为止,在 future 中,它实际上与无限期等待相同。
                None => self.recv().map_err(RecvTimeoutError::from),
            },
        }
    }

    /// 尝试等待此接收器上的值,如果相应的通道已挂起,或者到达 `deadline`,则返回错误。
    ///
    /// 如果没有可用数据,并且有可能发送更多数据,则此函数将始终阻止当前线程。
    /// 将消息发送到相应的 [`Sender`] (或 [`SyncSender`]) 后,此接收者将唤醒并返回该消息。
    ///
    /// 如果相应的 [`Sender`] 断开连接,或者在此调用阻塞时断开连接,则此调用将唤醒并返回 [`Err`],以指示该通道上再也不会收到任何消息。
    ///
    /// 但是,由于缓冲了通道,因此在断开连接之前发送的消息仍将被正确接收。
    ///
    /// # Examples
    ///
    /// 在截止日期之前成功获得值:
    ///
    /// ```no_run
    /// #![feature(deadline_api)]
    /// use std::thread;
    /// use std::time::{Duration, Instant};
    /// use std::sync::mpsc;
    ///
    /// let (send, recv) = mpsc::channel();
    ///
    /// thread::spawn(move || {
    ///     send.send('a').unwrap();
    /// });
    ///
    /// assert_eq!(
    ///     recv.recv_deadline(Instant::now() + Duration::from_millis(400)),
    ///     Ok('a')
    /// );
    /// ```
    ///
    /// 在截止日期前收到错误:
    ///
    /// ```no_run
    /// #![feature(deadline_api)]
    /// use std::thread;
    /// use std::time::{Duration, Instant};
    /// use std::sync::mpsc;
    ///
    /// let (send, recv) = mpsc::channel();
    ///
    /// thread::spawn(move || {
    ///     thread::sleep(Duration::from_millis(800));
    ///     send.send('a').unwrap();
    /// });
    ///
    /// assert_eq!(
    ///     recv.recv_deadline(Instant::now() + Duration::from_millis(400)),
    ///     Err(mpsc::RecvTimeoutError::Timeout)
    /// );
    /// ```
    ///
    ///
    ///
    ///
    ///
    #[unstable(feature = "deadline_api", issue = "46316")]
    pub fn recv_deadline(&self, deadline: Instant) -> Result<T, RecvTimeoutError> {
        use self::RecvTimeoutError::*;

        loop {
            let port_or_empty = match *unsafe { self.inner() } {
                Flavor::Oneshot(ref p) => match p.recv(Some(deadline)) {
                    Ok(t) => return Ok(t),
                    Err(oneshot::Disconnected) => return Err(Disconnected),
                    Err(oneshot::Upgraded(rx)) => Some(rx),
                    Err(oneshot::Empty) => None,
                },
                Flavor::Stream(ref p) => match p.recv(Some(deadline)) {
                    Ok(t) => return Ok(t),
                    Err(stream::Disconnected) => return Err(Disconnected),
                    Err(stream::Upgraded(rx)) => Some(rx),
                    Err(stream::Empty) => None,
                },
                Flavor::Shared(ref p) => match p.recv(Some(deadline)) {
                    Ok(t) => return Ok(t),
                    Err(shared::Disconnected) => return Err(Disconnected),
                    Err(shared::Empty) => None,
                },
                Flavor::Sync(ref p) => match p.recv(Some(deadline)) {
                    Ok(t) => return Ok(t),
                    Err(sync::Disconnected) => return Err(Disconnected),
                    Err(sync::Empty) => None,
                },
            };

            if let Some(new_port) = port_or_empty {
                unsafe {
                    mem::swap(self.inner_mut(), new_port.inner_mut());
                }
            }

            // 如果我们已经超过了最后期限,并且我们没有数据,请返回超时,否则重试。
            //
            if Instant::now() >= deadline {
                return Err(Timeout);
            }
        }
    }

    /// 返回一个迭代器,该迭代器将阻止等待消息,但不会阻止 [`panic!`]。
    /// 通道挂起时,它将返回 [`None`]。
    ///
    /// # Examples
    ///
    /// ```rust
    /// use std::sync::mpsc::channel;
    /// use std::thread;
    ///
    /// let (send, recv) = channel();
    ///
    /// thread::spawn(move || {
    ///     send.send(1).unwrap();
    ///     send.send(2).unwrap();
    ///     send.send(3).unwrap();
    /// });
    ///
    /// let mut iter = recv.iter();
    /// assert_eq!(iter.next(), Some(1));
    /// assert_eq!(iter.next(), Some(2));
    /// assert_eq!(iter.next(), Some(3));
    /// assert_eq!(iter.next(), None);
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn iter(&self) -> Iter<'_, T> {
        Iter { rx: self }
    }

    /// 返回一个迭代器,它将尝试产生所有挂起的值。
    /// 如果没有其他未决值或通道已挂断,它将返回 `None`。
    /// 迭代器永远不会 [`panic!`] 或通过等待值来阻止用户。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::sync::mpsc::channel;
    /// use std::thread;
    /// use std::time::Duration;
    ///
    /// let (sender, receiver) = channel();
    ///
    /// // 缓冲区中还没有任何东西
    /// assert!(receiver.try_iter().next().is_none());
    ///
    /// thread::spawn(move || {
    ///     thread::sleep(Duration::from_secs(1));
    ///     sender.send(1).unwrap();
    ///     sender.send(2).unwrap();
    ///     sender.send(3).unwrap();
    /// });
    ///
    /// // 缓冲区中还没有任何东西
    /// assert!(receiver.try_iter().next().is_none());
    ///
    /// // 阻塞两秒钟
    /// thread::sleep(Duration::from_secs(2));
    ///
    /// let mut iter = receiver.try_iter();
    /// assert_eq!(iter.next(), Some(1));
    /// assert_eq!(iter.next(), Some(2));
    /// assert_eq!(iter.next(), Some(3));
    /// assert_eq!(iter.next(), None);
    /// ```
    ///
    #[stable(feature = "receiver_try_iter", since = "1.15.0")]
    pub fn try_iter(&self) -> TryIter<'_, T> {
        TryIter { rx: self }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<'a, T> Iterator for Iter<'a, T> {
    type Item = T;

    fn next(&mut self) -> Option<T> {
        self.rx.recv().ok()
    }
}

#[stable(feature = "receiver_try_iter", since = "1.15.0")]
impl<'a, T> Iterator for TryIter<'a, T> {
    type Item = T;

    fn next(&mut self) -> Option<T> {
        self.rx.try_recv().ok()
    }
}

#[stable(feature = "receiver_into_iter", since = "1.1.0")]
impl<'a, T> IntoIterator for &'a Receiver<T> {
    type Item = T;
    type IntoIter = Iter<'a, T>;

    fn into_iter(self) -> Iter<'a, T> {
        self.iter()
    }
}

#[stable(feature = "receiver_into_iter", since = "1.1.0")]
impl<T> Iterator for IntoIter<T> {
    type Item = T;
    fn next(&mut self) -> Option<T> {
        self.rx.recv().ok()
    }
}

#[stable(feature = "receiver_into_iter", since = "1.1.0")]
impl<T> IntoIterator for Receiver<T> {
    type Item = T;
    type IntoIter = IntoIter<T>;

    fn into_iter(self) -> IntoIter<T> {
        IntoIter { rx: self }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> Drop for Receiver<T> {
    fn drop(&mut self) {
        match *unsafe { self.inner() } {
            Flavor::Oneshot(ref p) => p.drop_port(),
            Flavor::Stream(ref p) => p.drop_port(),
            Flavor::Shared(ref p) => p.drop_port(),
            Flavor::Sync(ref p) => p.drop_port(),
        }
    }
}

#[stable(feature = "mpsc_debug", since = "1.8.0")]
impl<T> fmt::Debug for Receiver<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Receiver").finish_non_exhaustive()
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> fmt::Debug for SendError<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("SendError").finish_non_exhaustive()
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> fmt::Display for SendError<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        "sending on a closed channel".fmt(f)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: Send> error::Error for SendError<T> {
    #[allow(deprecated)]
    fn description(&self) -> &str {
        "sending on a closed channel"
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> fmt::Debug for TrySendError<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match *self {
            TrySendError::Full(..) => "Full(..)".fmt(f),
            TrySendError::Disconnected(..) => "Disconnected(..)".fmt(f),
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> fmt::Display for TrySendError<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match *self {
            TrySendError::Full(..) => "sending on a full channel".fmt(f),
            TrySendError::Disconnected(..) => "sending on a closed channel".fmt(f),
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: Send> error::Error for TrySendError<T> {
    #[allow(deprecated)]
    fn description(&self) -> &str {
        match *self {
            TrySendError::Full(..) => "sending on a full channel",
            TrySendError::Disconnected(..) => "sending on a closed channel",
        }
    }
}

#[stable(feature = "mpsc_error_conversions", since = "1.24.0")]
impl<T> From<SendError<T>> for TrySendError<T> {
    /// 将 `SendError<T>` 转换为 `TrySendError<T>`。
    ///
    /// 这种转换总是返回一个包含 `SendError<T>` 中数据的 `TrySendError::Disconnected`。
    ///
    /// 没有在堆上分配数据。
    fn from(err: SendError<T>) -> TrySendError<T> {
        match err {
            SendError(t) => TrySendError::Disconnected(t),
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl fmt::Display for RecvError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        "receiving on a closed channel".fmt(f)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl error::Error for RecvError {
    #[allow(deprecated)]
    fn description(&self) -> &str {
        "receiving on a closed channel"
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl fmt::Display for TryRecvError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match *self {
            TryRecvError::Empty => "receiving on an empty channel".fmt(f),
            TryRecvError::Disconnected => "receiving on a closed channel".fmt(f),
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl error::Error for TryRecvError {
    #[allow(deprecated)]
    fn description(&self) -> &str {
        match *self {
            TryRecvError::Empty => "receiving on an empty channel",
            TryRecvError::Disconnected => "receiving on a closed channel",
        }
    }
}

#[stable(feature = "mpsc_error_conversions", since = "1.24.0")]
impl From<RecvError> for TryRecvError {
    /// 将 `RecvError` 转换为 `TryRecvError`。
    ///
    /// 此转换始终返回 `TryRecvError::Disconnected`。
    ///
    /// 没有在堆上分配数据。
    fn from(err: RecvError) -> TryRecvError {
        match err {
            RecvError => TryRecvError::Disconnected,
        }
    }
}

#[stable(feature = "mpsc_recv_timeout_error", since = "1.15.0")]
impl fmt::Display for RecvTimeoutError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match *self {
            RecvTimeoutError::Timeout => "timed out waiting on channel".fmt(f),
            RecvTimeoutError::Disconnected => "channel is empty and sending half is closed".fmt(f),
        }
    }
}

#[stable(feature = "mpsc_recv_timeout_error", since = "1.15.0")]
impl error::Error for RecvTimeoutError {
    #[allow(deprecated)]
    fn description(&self) -> &str {
        match *self {
            RecvTimeoutError::Timeout => "timed out waiting on channel",
            RecvTimeoutError::Disconnected => "channel is empty and sending half is closed",
        }
    }
}

#[stable(feature = "mpsc_error_conversions", since = "1.24.0")]
impl From<RecvError> for RecvTimeoutError {
    /// 将 `RecvError` 转换为 `RecvTimeoutError`。
    ///
    /// 此转换始终返回 `RecvTimeoutError::Disconnected`。
    ///
    /// 没有在堆上分配数据。
    fn from(err: RecvError) -> RecvTimeoutError {
        match err {
            RecvError => RecvTimeoutError::Disconnected,
        }
    }
}