From 6b7fdcd3c1c4d29d04c46b89204dac8a8a4db58d Mon Sep 17 00:00:00 2001 From: Axel Viala Date: Wed, 25 Jun 2014 20:15:39 +0200 Subject: [PATCH 1/5] Improve documentation on duplex.rs --- src/libsync/comm/duplex.rs | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/src/libsync/comm/duplex.rs b/src/libsync/comm/duplex.rs index 3840e55bb424d..11dbcec6859e4 100644 --- a/src/libsync/comm/duplex.rs +++ b/src/libsync/comm/duplex.rs @@ -21,13 +21,27 @@ use core::prelude::*; use comm; use comm::{Sender, Receiver, channel}; -/// An extension of `pipes::stream` that allows both sending and receiving. +/// An extension of `pipes::stream` that allows both sending and receiving +/// data over two channels pub struct DuplexStream { tx: Sender, rx: Receiver, } /// Creates a bidirectional stream. +/// +/// # Example +/// ``` +/// use std::comm; +/// +/// let (left, right) = comm::duplex(); +/// +/// left.send(("ABC").to_string()); +/// right.send(123); +/// +/// assert!(left.recv() == 123); +/// assert!(right.recv() == "ABC".to_string()); +/// ``` pub fn duplex() -> (DuplexStream, DuplexStream) { let (tx1, rx1) = channel(); let (tx2, rx2) = channel(); @@ -37,18 +51,27 @@ pub fn duplex() -> (DuplexStream, DuplexStream) { // Allow these methods to be used without import: impl DuplexStream { + /// Send data over the channel. pub fn send(&self, x: S) { self.tx.send(x) } + + /// Send optionnaly data to the channel. pub fn send_opt(&self, x: S) -> Result<(), S> { self.tx.send_opt(x) } + + /// Receive data from the channel. pub fn recv(&self) -> R { self.rx.recv() } + + /// Try to receive data from the channel. pub fn try_recv(&self) -> Result { self.rx.try_recv() } + + /// Receive optionnaly data from the channel. pub fn recv_opt(&self) -> Result { self.rx.recv_opt() } From ecccc78bce33814e550c53826ffcd42f71be29cb Mon Sep 17 00:00:00 2001 From: Axel Viala Date: Wed, 25 Jun 2014 21:22:05 +0200 Subject: [PATCH 2/5] fixup! Typo. --- src/libsync/comm/duplex.rs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/libsync/comm/duplex.rs b/src/libsync/comm/duplex.rs index 11dbcec6859e4..5fbbd260bb16c 100644 --- a/src/libsync/comm/duplex.rs +++ b/src/libsync/comm/duplex.rs @@ -14,7 +14,6 @@ Higher level communication abstractions. */ -#![allow(missing_doc)] use core::prelude::*; @@ -56,7 +55,7 @@ impl DuplexStream { self.tx.send(x) } - /// Send optionnaly data to the channel. + /// Optionally send data to the channel. pub fn send_opt(&self, x: S) -> Result<(), S> { self.tx.send_opt(x) } @@ -71,7 +70,7 @@ impl DuplexStream { self.rx.try_recv() } - /// Receive optionnaly data from the channel. + /// Optionally receive data from the channel. pub fn recv_opt(&self) -> Result { self.rx.recv_opt() } From 00a761d5d6012682499f86aac9da82486e3bb0eb Mon Sep 17 00:00:00 2001 From: Axel Viala Date: Thu, 26 Jun 2014 15:07:41 +0200 Subject: [PATCH 3/5] Add example to DuplexeStream.send_opt. --- src/libsync/comm/duplex.rs | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/src/libsync/comm/duplex.rs b/src/libsync/comm/duplex.rs index 5fbbd260bb16c..d82c4fa1069b4 100644 --- a/src/libsync/comm/duplex.rs +++ b/src/libsync/comm/duplex.rs @@ -14,7 +14,6 @@ Higher level communication abstractions. */ - use core::prelude::*; use comm; @@ -56,6 +55,23 @@ impl DuplexStream { } /// Optionally send data to the channel. + /// + /// # Example + /// ``` + /// use std::comm; + /// let (left, right) = comm::duplex(); + /// left.send("ABC".to_string()); + /// spawn(proc() { + /// right.send(123); + /// assert!(right.recv() == "ABC".to_string()); + /// drop(right); + /// }); + /// assert!(left.recv() == 123); + /// // I force this task to wait because the other have to drop. + /// std::io::timer::sleep(1000); + /// assert_eq!(left.send_opt("ABC".to_string()), + /// Err("ABC".to_string())); + /// ``` pub fn send_opt(&self, x: S) -> Result<(), S> { self.tx.send_opt(x) } From 9f3ad8d9e11b0c2fb4dfd8fb05ac266bf104948e Mon Sep 17 00:00:00 2001 From: Axel Viala Date: Fri, 27 Jun 2014 00:28:13 +0200 Subject: [PATCH 4/5] fixup! Adding example on try_recv and refactoring code on try_send --- src/libsync/comm/duplex.rs | 32 +++++++++++++++++++++++--------- 1 file changed, 23 insertions(+), 9 deletions(-) diff --git a/src/libsync/comm/duplex.rs b/src/libsync/comm/duplex.rs index d82c4fa1069b4..24012216b91c4 100644 --- a/src/libsync/comm/duplex.rs +++ b/src/libsync/comm/duplex.rs @@ -59,18 +59,15 @@ impl DuplexStream { /// # Example /// ``` /// use std::comm; + /// /// let (left, right) = comm::duplex(); + /// /// left.send("ABC".to_string()); - /// spawn(proc() { - /// right.send(123); - /// assert!(right.recv() == "ABC".to_string()); - /// drop(right); - /// }); + /// right.send(123); + /// assert!(right.recv() == "ABC".to_string()); + /// drop(right); /// assert!(left.recv() == 123); - /// // I force this task to wait because the other have to drop. - /// std::io::timer::sleep(1000); - /// assert_eq!(left.send_opt("ABC".to_string()), - /// Err("ABC".to_string())); + /// assert_eq!(left.send_opt("ABC".to_string()), Err("ABC".to_string())); /// ``` pub fn send_opt(&self, x: S) -> Result<(), S> { self.tx.send_opt(x) @@ -82,6 +79,23 @@ impl DuplexStream { } /// Try to receive data from the channel. + /// + /// # Example + /// ``` + /// use std::comm; + /// + /// let (left, right) = comm::duplex(); + /// let a = "ABC".to_string(); + /// let b:u32 = 123; + /// + /// left.send(a.clone()); + /// assert_eq!(right.recv(), a); + /// right.send(b); + /// assert_eq!(left.recv(), b); + /// // Here the channel is empty so it return an error. + /// assert_eq!(left.try_recv(), Err(comm::Empty)); + /// ``` +} pub fn try_recv(&self) -> Result { self.rx.try_recv() } From d6768c7febf026deeaf3717bcbf903e8b26fcd4a Mon Sep 17 00:00:00 2001 From: Axel Viala Date: Sat, 28 Jun 2014 15:44:35 +0200 Subject: [PATCH 5/5] Add documentation derived from Sender.send. --- src/libsync/comm/duplex.rs | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/src/libsync/comm/duplex.rs b/src/libsync/comm/duplex.rs index 24012216b91c4..ca27975be1e5d 100644 --- a/src/libsync/comm/duplex.rs +++ b/src/libsync/comm/duplex.rs @@ -49,7 +49,25 @@ pub fn duplex() -> (DuplexStream, DuplexStream) { // Allow these methods to be used without import: impl DuplexStream { - /// Send data over the channel. + /// Sends a value along this duplex to be received by the corresponding + /// receiver. + /// + /// Rust duplexes are infinitely buffered so this method will never block. + /// + /// # Failure + /// + /// This function will fail if the other end of the duplex has hung up. + /// This means that if the corresponding receiver has fallen out of scope, + /// this function will trigger a fail message saying that a message is being + /// sent on a closed duplex. + /// + /// Note that if this function does not fail, it does not mean that the data + /// will be successfully received. All sends are placed into a queue, so it + /// is possible for a send to succeed (the other end is alive), but then the + /// other end could immediately disconnect. + /// + /// The purpose of this functionality is to propagate failure among tasks. + /// If failure is not desired, then consider using the send_opt method. pub fn send(&self, x: S) { self.tx.send(x) }