13
13
//! This module provides message-based communication over channels, concretely
14
14
//! defined among three types:
15
15
//!
16
- //! * `Sender`
17
- //! * `SyncSender`
18
- //! * `Receiver`
16
+ //! * [ `Sender`]
17
+ //! * [ `SyncSender`]
18
+ //! * [ `Receiver`]
19
19
//!
20
- //! A `Sender` or `SyncSender` is used to send data to a `Receiver`. Both
20
+ //! A [ `Sender`] or [ `SyncSender`] is used to send data to a [ `Receiver`] . Both
21
21
//! senders are clone-able (multi-producer) such that many threads can send
22
22
//! simultaneously to one receiver (single-consumer).
23
23
//!
24
24
//! These channels come in two flavors:
25
25
//!
26
- //! 1. An asynchronous, infinitely buffered channel. The `channel()` function
26
+ //! 1. An asynchronous, infinitely buffered channel. The [ `channel`] function
27
27
//! will return a `(Sender, Receiver)` tuple where all sends will be
28
28
//! **asynchronous** (they never block). The channel conceptually has an
29
29
//! infinite buffer.
30
30
//!
31
- //! 2. A synchronous, bounded channel. The `sync_channel()` function will return
32
- //! a `(SyncSender, Receiver)` tuple where the storage for pending messages
33
- //! is a pre-allocated buffer of a fixed size. All sends will be
31
+ //! 2. A synchronous, bounded channel. The [ `sync_channel`] function will
32
+ //! return a `(SyncSender, Receiver)` tuple where the storage for pending
33
+ //! messages is a pre-allocated buffer of a fixed size. All sends will be
34
34
//! **synchronous** by blocking until there is buffer space available. Note
35
- //! that a bound of 0 is allowed, causing the channel to become a
36
- //! "rendezvous" channel where each sender atomically hands off a message to
37
- //! a receiver.
35
+ //! that a bound of 0 is allowed, causing the channel to become a "rendezvous"
36
+ //! channel where each sender atomically hands off a message to a receiver.
37
+ //!
38
+ //! [`Sender`]: ../../../std/sync/mpsc/struct.Sender.html
39
+ //! [`SyncSender`]: ../../../std/sync/mpsc/struct.SyncSender.html
40
+ //! [`Receiver`]: ../../../std/sync/mpsc/struct.Receiver.html
41
+ //! [`send`]: ../../../std/sync/mpsc/struct.Sender.html#method.send
42
+ //! [`channel`]: ../../../std/sync/mpsc/fn.channel.html
43
+ //! [`sync_channel`]: ../../../std/sync/mpsc/fn.sync_channel.html
38
44
//!
39
45
//! ## Disconnection
40
46
//!
41
- //! The send and receive operations on channels will all return a `Result`
47
+ //! The send and receive operations on channels will all return a [ `Result`]
42
48
//! indicating whether the operation succeeded or not. An unsuccessful operation
43
49
//! is normally indicative of the other half of a channel having "hung up" by
44
50
//! being dropped in its corresponding thread.
45
51
//!
46
52
//! Once half of a channel has been deallocated, most operations can no longer
47
- //! continue to make progress, so `Err` will be returned. Many applications will
48
- //! continue to `unwrap()` the results returned from this module, instigating a
49
- //! propagation of failure among threads if one unexpectedly dies.
53
+ //! continue to make progress, so [`Err`] will be returned. Many applications
54
+ //! will continue to [`unwrap`] the results returned from this module,
55
+ //! instigating a propagation of failure among threads if one unexpectedly dies.
56
+ //!
57
+ //! [`Result`]: ../../../std/result/enum.Result.html
58
+ //! [`Err`]: ../../../std/result/enum.Result.html#variant.Err
59
+ //! [`unwrap`]: ../../../std/result/enum.Result.html#method.unwrap
50
60
//!
51
61
//! # Examples
52
62
//!
@@ -288,7 +298,31 @@ mod mpsc_queue;
288
298
mod spsc_queue;
289
299
290
300
/// The receiving-half of Rust's channel type. This half can only be owned by
291
- /// one thread
301
+ /// one thread.
302
+ ///
303
+ /// Messages sent to the channel can be retrieved using [`recv`].
304
+ ///
305
+ /// [`recv`]: ../../../std/sync/mpsc/struct.Receiver.html#method.recv
306
+ ///
307
+ /// # Examples
308
+ ///
309
+ /// ```rust
310
+ /// use std::sync::mpsc::channel;
311
+ /// use std::thread;
312
+ /// use std::time::Duration;
313
+ ///
314
+ /// let (send, recv) = channel();
315
+ ///
316
+ /// thread::spawn(move || {
317
+ /// send.send("Hello world!").unwrap();
318
+ /// thread::sleep(Duration::from_secs(2)); // block for two seconds
319
+ /// send.send("Delayed for 2 seconds").unwrap();
320
+ /// });
321
+ ///
322
+ /// println!("{}", recv.recv().unwrap()); // Received immediately
323
+ /// println!("Waiting...");
324
+ /// println!("{}", recv.recv().unwrap()); // Received after 2 seconds
325
+ /// ```
292
326
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
293
327
pub struct Receiver < T > {
294
328
inner : UnsafeCell < Flavor < T > > ,
@@ -302,30 +336,39 @@ unsafe impl<T: Send> Send for Receiver<T> { }
302
336
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
303
337
impl < T > !Sync for Receiver < T > { }
304
338
305
- /// An iterator over messages on a receiver, this iterator will block
306
- /// whenever `next` is called, waiting for a new message, and `None` will be
307
- /// returned when the corresponding channel has hung up.
339
+ /// An iterator over messages on a receiver, this iterator will block whenever
340
+ /// [`next`] is called, waiting for a new message, and [`None`] will be returned
341
+ /// when the corresponding channel has hung up.
342
+ ///
343
+ /// [`next`]: ../../../std/iter/trait.Iterator.html#tymethod.next
344
+ /// [`None`]: ../../../std/option/enum.Option.html#variant.None
308
345
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
309
346
#[ derive( Debug ) ]
310
347
pub struct Iter < ' a , T : ' a > {
311
348
rx : & ' a Receiver < T >
312
349
}
313
350
314
351
/// An iterator that attempts to yield all pending values for a receiver.
315
- /// `None` will be returned when there are no pending values remaining or
316
- /// if the corresponding channel has hung up.
352
+ /// [ `None`] will be returned when there are no pending values remaining or if
353
+ /// the corresponding channel has hung up.
317
354
///
318
355
/// This Iterator will never block the caller in order to wait for data to
319
- /// become available. Instead, it will return `None`.
356
+ /// become available. Instead, it will return [`None`].
357
+ ///
358
+ /// [`None`]: ../../../std/option/enum.Option.html#variant.None
320
359
#[ stable( feature = "receiver_try_iter" , since = "1.15.0" ) ]
321
360
#[ derive( Debug ) ]
322
361
pub struct TryIter < ' a , T : ' a > {
323
362
rx : & ' a Receiver < T >
324
363
}
325
364
326
365
/// An owning iterator over messages on a receiver, this iterator will block
327
- /// whenever `next` is called, waiting for a new message, and `None` will be
366
+ /// whenever [ `next`] is called, waiting for a new message, and [ `None`] will be
328
367
/// returned when the corresponding channel has hung up.
368
+ ///
369
+ /// [`next`]: ../../../std/iter/trait.Iterator.html#tymethod.next
370
+ /// [`None`]: ../../../std/option/enum.Option.html#variant.None
371
+ ///
329
372
#[ stable( feature = "receiver_into_iter" , since = "1.1.0" ) ]
330
373
#[ derive( Debug ) ]
331
374
pub struct IntoIter < T > {
@@ -334,6 +377,35 @@ pub struct IntoIter<T> {
334
377
335
378
/// The sending-half of Rust's asynchronous channel type. This half can only be
336
379
/// owned by one thread, but it can be cloned to send to other threads.
380
+ ///
381
+ /// Messages can be sent through this channel with [`send`].
382
+ ///
383
+ /// [`send`]: ../../../std/sync/mpsc/struct.Sender.html#method.send
384
+ ///
385
+ /// # Examples
386
+ ///
387
+ /// ```rust
388
+ /// use std::sync::mpsc::channel;
389
+ /// use std::thread;
390
+ ///
391
+ /// let (sender, receiver) = channel();
392
+ /// let sender2 = sender.clone();
393
+ ///
394
+ /// // First thread owns sender
395
+ /// thread::spawn(move || {
396
+ /// sender.send(1).unwrap();
397
+ /// });
398
+ ///
399
+ /// // Second thread owns sender2
400
+ /// thread::spawn(move || {
401
+ /// sender2.send(2).unwrap();
402
+ /// });
403
+ ///
404
+ /// let msg = receiver.recv().unwrap();
405
+ /// let msg2 = receiver.recv().unwrap();
406
+ ///
407
+ /// assert_eq!(3, msg + msg2);
408
+ /// ```
337
409
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
338
410
pub struct Sender < T > {
339
411
inner : UnsafeCell < Flavor < T > > ,
@@ -349,6 +421,10 @@ impl<T> !Sync for Sender<T> { }
349
421
350
422
/// The sending-half of Rust's synchronous channel type. This half can only be
351
423
/// owned by one thread, but it can be cloned to send to other threads.
424
+ ///
425
+ /// [`send`]: ../../../std/sync/mpsc/struct.Sender.html#method.send
426
+ /// [`SyncSender::send`]: ../../../std/sync/mpsc/struct.SyncSender.html#method.send
427
+ ///
352
428
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
353
429
pub struct SyncSender < T > {
354
430
inner : Arc < sync:: Packet < T > > ,
@@ -360,25 +436,32 @@ unsafe impl<T: Send> Send for SyncSender<T> {}
360
436
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
361
437
impl < T > !Sync for SyncSender < T > { }
362
438
363
- /// An error returned from the `send` function on channels.
439
+ /// An error returned from the [ `send`] function on channels.
364
440
///
365
- /// A `send` operation can only fail if the receiving end of a channel is
441
+ /// A [ `send`] operation can only fail if the receiving end of a channel is
366
442
/// disconnected, implying that the data could never be received. The error
367
443
/// contains the data being sent as a payload so it can be recovered.
444
+ ///
445
+ /// [`send`]: ../../../std/sync/mpsc/struct.Sender.html#method.send
368
446
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
369
447
#[ derive( PartialEq , Eq , Clone , Copy ) ]
370
448
pub struct SendError < T > ( #[ stable( feature = "rust1" , since = "1.0.0" ) ] pub T ) ;
371
449
372
- /// An error returned from the `recv` function on a `Receiver`.
450
+ /// An error returned from the [ `recv`] function on a [ `Receiver`] .
373
451
///
374
- /// The `recv` operation can only fail if the sending half of a channel is
452
+ /// The [ `recv`] operation can only fail if the sending half of a channel is
375
453
/// disconnected, implying that no further messages will ever be received.
454
+ ///
455
+ /// [`recv`]: ../../../std/sync/mpsc/struct.Receiver.html#method.recv
456
+ /// [`Receiver`]: ../../../std/sync/mpsc/struct.Receiver.html
376
457
#[ derive( PartialEq , Eq , Clone , Copy , Debug ) ]
377
458
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
378
459
pub struct RecvError ;
379
460
380
- /// This enumeration is the list of the possible reasons that `try_recv` could
461
+ /// This enumeration is the list of the possible reasons that [ `try_recv`] could
381
462
/// not return data when called.
463
+ ///
464
+ /// [`try_recv`]: ../../../std/sync/mpsc/struct.Receiver.html#method.try_recv
382
465
#[ derive( PartialEq , Eq , Clone , Copy , Debug ) ]
383
466
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
384
467
pub enum TryRecvError {
@@ -393,8 +476,10 @@ pub enum TryRecvError {
393
476
Disconnected ,
394
477
}
395
478
396
- /// This enumeration is the list of possible errors that `recv_timeout` could
479
+ /// This enumeration is the list of possible errors that [ `recv_timeout`] could
397
480
/// not return data when called.
481
+ ///
482
+ /// [`recv_timeout`]: ../../../std/sync/mpsc/struct.Receiver.html#method.recv_timeout
398
483
#[ derive( PartialEq , Eq , Clone , Copy , Debug ) ]
399
484
#[ stable( feature = "mpsc_recv_timeout" , since = "1.12.0" ) ]
400
485
pub enum RecvTimeoutError {
@@ -409,7 +494,9 @@ pub enum RecvTimeoutError {
409
494
}
410
495
411
496
/// This enumeration is the list of the possible error outcomes for the
412
- /// `SyncSender::try_send` method.
497
+ /// [`SyncSender::try_send`] method.
498
+ ///
499
+ /// [`SyncSender::try_send`]: ../../../std/sync/mpsc/struct.SyncSender.html#method.try_send
413
500
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
414
501
#[ derive( PartialEq , Eq , Clone , Copy ) ]
415
502
pub enum TrySendError < T > {
@@ -556,10 +643,13 @@ impl<T> Sender<T> {
556
643
/// A successful send occurs when it is determined that the other end of
557
644
/// the channel has not hung up already. An unsuccessful send would be one
558
645
/// where the corresponding receiver has already been deallocated. Note
559
- /// that a return value of `Err` means that the data will never be
560
- /// received, but a return value of `Ok` does *not* mean that the data
646
+ /// that a return value of [ `Err`] means that the data will never be
647
+ /// received, but a return value of [ `Ok`] does *not* mean that the data
561
648
/// will be received. It is possible for the corresponding receiver to
562
- /// hang up immediately after this function returns `Ok`.
649
+ /// hang up immediately after this function returns [`Ok`].
650
+ ///
651
+ /// [`Err`]: ../../../std/result/enum.Result.html#variant.Err
652
+ /// [`Ok`]: ../../../std/result/enum.Result.html#variant.Ok
563
653
///
564
654
/// This method will never block the current thread.
565
655
///
@@ -702,23 +792,29 @@ impl<T> SyncSender<T> {
702
792
/// time. If the buffer size is 0, however, it can be guaranteed that the
703
793
/// receiver has indeed received the data if this function returns success.
704
794
///
705
- /// This function will never panic, but it may return `Err` if the
706
- /// `Receiver` has disconnected and is no longer able to receive
795
+ /// This function will never panic, but it may return [ `Err`] if the
796
+ /// [ `Receiver`] has disconnected and is no longer able to receive
707
797
/// information.
798
+ ///
799
+ /// [`Err`]: ../../../std/result/enum.Result.html#variant.Err
800
+ /// [`Receiver`]: ../../../std/sync/mpsc/struct.Receiver.html
708
801
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
709
802
pub fn send ( & self , t : T ) -> Result < ( ) , SendError < T > > {
710
803
self . inner . send ( t) . map_err ( SendError )
711
804
}
712
805
713
806
/// Attempts to send a value on this channel without blocking.
714
807
///
715
- /// This method differs from `send` by returning immediately if the
808
+ /// This method differs from [ `send`] by returning immediately if the
716
809
/// channel's buffer is full or no receiver is waiting to acquire some
717
- /// data. Compared with `send`, this function has two failure cases
810
+ /// data. Compared with [ `send`] , this function has two failure cases
718
811
/// instead of one (one for disconnection, one for a full buffer).
719
812
///
720
- /// See `SyncSender::send` for notes about guarantees of whether the
813
+ /// See [ `SyncSender::send`] for notes about guarantees of whether the
721
814
/// receiver has received the data or not if this function is successful.
815
+ ///
816
+ /// [`send`]: ../../../std/sync/mpsc/struct.Sender.html#method.send
817
+ /// [`SyncSender::send`]: ../../../std/sync/mpsc/struct.SyncSender.html#method.send
722
818
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
723
819
pub fn try_send ( & self , t : T ) -> Result < ( ) , TrySendError < T > > {
724
820
self . inner . try_send ( t)
@@ -819,15 +915,18 @@ impl<T> Receiver<T> {
819
915
///
820
916
/// This function will always block the current thread if there is no data
821
917
/// available and it's possible for more data to be sent. Once a message is
822
- /// sent to the corresponding `Sender`, then this receiver will wake up and
918
+ /// sent to the corresponding [ `Sender`] , then this receiver will wake up and
823
919
/// return that message.
824
920
///
825
- /// If the corresponding `Sender` has disconnected, or it disconnects while
826
- /// this call is blocking, this call will wake up and return `Err` to
921
+ /// If the corresponding [ `Sender`] has disconnected, or it disconnects while
922
+ /// this call is blocking, this call will wake up and return [ `Err`] to
827
923
/// indicate that no more messages can ever be received on this channel.
828
924
/// However, since channels are buffered, messages sent before the disconnect
829
925
/// will still be properly received.
830
926
///
927
+ /// [`Sender`]: ../../../std/sync/mpsc/struct.Sender.html
928
+ /// [`Err`]: ../../../std/result/enum.Result.html#variant.Err
929
+ ///
831
930
/// # Examples
832
931
///
833
932
/// ```
@@ -907,15 +1006,18 @@ impl<T> Receiver<T> {
907
1006
///
908
1007
/// This function will always block the current thread if there is no data
909
1008
/// available and it's possible for more data to be sent. Once a message is
910
- /// sent to the corresponding `Sender`, then this receiver will wake up and
1009
+ /// sent to the corresponding [ `Sender`] , then this receiver will wake up and
911
1010
/// return that message.
912
1011
///
913
- /// If the corresponding `Sender` has disconnected, or it disconnects while
914
- /// this call is blocking, this call will wake up and return `Err` to
1012
+ /// If the corresponding [ `Sender`] has disconnected, or it disconnects while
1013
+ /// this call is blocking, this call will wake up and return [ `Err`] to
915
1014
/// indicate that no more messages can ever be received on this channel.
916
1015
/// However, since channels are buffered, messages sent before the disconnect
917
1016
/// will still be properly received.
918
1017
///
1018
+ /// [`Sender`]: ../../../std/sync/mpsc/struct.Sender.html
1019
+ /// [`Err`]: ../../../std/result/enum.Result.html#variant.Err
1020
+ ///
919
1021
/// # Examples
920
1022
///
921
1023
/// ```no_run
@@ -993,16 +1095,40 @@ impl<T> Receiver<T> {
993
1095
}
994
1096
995
1097
/// Returns an iterator that will block waiting for messages, but never
996
- /// `panic!`. It will return `None` when the channel has hung up.
1098
+ /// [`panic!`]. It will return [`None`] when the channel has hung up.
1099
+ ///
1100
+ /// [`panic!`]: ../../../std/macro.panic.html
1101
+ /// [`None`]: ../../../std/option/enum.Option.html#variant.None
1102
+ ///
1103
+ /// # Examples
1104
+ ///
1105
+ /// ```rust
1106
+ /// use std::sync::mpsc::channel;
1107
+ /// use std::thread;
1108
+ ///
1109
+ /// let (send, recv) = channel();
1110
+ ///
1111
+ /// thread::spawn(move || {
1112
+ /// send.send(1u8).unwrap();
1113
+ /// send.send(2u8).unwrap();
1114
+ /// send.send(3u8).unwrap();
1115
+ /// });
1116
+ ///
1117
+ /// for x in recv.iter() {
1118
+ /// println!("Got: {}", x);
1119
+ /// }
1120
+ /// ```
997
1121
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
998
1122
pub fn iter ( & self ) -> Iter < T > {
999
1123
Iter { rx : self }
1000
1124
}
1001
1125
1002
1126
/// Returns an iterator that will attempt to yield all pending values.
1003
1127
/// It will return `None` if there are no more pending values or if the
1004
- /// channel has hung up. The iterator will never `panic!` or block the
1128
+ /// channel has hung up. The iterator will never [ `panic!`] or block the
1005
1129
/// user by waiting for values.
1130
+ ///
1131
+ /// [`panic!`]: ../../../std/macro.panic.html
1006
1132
#[ stable( feature = "receiver_try_iter" , since = "1.15.0" ) ]
1007
1133
pub fn try_iter ( & self ) -> TryIter < T > {
1008
1134
TryIter { rx : self }
0 commit comments