auto merge of #15286 : alexcrichton/rust/channel-stability, r=cmr

* channel() - #[unstable]. This will likely remain forever

* sync_channel(n: int) - #[unstable with comment]. Concerns have ben raised
  about the usage of the term "synchronous channel" because that generally only
  applies to the case where n == 0. If n > 0 then these channels are often
  referred to as buffered channels.

* Sender::send(), SyncSender::send(), Receiver::recv() - #[experimental]. These
  functions directly violate the general guideline of not providing a failing
  and non-failing variant. These functions were explicitly selected for being
  excused from this guideline, but recent discussions have cast doubt on that
  decision. These functions are #[experimental] for now until a decision is made
  as they are candidates for removal.

* Sender::send_opt(), SyncSender::send_opt(), Receiver::recv_opt() - #[unstable
  with a comment]. If the above no-`_opt` functions are removed, these functions
  will be renamed to the non-`_opt` variants.

* SyncSender::try_send(), Receiver::try_recv() - #[unstable with a comment].
  These return types of these functions to not follow general conventions. They
  are consistent with the rest of the api, but not with the rest of the
  libraries. Until their return types are nailed down, these functions are
  #[unstable].

* Receiver::iter() - #[unstable]. This will likely remain forever.

* std::com::select - #[experimental]. The functionality is likely to remain in
  some form forever, but it is highly unlikely to remain in its current form. It
  is unknown how much breakage this will cause if and when the api is
  redesigned, so the entire module and its components are all experimental.

* DuplexStream - #[deprecated]. This type is not composable with other channels
  in terms of selection or other expected locations. It can also not be used
  with ChanWriter and ChanReader, for example. Due to it being only lightly
  used, and easily replaced with two channels, this type is being deprecated and
  slated for removal.

* Clone for {,Sync}Sender - #[unstable]. This will likely remain forever.

Author: bors

src/doc/guide-tasks.md

@@ -457,6 +457,8 @@ the string in response.  The child terminates when it receives `0`.
 Here is the function that implements the child task:
 
 ~~~
+#![allow(deprecated)]
+
 use std::comm::DuplexStream;
 # fn main() {
 fn stringifier(channel: &DuplexStream<String, uint>) {
@@ -481,6 +483,8 @@ response itself is simply the stringified version of the received value,
 Here is the code for the parent task:
 
 ~~~
+#![allow(deprecated)]
+
 use std::comm::duplex;
 # use std::task::spawn;
 # use std::comm::DuplexStream;

src/libsync/comm/duplex.rs

@@ -15,6 +15,10 @@ Higher level communication abstractions.
 */
 
 #![allow(missing_doc)]
+#![deprecated = "This type is replaced by having a pair of channels. This type \
+                 is not fully composable with other channels in terms of \
+                 or possible semantics on a duplex stream. It will be removed \
+                 soon"]
 
 use core::prelude::*;
 

src/libsync/comm/mod.rs

@@ -370,6 +370,7 @@ static RESCHED_FREQ: int = 256;
 
 /// The receiving-half of Rust's channel type. This half can only be owned by
 /// one task
+#[unstable]
 pub struct Receiver<T> {
     inner: Unsafe<Flavor<T>>,
     receives: Cell<uint>,
@@ -380,12 +381,14 @@ pub struct Receiver<T> {
 /// An iterator over messages on a receiver, this iterator will block
 /// whenever `next` is called, waiting for a new message, and `None` will be
 /// returned when the corresponding channel has hung up.
+#[unstable]
 pub struct Messages<'a, T> {
     rx: &'a Receiver<T>
 }
 
 /// The sending-half of Rust's asynchronous channel type. This half can only be
 /// owned by one task, but it can be cloned to send to other tasks.
+#[unstable]
 pub struct Sender<T> {
     inner: Unsafe<Flavor<T>>,
     sends: Cell<uint>,
@@ -395,6 +398,7 @@ pub struct Sender<T> {
 
 /// The sending-half of Rust's synchronous channel type. This half can only be
 /// owned by one task, but it can be cloned to send to other tasks.
+#[unstable = "this type may be renamed, but it will always exist"]
 pub struct SyncSender<T> {
     inner: Arc<Unsafe<sync::Packet<T>>>,
     // can't share in an arc
@@ -404,6 +408,7 @@ pub struct SyncSender<T> {
 /// This enumeration is the list of the possible reasons that try_recv could not
 /// return data when called.
 #[deriving(PartialEq, Clone, Show)]
+#[experimental = "this is likely to be removed in changing try_recv()"]
 pub enum TryRecvError {
     /// This channel is currently empty, but the sender(s) have not yet
     /// disconnected, so data may yet become available.
@@ -416,6 +421,7 @@ pub enum TryRecvError {
 /// This enumeration is the list of the possible error outcomes for the
 /// `SyncSender::try_send` method.
 #[deriving(PartialEq, Clone, Show)]
+#[experimental = "this is likely to be removed in changing try_send()"]
 pub enum TrySendError<T> {
     /// The data could not be sent on the channel because it would require that
     /// the callee block to send the data.
@@ -478,6 +484,7 @@ impl<T> UnsafeFlavor<T> for Receiver<T> {
 /// // Let's see what that answer was
 /// println!("{}", rx.recv());
 /// ```
+#[unstable]
 pub fn channel<T: Send>() -> (Sender<T>, Receiver<T>) {
     let a = Arc::new(Unsafe::new(oneshot::Packet::new()));
     (Sender::new(Oneshot(a.clone())), Receiver::new(Oneshot(a)))
@@ -514,6 +521,8 @@ pub fn channel<T: Send>() -> (Sender<T>, Receiver<T>) {
 /// assert_eq!(rx.recv(), 1i);
 /// assert_eq!(rx.recv(), 2i);
 /// ```
+#[unstable = "this function may be renamed to more accurately reflect the type \
+              of channel that is is creating"]
 pub fn sync_channel<T: Send>(bound: uint) -> (SyncSender<T>, Receiver<T>) {
     let a = Arc::new(Unsafe::new(sync::Packet::new(bound)));
     (SyncSender::new(a.clone()), Receiver::new(Sync(a)))
@@ -547,6 +556,8 @@ impl<T: Send> Sender<T> {
     ///
     /// The purpose of this functionality is to propagate failure among tasks.
     /// If failure is not desired, then consider using the `send_opt` method
+    #[experimental = "this function is being considered candidate for removal \
+                      to adhere to the general guidelines of rust"]
     pub fn send(&self, t: T) {
         if self.send_opt(t).is_err() {
             fail!("sending on a closed channel");
@@ -583,6 +594,7 @@ impl<T: Send> Sender<T> {
     /// drop(rx);
     /// assert_eq!(tx.send_opt(1i), Err(1));
     /// ```
+    #[unstable = "this function may be renamed to send() in the future"]
     pub fn send_opt(&self, t: T) -> Result<(), T> {
         // In order to prevent starvation of other tasks in situations where
         // a task sends repeatedly without ever receiving, we occasionally
@@ -638,6 +650,7 @@ impl<T: Send> Sender<T> {
     }
 }
 
+#[unstable]
 impl<T: Send> Clone for Sender<T> {
     fn clone(&self) -> Sender<T> {
         let (packet, sleeper) = match *unsafe { self.inner() } {
@@ -719,6 +732,8 @@ impl<T: Send> SyncSender<T> {
     /// If failure is not desired, you can achieve the same semantics with the
     /// `SyncSender::send_opt` method which will not fail if the receiver
     /// disconnects.
+    #[experimental = "this function is being considered candidate for removal \
+                      to adhere to the general guidelines of rust"]
     pub fn send(&self, t: T) {
         if self.send_opt(t).is_err() {
             fail!("sending on a closed channel");
@@ -736,6 +751,7 @@ impl<T: Send> SyncSender<T> {
     /// # Failure
     ///
     /// This function cannot fail.
+    #[unstable = "this function may be renamed to send() in the future"]
     pub fn send_opt(&self, t: T) -> Result<(), T> {
         unsafe { (*self.inner.get()).send(t) }
     }
@@ -753,11 +769,14 @@ impl<T: Send> SyncSender<T> {
     /// # Failure
     ///
     /// This function cannot fail
+    #[unstable = "the return type of this function is candidate for \
+                  modification"]
     pub fn try_send(&self, t: T) -> Result<(), TrySendError<T>> {
         unsafe { (*self.inner.get()).try_send(t) }
     }
 }
 
+#[unstable]
 impl<T: Send> Clone for SyncSender<T> {
     fn clone(&self) -> SyncSender<T> {
         unsafe { (*self.inner.get()).clone_chan(); }
@@ -800,6 +819,8 @@ impl<T: Send> Receiver<T> {
     ///
     /// * If blocking is not desired, then the `try_recv` method will attempt to
     ///   peek at a value on this receiver.
+    #[experimental = "this function is being considered candidate for removal \
+                      to adhere to the general guidelines of rust"]
     pub fn recv(&self) -> T {
         match self.recv_opt() {
             Ok(t) => t,
@@ -817,6 +838,7 @@ impl<T: Send> Receiver<T> {
     /// block on a receiver.
     ///
     /// This function cannot fail.
+    #[unstable = "the return type of this function may be altered"]
     pub fn try_recv(&self) -> Result<T, TryRecvError> {
         // If a thread is spinning in try_recv, we should take the opportunity
         // to reschedule things occasionally. See notes above in scheduling on
@@ -881,6 +903,7 @@ impl<T: Send> Receiver<T> {
     ///
     /// If the channel has hung up, then `Err` is returned. Otherwise `Ok` of
     /// the value found on the receiver is returned.
+    #[unstable = "this function may be renamed to recv()"]
     pub fn recv_opt(&self) -> Result<T, ()> {
         loop {
             let new_port = match *unsafe { self.inner() } {
@@ -917,6 +940,7 @@ impl<T: Send> Receiver<T> {
 
     /// Returns an iterator which will block waiting for messages, but never
     /// `fail!`. It will return `None` when the channel has hung up.
+    #[unstable]
     pub fn iter<'a>(&'a self) -> Messages<'a, T> {
         Messages { rx: self }
     }
@@ -1009,6 +1033,7 @@ impl<T: Send> select::Packet for Receiver<T> {
     }
 }
 
+#[unstable]
 impl<'a, T: Send> Iterator<T> for Messages<'a, T> {
     fn next(&mut self) -> Option<T> { self.rx.recv_opt().ok() }
 }

src/libsync/comm/select.rs

@@ -44,6 +44,13 @@
 //! ```
 
 #![allow(dead_code)]
+#![experimental = "This implementation, while likely sufficient, is unsafe and \
+                   likely to be error prone. At some point in the future this \
+                   module will likely be replaced, and it is currently \
+                   unknown how much API breakage that will cause. The ability \
+                   to select over a number of channels will remain forever, \
+                   but no guarantees beyond this are being made"]
+
 
 use core::prelude::*;