@@ -597,3 +597,138 @@ pub const fn black_box<T>(dummy: T) -> T {
597597pub const fn must_use < T > ( value : T ) -> T {
598598 value
599599}
600+
601+ /// Hints to the compiler that a branch condition is likely to be true.
602+ /// Returns the value passed to it.
603+ ///
604+ /// It can be used with `if` or boolean `match` expressions.
605+ ///
606+ /// When used outside of a branch condition, it may still influence a nearby branch, but
607+ /// probably will not have any effect.
608+ ///
609+ /// It can also be applied to parts of expressions, such as `likely(a) && unlikely(b)`, or to
610+ /// compound expressions, such as `likely(a && b)`. When applied to compound expressions, it has
611+ /// the following effect:
612+ /// ```text
613+ /// likely(!a) => !unlikely(a)
614+ /// likely(a && b) => likely(a) && likely(b)
615+ /// likely(a || b) => a || likely(b)
616+ /// ```
617+ ///
618+ /// See also the function [`cold_path()`] which may be more appropriate for idiomatic Rust code.
619+ ///
620+ /// # Examples
621+ ///
622+ /// ```
623+ /// #![feature(likely_unlikely)]
624+ /// use core::hint::likely;
625+ ///
626+ /// fn foo(x: i32) {
627+ /// if likely(x > 0) {
628+ /// println!("this branch is likely to be taken");
629+ /// } else {
630+ /// println!("this branch is unlikely to be taken");
631+ /// }
632+ ///
633+ /// match likely(x > 0) {
634+ /// true => println!("this branch is likely to be taken"),
635+ /// false => println!("this branch is unlikely to be taken"),
636+ /// }
637+ ///
638+ /// // Use outside of a branch condition may still influence a nearby branch
639+ /// let cond = likely(x != 0);
640+ /// if cond {
641+ /// println!("this branch is likely to be taken");
642+ /// }
643+ /// }
644+ /// ```
645+ ///
646+ ///
647+ #[ unstable( feature = "likely_unlikely" , issue = "26179" ) ]
648+ #[ inline( always) ]
649+ pub const fn likely ( b : bool ) -> bool {
650+ crate :: intrinsics:: likely ( b)
651+ }
652+
653+ /// Hints to the compiler that a branch condition is unlikely to be true.
654+ /// Returns the value passed to it.
655+ ///
656+ /// It can be used with `if` or boolean `match` expressions.
657+ ///
658+ /// When used outside of a branch condition, it may still influence a nearby branch, but
659+ /// probably will not have any effect.
660+ ///
661+ /// It can also be applied to parts of expressions, such as `likely(a) && unlikely(b)`, or to
662+ /// compound expressions, such as `unlikely(a && b)`. When applied to compound expressions, it has
663+ /// the following effect:
664+ /// ```text
665+ /// unlikely(!a) => !likely(a)
666+ /// unlikely(a && b) => a && unlikely(b)
667+ /// unlikely(a || b) => unlikely(a) || unlikely(b)
668+ /// ```
669+ ///
670+ /// See also the function [`cold_path()`] which may be more appropriate for idiomatic Rust code.
671+ ///
672+ /// # Examples
673+ ///
674+ /// ```
675+ /// #![feature(likely_unlikely)]
676+ /// use core::hint::unlikely;
677+ ///
678+ /// fn foo(x: i32) {
679+ /// if unlikely(x > 0) {
680+ /// println!("this branch is unlikely to be taken");
681+ /// } else {
682+ /// println!("this branch is likely to be taken");
683+ /// }
684+ ///
685+ /// match unlikely(x > 0) {
686+ /// true => println!("this branch is unlikely to be taken"),
687+ /// false => println!("this branch is likely to be taken"),
688+ /// }
689+ ///
690+ /// // Use outside of a branch condition may still influence a nearby branch
691+ /// let cond = unlikely(x != 0);
692+ /// if cond {
693+ /// println!("this branch is likely to be taken");
694+ /// }
695+ /// }
696+ /// ```
697+ #[ unstable( feature = "likely_unlikely" , issue = "26179" ) ]
698+ #[ inline( always) ]
699+ pub const fn unlikely ( b : bool ) -> bool {
700+ crate :: intrinsics:: unlikely ( b)
701+ }
702+
703+ /// Hints to the compiler that given path is cold, i.e., unlikely to be taken. The compiler may
704+ /// choose to optimize paths that are not cold at the expense of paths that are cold.
705+ ///
706+ /// # Examples
707+ ///
708+ /// ```
709+ /// #![feature(cold_path)]
710+ /// use core::hint::cold_path;
711+ ///
712+ /// fn foo(x: &[i32]) {
713+ /// if let Some(first) = x.get(0) {
714+ /// // this is the fast path
715+ /// } else {
716+ /// // this path is unlikely
717+ /// cold_path();
718+ /// }
719+ /// }
720+ ///
721+ /// fn bar(x: i32) -> i32 {
722+ /// match x {
723+ /// 1 => 10,
724+ /// 2 => 100,
725+ /// 3 => { cold_path(); 1000 }, // this branch is unlikely
726+ /// _ => { cold_path(); 10000 }, // this is also unlikely
727+ /// }
728+ /// }
729+ /// ```
730+ #[ unstable( feature = "cold_path" , issue = "26179" ) ]
731+ #[ inline( always) ]
732+ pub const fn cold_path ( ) {
733+ crate :: intrinsics:: cold_path ( )
734+ }
0 commit comments