Improve performance annotation docs #17722

lopezm94 · 2016-07-30T17:49:23Z

Continuation of pull request #17700

kshyatt · 2016-07-30T20:38:57Z

doc/manual/performance-tips.rst

@@ -1114,6 +1114,54 @@ properties:
   LLVM auto-vectorization may kick in automatically, leading to no further
   speedup with :obj:`@simd`.

+While :obj:`@simd` needs to be placed in front of a loop, that is not the case
+for :obj:`@inbounds`. It can be placed in front of any expression as long as it
+is inside a function, the only place where it could be outside of a function


Run on sentence here. Turn the comma into a period, I think.

lopezm94 · 2016-07-31T13:56:42Z

Should I improve anything else?

tkelman · 2016-07-31T14:01:14Z

doc/manual/performance-tips.rst

+    in getindex(::Array{Int64,1}, ::Int64) at ./array.jl:309
+    in eval(::Module, ::Any) at ./boot.jl:225
+    in macro expansion at ./REPL.jl:92 [inlined]
+    in (::Base.REPL.##1#2{Base.REPL.REPLBackend})() at ./event.jl:46


did you run this on 0.5? the backtraces should look different now

lopezm94 · 2016-07-31T14:10:17Z

Nope, completely forgot about that after switching branch. Will do that right away

Previous error message was 0.4

lopezm94 · 2016-07-31T18:35:01Z

Backtrace modified

tkelman · 2016-08-01T08:55:38Z

doc/manual/performance-tips.rst

+for :obj:`@inbounds`. It can be placed in front of any expression as long as it
+is inside a function. The only place where it can be outside of a function
+definition is in front of a loop.
+::


This double-colon is malformed RST I think, see the sphinx errors

/home/Tony/julia/doc/manual/performance-tips.rst:1122: ERROR: Unexpected indentation. /home/Tony/julia/doc/manual/performance-tips.rst:1146: ERROR: Unexpected indentation.

lopezm94 · 2016-08-01T11:54:16Z

I can only imagine putting one more newline between :: and the code, I'm clueless about the error. Building the documentations locally with make -C doc html and make -C doc latex I don't get any error. If I may ask, how should I build the documentation?

tkelman · 2016-08-01T11:58:18Z

You have to scroll up to the start of the output, there are a lot of harmless warnings and the actual malformed rst errors are buried at the start of those.

lopezm94 · 2016-08-02T13:32:48Z

It is now fixed, thanks for the help.

kshyatt · 2016-08-02T16:05:26Z

This will fix #13234 as well, right?

lopezm94 · 2016-08-02T22:38:40Z

Yes, I mention it doesn't work on whole functions and a workaround must be done.

tkelman · 2016-08-03T03:48:23Z

@eschnett @blakejohnson does this look all good to you?

eschnett · 2016-08-03T13:41:52Z

doc/manual/performance-tips.rst

+While :obj:`@simd` needs to be placed in front of a loop, that is not the case
+for :obj:`@inbounds`. It can be placed in front of any expression as long as it
+is inside a function. The only place where it can be outside of a function
+definition is in front of a loop.


This information (outside functions only in front of loops) is news to me. Does this mean that a stand-alone statement

@inbounds a[1] = 0

is malformed?

It is not. It just may or may not disable boundscheck depending on many other compiler heuristics.

FWIW, The only place where it can be outside of a function definition is in front of a loop is very misleading....

What should it say? What does malformed mean in programming btw?

Well, it is also just not true. At global scope it is perfectly fine to write:

x = 1 @inbounds x

But whereas without @inbounds this would print 1, with @inbounds it doesn't print anything. However, I think the inbounds meta information is ignored outside of a function.

I would simplify the description to say that @inbounds can be written in front of any expression, and in some expressions this may be useful to limit the scope of what you are declaring to be "in bounds".

lopezm94 · 2016-08-05T18:45:44Z

Would this be alright?

While :obj:`@simd` needs to be placed in front of a loop, that is not the case
for :obj:`@inbounds`. It can be placed in front of any expression, however
in some expressions it may be useful to limit the scope of what you are
declaring to be "in bounds". Not using the macro carefully can lead to
unexpected errors, it will generally work when used inside of a function
definition.

blakejohnson · 2016-08-06T20:48:42Z

How about "it will generally have an effect when used inside a function definition"?

tkelman · 2016-08-07T07:04:08Z

doc/manual/performance-tips.rst

-is inside a function. The only place where it can be outside of a function
-definition is in front of a loop.
+for :obj:`@inbounds`. It can be placed in front of any expression, however
+the compiler isn't always capable of recognizing where to remove bounds check,


Bit of a run-on. Just end this sentence here ("where to remove bounds checks.") and have "Limiting" start a new one.

lopezm94 · 2016-08-15T22:06:30Z

What is the backport pending label for?

lopezm94 · 2016-12-07T00:49:07Z

#17702

blakejohnson · 2017-03-06T17:50:06Z

@lopezm94 could you give me commit access to your branch, following the instructions here:

https://help.github.com/articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork/

I'd like to make a more more edits and then get this merged.

lopezm94 · 2017-03-06T19:48:01Z

Permission given just now @blakejohnson

ViralBShah · 2020-04-30T15:05:10Z

I wonder if we want to use some of this stuff, or close this. @chriselrod Could you help decide, if you have a moment?

chriselrod · 2020-04-30T16:22:54Z

Looking over the PR, it looks like it's mostly about where you can apply the macros?
I think details like "placing @inbounds in front of a function definition or in global scope won't work" are better suited for docs on the individual macros themselves.

It can be placed in front of any expression, however
the compiler isn't always capable of recognizing where to remove bounds check. Limiting the scope of what you are declaring to be "in bounds" can help the
compiler to apply the optimizations.

While I think it's better to limit the scope of @inbounds for other reasons, is this really true, other than the global scope / outside of functions example?

fredrikekre · 2020-04-30T16:33:26Z

I think the docstrings cover this, and if not we should add it there instead. This PR is for the old docsystem and lots have changed so I will just close this.

Improve performance annotation docs

eb010b5

kshyatt added docs This change adds or pertains to documentation performance Must go faster labels Jul 30, 2016

kshyatt reviewed Jul 30, 2016
View reviewed changes

Update performance-tips.rst

b61dfc4

tkelman reviewed Jul 31, 2016
View reviewed changes

Update Error message

cbaadba

Previous error message was 0.4

tkelman reviewed Aug 1, 2016
View reviewed changes

Fix malformed RST

de765cb

eschnett reviewed Aug 3, 2016
View reviewed changes

tkelman added the backport pending 0.5 label Aug 5, 2016

Remove misleading statement

e321636

Update performance-tips.rst

429636b

tkelman reviewed Aug 7, 2016
View reviewed changes

Update performance-tips.rst

469bd48

blakejohnson self-assigned this Mar 3, 2017

JeffBezanson removed the backport pending 0.5 label Aug 14, 2018

fredrikekre closed this Apr 30, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve performance annotation docs #17722

Improve performance annotation docs #17722

lopezm94 commented Jul 30, 2016 •

edited

Loading

kshyatt Jul 30, 2016

lopezm94 commented Jul 31, 2016

tkelman Jul 31, 2016

lopezm94 commented Jul 31, 2016 •

edited

Loading

lopezm94 commented Jul 31, 2016

tkelman Aug 1, 2016

lopezm94 commented Aug 1, 2016

tkelman commented Aug 1, 2016

lopezm94 commented Aug 2, 2016

kshyatt commented Aug 2, 2016

lopezm94 commented Aug 2, 2016

tkelman commented Aug 3, 2016

eschnett Aug 3, 2016 •

edited

Loading

yuyichao Aug 3, 2016

yuyichao Aug 3, 2016

lopezm94 Aug 3, 2016 •

edited

Loading

blakejohnson Aug 3, 2016

lopezm94 commented Aug 5, 2016

blakejohnson commented Aug 6, 2016

tkelman Aug 7, 2016 •

edited

Loading

lopezm94 commented Aug 15, 2016

lopezm94 commented Dec 7, 2016

blakejohnson commented Mar 6, 2017

lopezm94 commented Mar 6, 2017 •

edited

Loading

ViralBShah commented Apr 30, 2020

chriselrod commented Apr 30, 2020 •

edited

Loading

fredrikekre commented Apr 30, 2020

Improve performance annotation docs #17722

Improve performance annotation docs #17722

Conversation

lopezm94 commented Jul 30, 2016 • edited Loading

kshyatt Jul 30, 2016

Choose a reason for hiding this comment

lopezm94 commented Jul 31, 2016

tkelman Jul 31, 2016

Choose a reason for hiding this comment

lopezm94 commented Jul 31, 2016 • edited Loading

lopezm94 commented Jul 31, 2016

tkelman Aug 1, 2016

Choose a reason for hiding this comment

lopezm94 commented Aug 1, 2016

tkelman commented Aug 1, 2016

lopezm94 commented Aug 2, 2016

kshyatt commented Aug 2, 2016

lopezm94 commented Aug 2, 2016

tkelman commented Aug 3, 2016

eschnett Aug 3, 2016 • edited Loading

Choose a reason for hiding this comment

yuyichao Aug 3, 2016

Choose a reason for hiding this comment

yuyichao Aug 3, 2016

Choose a reason for hiding this comment

lopezm94 Aug 3, 2016 • edited Loading

Choose a reason for hiding this comment

blakejohnson Aug 3, 2016

Choose a reason for hiding this comment

lopezm94 commented Aug 5, 2016

blakejohnson commented Aug 6, 2016

tkelman Aug 7, 2016 • edited Loading

Choose a reason for hiding this comment

lopezm94 commented Aug 15, 2016

lopezm94 commented Dec 7, 2016

blakejohnson commented Mar 6, 2017

lopezm94 commented Mar 6, 2017 • edited Loading

ViralBShah commented Apr 30, 2020

chriselrod commented Apr 30, 2020 • edited Loading

fredrikekre commented Apr 30, 2020

lopezm94 commented Jul 30, 2016 •

edited

Loading

lopezm94 commented Jul 31, 2016 •

edited

Loading

eschnett Aug 3, 2016 •

edited

Loading

lopezm94 Aug 3, 2016 •

edited

Loading

tkelman Aug 7, 2016 •

edited

Loading

lopezm94 commented Mar 6, 2017 •

edited

Loading

chriselrod commented Apr 30, 2020 •

edited

Loading