From 99c0c520aff7f9858340406631d9de763a743d41 Mon Sep 17 00:00:00 2001 From: Lucas Morales Date: Sat, 23 Sep 2017 18:28:08 -0400 Subject: docs improvement std::sync::{PoisonError, TryLockError} --- src/libstd/sys_common/poison.rs | 57 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 55 insertions(+), 2 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/sys_common/poison.rs b/src/libstd/sys_common/poison.rs index 3c61593acc5..934ac3edbf1 100644 --- a/src/libstd/sys_common/poison.rs +++ b/src/libstd/sys_common/poison.rs @@ -65,6 +65,31 @@ pub struct Guard { /// each lock, but once a lock is poisoned then all future acquisitions will /// return this error. /// +/// # Examples +/// +/// ``` +/// use std::sync::{Arc, Mutex}; +/// use std::thread; +/// +/// let mutex = Arc::new(Mutex::new(1)); +/// +/// // poison the mutex +/// let c_mutex = mutex.clone(); +/// let _ = thread::spawn(move || { +/// let mut data = c_mutex.lock().unwrap(); +/// *data = 2; +/// panic!(); +/// }).join(); +/// +/// match mutex.lock() { +/// Ok(_) => unreachable!(), +/// Err(p_err) => { +/// let data = p_err.get_ref(); +/// println!("recovered: {}", data); +/// } +/// }; +/// ``` +/// /// [`Mutex`]: ../../std/sync/struct.Mutex.html /// [`RwLock`]: ../../std/sync/struct.RwLock.html #[stable(feature = "rust1", since = "1.0.0")] @@ -72,10 +97,16 @@ pub struct PoisonError { guard: T, } -/// An enumeration of possible errors which can occur while calling the -/// [`try_lock`] method. +/// An enumeration of possible errors associated with a [`TryLockResult`] which +/// can occur while trying to aquire a lock, from the [`try_lock`] method on a +/// [`Mutex`] or the [`try_read`] and [`try_write`] methods on an [`RwLock`]. /// +/// [`Mutex`]: struct.Mutex.html +/// [`RwLock`]: struct.RwLock.html +/// [`TryLockResult`]: type.TryLockResult.html /// [`try_lock`]: struct.Mutex.html#method.try_lock +/// [`try_read`]: struct.RwLock.html#method.try_read +/// [`try_write`]: struct.RwLock.html#method.try_write #[stable(feature = "rust1", since = "1.0.0")] pub enum TryLockError { /// The lock could not be acquired because another thread failed while holding @@ -148,6 +179,28 @@ impl PoisonError { /// Consumes this error indicating that a lock is poisoned, returning the /// underlying guard to allow access regardless. + /// + /// # Examples + /// + /// ``` + /// use std::collections::HashSet; + /// use std::sync::{Arc, Mutex}; + /// use std::thread; + /// + /// let mutex = Arc::new(Mutex::new(HashSet::new())); + /// + /// // poison the mutex + /// let c_mutex = mutex.clone(); + /// let _ = thread::spawn(move || { + /// let mut data = c_mutex.lock().unwrap(); + /// data.insert(10); + /// panic!(); + /// }).join(); + /// + /// let p_err = mutex.lock().unwrap_err(); + /// let data = p_err.into_inner(); + /// println!("recovered {} items", data.len()); + /// ``` #[stable(feature = "sync_poison", since = "1.2.0")] pub fn into_inner(self) -> T { self.guard } -- cgit 1.4.1-3-g733a5 From bc43e1739234727ebddaf475c2851eab00353324 Mon Sep 17 00:00:00 2001 From: Ethan Dagner Date: Sat, 23 Sep 2017 11:47:21 -0600 Subject: Add doc example to HashMap::hasher --- src/libstd/collections/hash/map.rs | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/collections/hash/map.rs b/src/libstd/collections/hash/map.rs index 96af2272578..f28577d257e 100644 --- a/src/libstd/collections/hash/map.rs +++ b/src/libstd/collections/hash/map.rs @@ -691,6 +691,17 @@ impl HashMap /// Returns a reference to the map's [`BuildHasher`]. /// /// [`BuildHasher`]: ../../std/hash/trait.BuildHasher.html + /// + /// # Examples + /// + /// ``` + /// use std::collections::HashMap; + /// use std::collections::hash_map::RandomState; + /// + /// let hasher = RandomState::new(); + /// let map: HashMap = HashMap::with_hasher(hasher); + /// let hasher: &RandomState = map.hasher(); + /// ``` #[stable(feature = "hashmap_public_hasher", since = "1.9.0")] pub fn hasher(&self) -> &S { &self.hash_builder -- cgit 1.4.1-3-g733a5 From 874124b2c73dc764aa83f7ba9711a4170c0aeffc Mon Sep 17 00:00:00 2001 From: David Tolnay Date: Sun, 24 Sep 2017 22:23:26 -0700 Subject: Backport libs stabilizations to 1.21 beta This includes the following stabilizations: - tcpstream_connect_timeout https://github.com/rust-lang/rust/pull/44563 - iterator_for_each https://github.com/rust-lang/rust/pull/44567 - ord_max_min https://github.com/rust-lang/rust/pull/44593 - compiler_fences https://github.com/rust-lang/rust/pull/44595 - needs_drop https://github.com/rust-lang/rust/pull/44639 - vec_splice https://github.com/rust-lang/rust/pull/44640 --- src/liballoc/vec.rs | 12 ++++++------ src/libcore/cmp.rs | 4 ++-- src/libcore/iter/iterator.rs | 2 +- src/libcore/mem.rs | 2 +- src/libcore/sync/atomic.rs | 2 +- src/libstd/net/tcp.rs | 2 +- 6 files changed, 12 insertions(+), 12 deletions(-) (limited to 'src/libstd') diff --git a/src/liballoc/vec.rs b/src/liballoc/vec.rs index 7dd8895c1ae..725d3e15f4a 100644 --- a/src/liballoc/vec.rs +++ b/src/liballoc/vec.rs @@ -1950,7 +1950,7 @@ impl Vec { /// assert_eq!(u, &[1, 2]); /// ``` #[inline] - #[stable(feature = "vec_splice", since = "1.22.0")] + #[stable(feature = "vec_splice", since = "1.21.0")] pub fn splice(&mut self, range: R, replace_with: I) -> Splice where R: RangeArgument, I: IntoIterator { @@ -2553,13 +2553,13 @@ impl<'a, T> InPlace for PlaceBack<'a, T> { /// [`splice()`]: struct.Vec.html#method.splice /// [`Vec`]: struct.Vec.html #[derive(Debug)] -#[stable(feature = "vec_splice", since = "1.22.0")] +#[stable(feature = "vec_splice", since = "1.21.0")] pub struct Splice<'a, I: Iterator + 'a> { drain: Drain<'a, I::Item>, replace_with: I, } -#[stable(feature = "vec_splice", since = "1.22.0")] +#[stable(feature = "vec_splice", since = "1.21.0")] impl<'a, I: Iterator> Iterator for Splice<'a, I> { type Item = I::Item; @@ -2572,18 +2572,18 @@ impl<'a, I: Iterator> Iterator for Splice<'a, I> { } } -#[stable(feature = "vec_splice", since = "1.22.0")] +#[stable(feature = "vec_splice", since = "1.21.0")] impl<'a, I: Iterator> DoubleEndedIterator for Splice<'a, I> { fn next_back(&mut self) -> Option { self.drain.next_back() } } -#[stable(feature = "vec_splice", since = "1.22.0")] +#[stable(feature = "vec_splice", since = "1.21.0")] impl<'a, I: Iterator> ExactSizeIterator for Splice<'a, I> {} -#[stable(feature = "vec_splice", since = "1.22.0")] +#[stable(feature = "vec_splice", since = "1.21.0")] impl<'a, I: Iterator> Drop for Splice<'a, I> { fn drop(&mut self) { // exhaust drain first diff --git a/src/libcore/cmp.rs b/src/libcore/cmp.rs index 6f86f8caad0..e012cbd76ff 100644 --- a/src/libcore/cmp.rs +++ b/src/libcore/cmp.rs @@ -456,7 +456,7 @@ pub trait Ord: Eq + PartialOrd { /// assert_eq!(2, 1.max(2)); /// assert_eq!(2, 2.max(2)); /// ``` - #[stable(feature = "ord_max_min", since = "1.22.0")] + #[stable(feature = "ord_max_min", since = "1.21.0")] fn max(self, other: Self) -> Self where Self: Sized { if other >= self { other } else { self } @@ -472,7 +472,7 @@ pub trait Ord: Eq + PartialOrd { /// assert_eq!(1, 1.min(2)); /// assert_eq!(2, 2.min(2)); /// ``` - #[stable(feature = "ord_max_min", since = "1.22.0")] + #[stable(feature = "ord_max_min", since = "1.21.0")] fn min(self, other: Self) -> Self where Self: Sized { if self <= other { self } else { other } diff --git a/src/libcore/iter/iterator.rs b/src/libcore/iter/iterator.rs index 36bf9633b4a..e9e31065cf8 100644 --- a/src/libcore/iter/iterator.rs +++ b/src/libcore/iter/iterator.rs @@ -518,7 +518,7 @@ pub trait Iterator { /// .for_each(|(i, x)| println!("{}:{}", i, x)); /// ``` #[inline] - #[stable(feature = "iterator_for_each", since = "1.22.0")] + #[stable(feature = "iterator_for_each", since = "1.21.0")] fn for_each(self, mut f: F) where Self: Sized, F: FnMut(Self::Item), { diff --git a/src/libcore/mem.rs b/src/libcore/mem.rs index 669b93120cf..c869054cee8 100644 --- a/src/libcore/mem.rs +++ b/src/libcore/mem.rs @@ -402,7 +402,7 @@ pub fn align_of_val(val: &T) -> usize { /// } /// ``` #[inline] -#[stable(feature = "needs_drop", since = "1.22.0")] +#[stable(feature = "needs_drop", since = "1.21.0")] pub fn needs_drop() -> bool { unsafe { intrinsics::needs_drop::() } } diff --git a/src/libcore/sync/atomic.rs b/src/libcore/sync/atomic.rs index 3dd08e69710..2bb40cb672e 100644 --- a/src/libcore/sync/atomic.rs +++ b/src/libcore/sync/atomic.rs @@ -1752,7 +1752,7 @@ pub fn fence(order: Ordering) { /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed /// [memory barriers]: https://www.kernel.org/doc/Documentation/memory-barriers.txt #[inline] -#[stable(feature = "compiler_fences", since = "1.22.0")] +#[stable(feature = "compiler_fences", since = "1.21.0")] pub fn compiler_fence(order: Ordering) { unsafe { match order { diff --git a/src/libstd/net/tcp.rs b/src/libstd/net/tcp.rs index aff9af66444..8d1e7882e5d 100644 --- a/src/libstd/net/tcp.rs +++ b/src/libstd/net/tcp.rs @@ -167,7 +167,7 @@ impl TcpStream { /// connection request. /// /// [`SocketAddr`]: ../../std/net/enum.SocketAddr.html - #[stable(feature = "tcpstream_connect_timeout", since = "1.22.0")] + #[stable(feature = "tcpstream_connect_timeout", since = "1.21.0")] pub fn connect_timeout(addr: &SocketAddr, timeout: Duration) -> io::Result { net_imp::TcpStream::connect_timeout(addr, timeout).map(TcpStream) } -- cgit 1.4.1-3-g733a5