docstr to explaing >100% compilation time in @time

[Krastanov]

This caused me a minor confusion when seeing @time reporting >100% compilation time. To me, the original docstring sounded like some compilation time is skipped altogether in the reporting, but it seems it is skipped only in the denominator, not in the numerator.

Feel free to close if too minor, or if my interpretation was wrong

[LilithHafner]

It is certainly not too minor! A >100% reported compilation time is certainly worth eliminating or explaining. @IanButterworth may be able to speak on this?

[Krastanov]

Noted!

For context, this came from my questions here:

#47184 (comment)

#47184 (comment)

[rikhuijzer]

This PR adds the comment to @time while @timed and @elapsed have very similar comments and @timev doesn't. I'm not familiar with how duplication is normally handled in Julia docstrings. Maybe the duplication can be removed via a const and maybe a test can be added to check for the mention of @eval in the text to avoid partial updates, that is, PRs where only some of the duplicated texts are updated.

EDIT: Maybe refer from all time-macro's to one central section in the docs with more info, such as using @eval, about timing?

[brenhinkeller]

How about "..., but may still be counted in the reported percentage, potentially even resulting in compilation times >100%. To report this time more accurately, you can ..."

[Krastanov]

I am pretty easy going on this type of redundancy / repetition, but happy to follow other directions. All 3 docstrings updated now, using the more polished phrasing from the above comment.

[IanButterworth]

I'm not sure the >100% isn't a regression. I don't believe it happened at one point. If someone can give a mwe without a package we could perhaps explore it.

[brenhinkeller]

The >100% thing is specifically something that's happening on #47184 -- let me see if I can find an mwe

[brenhinkeller]

Ah, the first place I saw it was also when plotting with Makie: #47184 (comment)
so pretty much the same as @Krastanov 's example.

FWIW, my example in that comment actually doesn't seem to reproduce anymore on the latest build of that PR though!

[Krastanov]

@IanButterworth , here is a MWE of >100% compile time that does not require a package installation:

On the nightly just after merging the pkgimages PR

julia> double(x::Real) = 2x
       calldouble(container) = double(container[1])
       calldouble2(container) = calldouble(container)
calldouble2 (generic function with 1 method)

julia> @time @eval calldouble([1.0])
  0.015989 seconds (9.68 k allocations: 636.003 KiB, 41.47% compilation time)
2.0

julia> @time @eval calldouble2(1.0)
  0.012463 seconds (3.53 k allocations: 250.709 KiB, 111.08% compilation time)
2.0

julia> versioninfo()
Julia Version 1.10.0-DEV.204
Commit a2db90fe8d9 (2022-12-27 13:46 UTC)
Platform Info:
  OS: Linux (x86_64-linux-gnu)
  CPU: 16 × AMD Ryzen 7 1700 Eight-Core Processor
  WORD_SIZE: 64
  LIBM: libopenlibm
  LLVM: libLLVM-14.0.6 (ORCJIT, znver1)
  Threads: 8 on 16 virtual cores

On 1.8.0

julia> double(x::Real) = 2x
       calldouble(container) = double(container[1])
       calldouble2(container) = calldouble(container)
calldouble2 (generic function with 1 method)

julia> @time @eval calldouble([1.0])
  0.012558 seconds (7.12 k allocations: 412.803 KiB, 42.40% compilation time)
2.0

julia> @time @eval calldouble2(1.0)
  0.008551 seconds (3.41 k allocations: 208.565 KiB, 95.67% compilation time)
2.0

julia> versioninfo()
Julia Version 1.8.0
Commit 5544a0fab76 (2022-08-17 13:38 UTC)
Platform Info:
  OS: Linux (x86_64-linux-gnu)
  CPU: 16 × AMD Ryzen 7 1700 Eight-Core Processor
  WORD_SIZE: 64
  LIBM: libopenlibm
  LLVM: libLLVM-13.0.1 (ORCJIT, znver1)
  Threads: 8 on 16 virtual cores

Should I close this and open an issue?

[IanButterworth]

Great, yes please. Thanks