Bug in doc system? And question on "pure" [in docs]; meaning Julia 1.0 is close?

question
documentation

#1

On

‘’’
@pure constructor.*
‘’’

in NEWS.md

and biggest PR ever in Julia:

Congratulation! Wasn’t that the biggest blocker for Julia 1.0 (I recall one post on it, but can’t find it, find this one likely even with it never tagged on 1.0 milestone)?

I believe I know what a pure function is and what @pure does (mark function as such; is there another way, such as self-discovery?).

Searching the docs for @pure I find way to many results (previously I found only a few results on “pure” in 0.6 docs (“stable”) but currently about as many as in 0.7).

With now only one seemingly trivial 0.7 milestone blocker and and 3 on 1.0 it seems to be close:

https://docs.julialang.org/en/latest/manual/interfaces/#man-interfaces-broadcasting-1

*I highlighted @pure and pressed SHIFT-CTRL-K and got “DEBUG” console … “Source map error” on Firefox for Discourse… seems unrelated to content/highlighted text, but how do I get


#2

No, the biggest blocker was overhauling the optimizer to efficiently handle small type unions and the associated iteration protocol change. My impression was that the lazy broadcasting went relatively smoothly, but I’m sure the actual devs will have more insight.


#3

There are many things going on at once in this post. In short, is the problem here that searching the documentation for macros doesn’t give the expected results?


#4

Yes, I did get 6 results at some point searching in Julia 0.6 docs, but even then none really explaining @pure. If there a good link to where it’s documented, or isn’t it simply?

Now I get lots searching for @pure, but also searching for “pure”. I can’t easily know if I could help with documenting or if I have the right idea even myself until the search is too the point.

The relevant NEWS.md item was also missing a PR number.


#5

We should probably just remove @pure from the description in that NEWS item. It’s an unnecessary implementation detail.

@pure itself is totally distinct from either the Val change or broadcasting. It’s an internal macro that has an extremely high standard for purity. So high, in fact, that almost nobody should use it other than Jameson. As such, it is not exported for general use.

Edit: https://github.com/JuliaLang/julia/pull/27349


#6

That would be a good start for a docstring. :wink:


#7

It’s not actually that hard to understand when @pure is safe to use—the definition is quite standard: a function is pure when its result does not alter or depend on any global mutable state. The big caveat is that method tables of generic functions count as global mutable state, so any function that calls a generic function whose method table could be modified is not strictly pure in the sense that @pure promises it is. And it’s actually quite hard to define a Julia function which is pure in this strict sense. After all you can’t do much without calling any generic functions.


#8

This has been stated multiple times on this forum, but people are suggesting @pure anyway when it may be inapplicable from time to time, which is why I think documenting it would be a great thing.

I think that this issue may become more acute with v1.0: many people come to Julia to write fast programs, and the lure of @pure is that it looks like some sort of semi-secret ingredient that is not widely advertised but may make your code even faster.


#9

That’s why I’ve suggested renaming it to @hyperpure or @pureasthedrivensnow Or something to warn people off of it a bit and at least suggest that they should possibly read the docs.


#10

How about @unsafe_pure? That seems to be an established convention.


#11

Yeah, that’s a pretty good name.


#12

I opened a PR https://github.com/JuliaLang/julia/pull/27432


#13

I expect that what I wrote above still applies; while name changes can help, documenting it would be best.