Added cold_path()

Author: x17jiri

library/core/src/hint.rs

@@ -529,6 +529,8 @@ pub const fn must_use<T>(value: T) -> T {
 ///     likely(a || b) => a || likely(b)
 /// ```
 ///
+/// See also the function `cold_path()` which may be more appropriate for idiomatic Rust code.
+///
 /// # Examples
 ///
 /// ```
@@ -581,6 +583,8 @@ pub const fn likely(b: bool) -> bool {
 ///     unlikely(a || b) => unlikely(a) || unlikely(b)
 /// ```
 ///
+/// See also the function `cold_path()` which may be more appropriate for idiomatic Rust code.
+///
 /// # Examples
 ///
 /// ```
@@ -613,3 +617,37 @@ pub const fn likely(b: bool) -> bool {
 pub const fn unlikely(b: bool) -> bool {
     crate::intrinsics::unlikely(b)
 }
+
+/// Hints to the compiler that given path is cold, i.e., unlikely to be taken. The compiler may
+/// choose to optimize paths that are not cold at the expense of paths that are cold.
+///
+/// # Examples
+///
+/// ```
+/// #![feature(cold_path)]
+/// use core::hint::cold_path;
+///
+/// fn foo(x: &[i32]) {
+///     if let Some(first) = x.get(0) {
+///         // this is the fast path
+///     } else {
+///         // this path is unlikely
+///         cold_path();
+///     }
+/// }
+///
+/// fn bar(x: i32) -> i32 {
+///     match x {
+///         1 => 10,
+///         2 => 100,
+///         3 => { cold_path(); 1000 }, // this branch is unlikely
+///         _ => { cold_path(); 10000 }, // this is also unlikely
+///     }
+/// }
+/// ```
+#[unstable(feature = "cold_path", issue = "none")]
+#[rustc_nounwind]
+#[inline(always)]
+pub fn cold_path() {
+    crate::intrinsics::cold_path()
+}