Skip to content

Commit 7c88c28

Browse files
NHDalySacha0
authored andcommitted
Added docstring to @fastmath macro. (#22359)
* Added docstring to @fastmath macro. Adds docstring to @fastmath macro that explains a bit about what it does, and includes examples how to use it. * Updated per yuyichao's comments Added link to [LLVM Fast-Math flags](http://llvm.org/docs/LangRef.html#fast-math-flags) * Indented docstring first line * added @fastmath to math.md @doc * added link to performance annotations, removed bulleted details * fixed intra-doc link && wrap 92. * added "be careful" warning as well. * s/Executes/Execute/g
1 parent 1df1e42 commit 7c88c28

File tree

3 files changed

+25
-2
lines changed

3 files changed

+25
-2
lines changed

base/fastmath.jl

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@
55
# This module provides versions of math functions that may violate
66
# strict IEEE semantics.
77

8-
# This allows the following transformations:
8+
# This allows the following transformations. For more information see
9+
# http://llvm.org/docs/LangRef.html#fast-math-flags:
910
# nnan: No NaNs - Allow optimizations to assume the arguments and
1011
# result are not NaN. Such optimizations are required to retain
1112
# defined behavior over NaNs, but the value of the result is
@@ -124,6 +125,27 @@ function make_fastmath(symb::Symbol)
124125
end
125126
make_fastmath(expr) = expr
126127

128+
"""
129+
@fastmath expr
130+
131+
Execute a transformed version of the expression, which calls functions that
132+
may violate strict IEEE semantics. This allows the fastest possible operation,
133+
but results are undefined -- be careful when doing this, as it may change numerical
134+
results.
135+
136+
This sets the [LLVM Fast-Math flags](http://llvm.org/docs/LangRef.html#fast-math-flags),
137+
and corresponds to the `-ffast-math` option in clang. See [the notes on performance
138+
annotations](@ref man-performance-annotations) for more details.
139+
140+
# Examples
141+
```jldoctest
142+
julia> @fastmath 1+2
143+
3
144+
145+
julia> @fastmath(sin(3))
146+
0.1411200080598672
147+
```
148+
"""
127149
macro fastmath(expr)
128150
make_fastmath(esc(expr))
129151
end

doc/src/manual/performance-tips.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1082,7 +1082,7 @@ These are some minor points that might help in tight inner loops.
10821082
* Use [`div(x,y)`](@ref) for truncating division of integers instead of [`trunc(x/y)`](@ref), [`fld(x,y)`](@ref)
10831083
instead of [`floor(x/y)`](@ref), and [`cld(x,y)`](@ref) instead of [`ceil(x/y)`](@ref).
10841084

1085-
## Performance Annotations
1085+
## [Performance Annotations](@id man-performance-annotations)
10861086

10871087
Sometimes you can enable better optimization by promising certain program properties.
10881088

doc/src/stdlib/math.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -181,6 +181,7 @@ Base.Math.lbeta
181181
Base.ndigits
182182
Base.widemul
183183
Base.Math.@evalpoly
184+
Base.FastMath.@fastmath
184185
```
185186

186187
## Statistics

0 commit comments

Comments
 (0)