add @pure docstring and example

[miguelraz]

I aggregated Chris Rackauckas's and mbauman's discussion form here

https://discourse.julialang.org/t/pure-macro/3871/3

Into the docstring.

[vtjnash]

What’s wrong with recursion?

[miguelraz]

It came up during a Discourse post and @mbauman mentioned the restriction.
https://discourse.julialang.org/t/pure-macro/3871

[vtjnash]

typejoin is pure and does recursion - seems to be doing OK

[miguelraz]

Thanks! Will ammend.

[vtjnash]

I don’t know what regression means. This should just say “Usage can easily lead to whole program corruption or crashes and should be avoided.”

[StefanKarpinski]

Did you mean to say "Usage" rather than "Misuse"? 😂

[vtjnash]

• Uses dispatch on one of its arguments.

[miguelraz]

Thanks!
Clarifying: one, or any of its arguments?

[vtjnash]

Yes, any.

[vtjnash]

delete me (duplicate code)

[vtjnash]

This example isn't wrong, but it will almost certainly be made obsolete by #24362

[vtjnash]

Yes, any.

[vtjnash]

"by all users."

[mschauer]

The definition of what @pure actually does got lost during a later commit. (Even if use is discouraged, the doc-string should inform about use and purpose.)

[vtjnash]

Usage is “do not use”: what’s not to like 😜?

[yurivish]

I think the name of the macro is what makes it so tempting to potential users, even if documented as “really, don’t use this.”. Pure is such a nice word, and people think they know what it means. It’s would be a lot of churn, but is renaming the function to something less exciting something within the realm of possibility for 1.0?

[vtjnash]

within the realm of possibility for 1.0?

Sure. I reserve the right to change the name whenever anyone feels so inclined.

[StefanKarpinski]

I've proposed @hyperpure previously.

[miguelraz]

I can put in the work to get @hyperpure pre 1.0 (this means I can work on this during feature freeze, right?), but would very much like at least a canonical example of where @hyperpure is actually useful.
Any help/ pointers?

[StefanKarpinski]

Just so you're aware, @pure isn't exported so this can be changed at any time.

[miguelraz]

That would explain why I couldn't find examples of it in Base -.-

[YingboMa]

-> % rg '@pure'
NEWS.md
374:    accessible via the `@pure` constructor `Val(c)`. Functions are defined as

test/inference.jl
400:Base.@pure function fpure(a=rand(); b=rand())
416:# Make sure @pure works for functions using the new syntax
417:Base.@pure (fpure2(x::T) where T) = T
709:Base.@pure b20704(@nospecialize(x)) = f20704(x)
720:Base.@pure g20704(::Int) = 1
725:Base.@pure c20704() = (f20704(1.0); 1)
729:Base.@pure function a20704(x)
980:Base.@pure plus1(x) = x + 1

base/inference.jl
78:    actual::Bool  # if true, we obtained `val` by actually calling a @pure function
1599:@pure function type_typeof(@nospecialize(v))
3606:        # TODO: Improve this analysis; if a function is marked @pure we should really

base/broadcast.jl
153:Base.@pure function BroadcastStyle(a::A, b::B) where {A<:AbstractArrayStyle{M},B<:AbstractArrayStyle{N}} where {M,N}

base/irrationals.jl
31:@pure function convert(::Type{Rational{T}}, x::AbstractIrrational) where T<:Integer
47:@pure function (t::Type{T})(x::AbstractIrrational, r::RoundingMode) where T<:Union{Float32,Float64}
80:@pure function rationalize(::Type{T}, x::AbstractIrrational; tol::Real=0) where T
83:@pure function lessrational(rx::Rational{<:Integer}, x::AbstractIrrational)
84:    # an @pure version of `<` for determining if the rationalization of

base/namedtuple.jl
135:@pure function sym_in(x::Symbol, itr::Tuple{Vararg{Symbol}})
142:@pure function merge_names(an::Tuple{Vararg{Symbol}}, bn::Tuple{Vararg{Symbol}})
152:@pure function merge_types(names::Tuple{Vararg{Symbol}}, a::Type{<:NamedTuple}, b::Type{<:NamedTuple})

base/linalg/linalg.jl
20:    @propagate_inbounds, @pure, reduce, typed_vcat

base/linalg/rowvector.jl
67:@pure check_types(::Type{T1}, ::Type{T2}) where {T1,T2} = T1 === transpose_type(T2) ? nothing :

doc/src/manual/types.md
1347:julia> Base.@pure Val(x) = Val{x}()

There are several places in Julia where @pure is used, so you need to change them too.

[fredrikekre]

Is it really necessary to change the name? Why would that stop people from using it (incorrectly)?
Edit: Presumably, now that we discourage the use of it in the docstring, people will avoid it.

[StefanKarpinski]

Is it really necessary to change the name? Why would that stop people from using it (incorrectly)?

The problem is that a "pure" function has a more familiar sense which this is stricter than. People refer to functions that only depend on their arguments and not on any other mutable program state as being pure. Now technically, if you include the method tables of functions as mutable program state (which it is), then the @pure macro does have this meaning. However, people aren't accustomed to considering method tables of all the functions they use as part of mutable global state, so they don't think of this when applying the @pure macro. Moreover, it's almost impossible for the behavior of a non-trivial method definition not to depend in some way on some method tables, which is why the answer to "is this really pure?" is almost always no, even in seemingly ridiculously simple cases. So the idea behind calling it @hyperpure is to serve as a warning to people that it probably doesn't mean what they think it means. Then again, it's technically accurate and it's not an exported macro, so maybe just documenting the method table part is sufficient.

[mbauman]

I would still strongly support this change.

$ ack --type=julia '@pure' ALL_PACKAGES | wc -l
396

Just in my skimming through, I'd imagine that's at least 300 too many.