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::*;