From 1cfed0d452d739b502c73904d61a1f4496b1acf5 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Wed, 3 Apr 2019 11:19:16 +0300 Subject: be more direct about borrow requirenments --- src/libcore/borrow.rs | 4 ++++ src/libcore/convert.rs | 10 ++++++---- 2 files changed, 10 insertions(+), 4 deletions(-) (limited to 'src/libcore') diff --git a/src/libcore/borrow.rs b/src/libcore/borrow.rs index 89668dc0650..4d58aaca941 100644 --- a/src/libcore/borrow.rs +++ b/src/libcore/borrow.rs @@ -32,6 +32,10 @@ /// on the identical behavior of these additional trait implementations. /// These traits will likely appear as additional trait bounds. /// +/// In particular `Eq`, `Ord` and `Hash` must be equivalent for +/// borrowed and owned values: `x.borrow() == y.borrow()` should give the +/// same result as `x == y`. +/// /// If generic code merely needs to work for all types that can /// provide a reference to related type `T`, it is often better to use /// [`AsRef`] as more types can safely implement it. diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index a6c65e890a5..7b9e19e36a2 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -105,11 +105,13 @@ pub const fn identity(x: T) -> T { x } /// `&T` or write a custom function. /// /// -/// `AsRef` is very similar to, but serves a slightly different purpose than [`Borrow`]: +/// `AsRef` has the same signature as [`Borrow`], but `Borrow` is different in few aspects: /// -/// - Use `AsRef` when the goal is to simply convert into a reference -/// - Use `Borrow` when the goal is related to writing code that is agnostic to -/// the type of borrow and whether it is a reference or value +/// - Unlike `AsRef`, `Borrow` has a blanket impl for any `T`, and can be used to accept either +/// a reference or a value. +/// - `Borrow` also requires that `Hash`, `Eq` and `Ord` for borrowed value are +/// equivalent to those of the owned value. For this reason, if you want to +/// borrow only a single field of a struct you can implement `AsRef`, but not `Borrow`. /// /// [`Borrow`]: ../../std/borrow/trait.Borrow.html /// -- cgit 1.4.1-3-g733a5 From ab3b65737380d2c2a15a868452026df49c58131a Mon Sep 17 00:00:00 2001 From: Christian Date: Wed, 3 Apr 2019 10:54:07 +0200 Subject: Updated the documentation of core::hints::spin_loop and core::sync::spin_loop_hint --- src/libcore/hint.rs | 27 ++++++++++++++++++++------- src/libcore/sync/atomic.rs | 27 ++++++++++++++++++++------- 2 files changed, 40 insertions(+), 14 deletions(-) (limited to 'src/libcore') diff --git a/src/libcore/hint.rs b/src/libcore/hint.rs index d1ccc148654..7d2006e03c4 100644 --- a/src/libcore/hint.rs +++ b/src/libcore/hint.rs @@ -50,15 +50,28 @@ pub unsafe fn unreachable_unchecked() -> ! { intrinsics::unreachable() } -/// Save power or switch hyperthreads in a busy-wait spin-loop. +/// Signals the processor that it is entering a busy-wait spin-loop. /// -/// This function is deliberately more primitive than -/// [`std::thread::yield_now`](../../std/thread/fn.yield_now.html) and -/// does not directly yield to the system's scheduler. -/// In some cases it might be useful to use a combination of both functions. -/// Careful benchmarking is advised. +/// Upon receiving spin-loop signal the processor can optimize its behavior by, for example, saving +/// power or switching hyper-threads. /// -/// On some platforms this function may not do anything at all. +/// This function is different than [`std::thread::yield_now`] which directly yields to the +/// system's scheduler, whereas `spin_loop` only signals the processor that it is entering a +/// busy-wait spin-loop without yielding control to the system's scheduler. +/// +/// Using a busy-wait spin-loop with `spin_loop` is ideally used in situations where a +/// contended lock is held by another thread executed on a different CPU and where the waiting +/// times are relatively small. Because entering busy-wait spin-loop does not trigger the system's +/// scheduler, no overhead for switching threads occurs. However, if the thread holding the +/// contended lock is running on the same CPU, the spin-loop is likely to occupy an entire CPU slice +/// before switching to the thread that holds the lock. If the contending lock is held by a thread +/// on the same CPU or if the waiting times for acquiring the lock are longer, it is often better to +/// use [`std::thread::yield_now`]. +/// +/// **Note**: On platforms that do not support receiving spin-loop hints this function does not +/// do anything at all. +/// +/// [`std::thread::yield_now`]: ../../../std/thread/fn.yield_now.html #[inline] #[unstable(feature = "renamed_spin_loop", issue = "55002")] pub fn spin_loop() { diff --git a/src/libcore/sync/atomic.rs b/src/libcore/sync/atomic.rs index 04a49d25301..26b59969e18 100644 --- a/src/libcore/sync/atomic.rs +++ b/src/libcore/sync/atomic.rs @@ -124,15 +124,28 @@ use fmt; use hint::spin_loop; -/// Save power or switch hyperthreads in a busy-wait spin-loop. +/// Signals the processor that it is entering a busy-wait spin-loop. /// -/// This function is deliberately more primitive than -/// [`std::thread::yield_now`](../../../std/thread/fn.yield_now.html) and -/// does not directly yield to the system's scheduler. -/// In some cases it might be useful to use a combination of both functions. -/// Careful benchmarking is advised. +/// Upon receiving spin-loop signal the processor can optimize its behavior by, for example, saving +/// power or switching hyper-threads. /// -/// On some platforms this function may not do anything at all. +/// This function is different than [`std::thread::yield_now`] which directly yields to the +/// system's scheduler, whereas `spin_loop_hint` only signals the processor that it is entering a +/// busy-wait spin-loop without yielding control to the system's scheduler. +/// +/// Using a busy-wait spin-loop with `spin_loop_hint` is ideally used in situations where a +/// contended lock is held by another thread executed on a different CPU and where the waiting +/// times are relatively small. Because entering busy-wait spin-loop does not trigger the system's +/// scheduler, no overhead for switching threads occurs. However, if the thread holding the +/// contended lock is running on the same CPU, the spin-loop is likely to occupy an entire CPU slice +/// before switching to the thread that holds the lock. If the contending lock is held by a thread +/// on the same CPU or if the waiting times for acquiring the lock are longer, it is often better to +/// use [`std::thread::yield_now`]. +/// +/// **Note**: On platforms that do not support receiving spin-loop hints this function does not +/// do anything at all. +/// +/// [`std::thread::yield_now`]: ../../../std/thread/fn.yield_now.html #[inline] #[stable(feature = "spin_loop_hint", since = "1.24.0")] pub fn spin_loop_hint() { -- cgit 1.4.1-3-g733a5 From becee90cfd9f174ed050c1d4b366fd13d89f1913 Mon Sep 17 00:00:00 2001 From: Christian Date: Wed, 3 Apr 2019 15:47:38 +0200 Subject: Updated the reference in core::hint::spin_loop to the correct relative path. --- src/libcore/hint.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libcore') diff --git a/src/libcore/hint.rs b/src/libcore/hint.rs index 7d2006e03c4..d43e6c49f4c 100644 --- a/src/libcore/hint.rs +++ b/src/libcore/hint.rs @@ -71,7 +71,7 @@ pub unsafe fn unreachable_unchecked() -> ! { /// **Note**: On platforms that do not support receiving spin-loop hints this function does not /// do anything at all. /// -/// [`std::thread::yield_now`]: ../../../std/thread/fn.yield_now.html +/// [`std::thread::yield_now`]: ../../std/thread/fn.yield_now.html #[inline] #[unstable(feature = "renamed_spin_loop", issue = "55002")] pub fn spin_loop() { -- cgit 1.4.1-3-g733a5