From 58133ae360ff759d444f7743ec7ac55c9eb7b10b Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Mon, 30 Jun 2014 15:10:57 -0700 Subject: [PATCH] Apply stability attributes to std::comm * 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. --- src/doc/guide-tasks.md | 4 ++++ src/libsync/comm/duplex.rs | 4 ++++ src/libsync/comm/mod.rs | 25 +++++++++++++++++++++++++ src/libsync/comm/select.rs | 7 +++++++ 4 files changed, 40 insertions(+) diff --git a/src/doc/guide-tasks.md b/src/doc/guide-tasks.md index 81d7f37d6fbcc..9021b761954d0 100644 --- a/src/doc/guide-tasks.md +++ b/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) { @@ -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; diff --git a/src/libsync/comm/duplex.rs b/src/libsync/comm/duplex.rs index 4ab2ac97cc157..44dd63cbf6c01 100644 --- a/src/libsync/comm/duplex.rs +++ b/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::*; diff --git a/src/libsync/comm/mod.rs b/src/libsync/comm/mod.rs index 665f94d80b237..6c09a021c4338 100644 --- a/src/libsync/comm/mod.rs +++ b/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 { inner: Unsafe>, receives: Cell, @@ -380,12 +381,14 @@ pub struct Receiver { /// 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 } /// 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 { inner: Unsafe>, sends: Cell, @@ -395,6 +398,7 @@ pub struct Sender { /// 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 { inner: Arc>>, // can't share in an arc @@ -404,6 +408,7 @@ pub struct SyncSender { /// 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 { /// 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 UnsafeFlavor for Receiver { /// // Let's see what that answer was /// println!("{}", rx.recv()); /// ``` +#[unstable] pub fn channel() -> (Sender, Receiver) { 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() -> (Sender, Receiver) { /// 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(bound: uint) -> (SyncSender, Receiver) { let a = Arc::new(Unsafe::new(sync::Packet::new(bound))); (SyncSender::new(a.clone()), Receiver::new(Sync(a))) @@ -547,6 +556,8 @@ impl Sender { /// /// 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 Sender { /// 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 Sender { } } +#[unstable] impl Clone for Sender { fn clone(&self) -> Sender { let (packet, sleeper) = match *unsafe { self.inner() } { @@ -719,6 +732,8 @@ impl SyncSender { /// 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 SyncSender { /// # 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 SyncSender { /// # 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> { unsafe { (*self.inner.get()).try_send(t) } } } +#[unstable] impl Clone for SyncSender { fn clone(&self) -> SyncSender { unsafe { (*self.inner.get()).clone_chan(); } @@ -800,6 +819,8 @@ impl Receiver { /// /// * 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 Receiver { /// block on a receiver. /// /// This function cannot fail. + #[unstable = "the return type of this function may be altered"] pub fn try_recv(&self) -> Result { // 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 Receiver { /// /// 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 { loop { let new_port = match *unsafe { self.inner() } { @@ -917,6 +940,7 @@ impl Receiver { /// 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 select::Packet for Receiver { } } +#[unstable] impl<'a, T: Send> Iterator for Messages<'a, T> { fn next(&mut self) -> Option { self.rx.recv_opt().ok() } } diff --git a/src/libsync/comm/select.rs b/src/libsync/comm/select.rs index 8d56f9a003b3f..230bca624f5a7 100644 --- a/src/libsync/comm/select.rs +++ b/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::*;