Rollup merge of #77027 - termhn:mul_add_doc_change, r=m-ou-se

Improve documentation for `std::{f32,f64}::mul_add` Makes it more clear that performance improvement is not guaranteed when using FMA, even when the target architecture supports it natively.
rust-lang · Dec 11, 2020 · 1b4ffe4 · 1b4ffe4
2 parents 0c9ef56 + a6d98d8
commit 1b4ffe4
Show file tree

Hide file tree

Showing 2 changed files with 8 additions and 4 deletions.
diff --git a/library/std/src/f32.rs b/library/std/src/f32.rs
@@ -206,8 +206,10 @@ impl f32 {
     /// Fused multiply-add. Computes `(self * a) + b` with only one rounding
     /// error, yielding a more accurate result than an unfused multiply-add.
     ///
-    /// Using `mul_add` can be more performant than an unfused multiply-add if
-    /// the target architecture has a dedicated `fma` CPU instruction.
+    /// Using `mul_add` *may* be more performant than an unfused multiply-add if
+    /// the target architecture has a dedicated `fma` CPU instruction. However,
+    /// this is not always true, and will be heavily dependant on designing
+    /// algorithms with specific target hardware in mind.
     ///
     /// # Examples
     ///

diff --git a/library/std/src/f64.rs b/library/std/src/f64.rs
@@ -206,8 +206,10 @@ impl f64 {
     /// Fused multiply-add. Computes `(self * a) + b` with only one rounding
     /// error, yielding a more accurate result than an unfused multiply-add.
     ///
-    /// Using `mul_add` can be more performant than an unfused multiply-add if
-    /// the target architecture has a dedicated `fma` CPU instruction.
+    /// Using `mul_add` *may* be more performant than an unfused multiply-add if
+    /// the target architecture has a dedicated `fma` CPU instruction. However,
+    /// this is not always true, and will be heavily dependant on designing
+    /// algorithms with specific target hardware in mind.
     ///
     /// # Examples
     ///