From 74e70765ad397418294d357b97f6b87d8a13fe7f Mon Sep 17 00:00:00 2001
From: Trevor Gross <tg@trevorgross.com>
Date: Sat, 24 Jan 2026 13:28:39 -0600
Subject: [PATCH 1/3] hint: Add a recommendation to benchmark with `cold_path`

Other hints have a note recommending benchmarks to ensure they actually
do what is intended. This is also applicable for `cold_path`, so add a
note here.
---
 library/core/src/hint.rs | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/library/core/src/hint.rs b/library/core/src/hint.rs
index 4c050b49bf7e..bf8bbd12d82a 100644
--- a/library/core/src/hint.rs
+++ b/library/core/src/hint.rs
@@ -708,6 +708,10 @@ pub const fn unlikely(b: bool) -> bool {
 /// 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.
 ///
+/// Note that like all hints, the exact effect to codegen is not guaranteed. Using `cold_path`
+/// can actually *decrease* performance if the branch is called more than expected. It is advisable
+/// to perform benchmarks to tell if this function is useful.
+///
 /// # Examples
 ///
 /// ```

From a694b502d4772c6a83e97617270dbe177a93631e Mon Sep 17 00:00:00 2001
From: Trevor Gross <tg@trevorgross.com>
Date: Sat, 24 Jan 2026 15:30:27 -0600
Subject: [PATCH 2/3] hint: Document that `cold_path` can be used to implement
 `(un)likely`

---
 library/core/src/hint.rs | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/library/core/src/hint.rs b/library/core/src/hint.rs
index bf8bbd12d82a..be3800956042 100644
--- a/library/core/src/hint.rs
+++ b/library/core/src/hint.rs
@@ -736,6 +736,38 @@ pub const fn unlikely(b: bool) -> bool {
 ///     }
 /// }
 /// ```
+///
+/// This can also be used to implement `likely` and `unlikely` helpers to hint the condition rather
+/// than the branch:
+///
+/// ```
+/// #![feature(cold_path)]
+/// use core::hint::cold_path;
+///
+/// #[inline(always)]
+/// pub const fn likely(b: bool) -> bool {
+///     if !b {
+///         cold_path();
+///     }
+///     b
+/// }
+///
+/// #[inline(always)]
+/// pub const fn unlikely(b: bool) -> bool {
+///     if b {
+///         cold_path();
+///     }
+///     b
+/// }
+///
+/// fn foo(x: i32) {
+///     if likely(x > 0) {
+///         println!("this branch is likely to be taken");
+///     } else {
+///         println!("this branch is unlikely to be taken");
+///     }
+/// }
+/// ```
 #[unstable(feature = "cold_path", issue = "136873")]
 #[inline(always)]
 pub const fn cold_path() {

From 6c0ae9322258e3fe3121561492d041d2d9f3a982 Mon Sep 17 00:00:00 2001
From: Trevor Gross <tg@trevorgross.com>
Date: Sat, 24 Jan 2026 15:26:12 -0600
Subject: [PATCH 3/3] hint: Update the tracking issue for `likely_unlikely`

These were split from the `cold_path` tracking issue.
---
 library/core/src/hint.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/library/core/src/hint.rs b/library/core/src/hint.rs
index be3800956042..f4544304a4a4 100644
--- a/library/core/src/hint.rs
+++ b/library/core/src/hint.rs
@@ -649,7 +649,7 @@ pub const fn must_use<T>(value: T) -> T {
 ///     }
 /// }
 /// ```
-#[unstable(feature = "likely_unlikely", issue = "136873")]
+#[unstable(feature = "likely_unlikely", issue = "151619")]
 #[inline(always)]
 pub const fn likely(b: bool) -> bool {
     crate::intrinsics::likely(b)
@@ -699,7 +699,7 @@ pub const fn likely(b: bool) -> bool {
 ///     }
 /// }
 /// ```
-#[unstable(feature = "likely_unlikely", issue = "136873")]
+#[unstable(feature = "likely_unlikely", issue = "151619")]
 #[inline(always)]
 pub const fn unlikely(b: bool) -> bool {
     crate::intrinsics::unlikely(b)