Ref docstring should note clearly that it's an abstract type

[DanielVandH]

The docstring for Ref gives no indication that it's an abstract type (or, if it does and I've missed it, it certainly isn't clear). I think there should be a note or admonition warning that the type Ref{T} is an abstract type, since I don't believe it is as widely known that this is the case.

Indeed, searching for ::Ref in package codes shows a good amount of code that uses it as the type for a field in a struct, which I imagine the majority of authors are doing under the impression that it's a concrete type

[MasonProtter]

Just to lay some bread crumbs so it's easier to follow up, here's at least one connected issue: #49004

The docstring for Ref probably just needs to be totally rewritten.

My preference would be that we just take the docstring from Ref and place it on RefValue instead, and then export RefValue. The docstring for Ref can then be rewritten from scratch.

[DanielVandH]

Putting the docstring onto RefValue, and cleaning it up a bit, also has the benefit that it can be better explained how Ref is commonly used for allowing a field to be mutated in a struct, just like how Ref briefly mentions at the end that it is sometimes used in broadcasting.

[vtjnash]

RefValue is not public, intentionally though. Users that want a mutable field should be using mutable since it is much faster than RefValue.

[MasonProtter]

Why is RefValue intentionally not public though? Maybe that intention wasn't such a good idea in hindsight.

Users that want a mutable field should be using mutable since it is much faster than RefValue.

Mutable fields are not the only use-case for something like this. For example, there's

const x::RefValue{T} = Ref{T}()

and many other legitimate reasons to want to have a zero-dimensional indexable, mutable container.

[MasonProtter]

Another case is things like

function f(rx::Ref)
    x = rx[]
    do_something(x)
end

but since the contract for Ref is completely broken by all of its subtypes except RefValue, this is not actually a valid generic function, and it should only be accepting f(::RefValue).

julia> function f(rx::Ref{<:Number})
           x = rx[]
           x + 1
       end;

julia> f(Ref(1))
2

julia> f(Ptr{Int}(1))
ERROR: MethodError: no method matching getindex(::Ptr{Int64})
The function `getindex` exists, but no method is defined for this combination of argument types.

Closest candidates are:
  getindex(::Ref, ::CartesianIndex{0})
   @ Base multidimensional.jl:1950

Stacktrace:
 [1] f(rx::Ptr{Int64})
   @ Main ./REPL[55]:2
 [2] top-level scope
   @ REPL[58]:1

[DanielVandH]

As mentioned, Ref is definitely still valuable for this purpose, and it's certainly used frequently enough that I think making RefValue public could be valuable. Even if not, at the very least it would still be useful to clarify the type of Ref in its docstring - not everyone is aware of this. It doesn't help that a lot of abstract types have the prefix Abstract while Ref doesn't, making it something you'd have no reason to assume could be abstract in the first place.

Making RefValue public or otherwise is maybe worth its own issue since these are two separate (although very closely related) problems

[vtjnash]

const x::RefValue{T} = Ref{T}()

This probably should not be a legal expression anymore, since you are declaring it both mutable and constant, and Keno's changes are going to disallow that.

it should only be accepting

There are many other subtypes of Ref that would work fine there. The Ptr case doesn't violate any API, it just doesn't have any data there accessible to Julia (similar to how other Ref objects will throw if the value contained inside is #undef or is referencing something out of bounds)

[KristofferC]

This probably should not be a legal expression anymore, since you are declaring it both mutable and constant,

Could you elaborate on this. What is different about this and a constant vector or dict? The constness is referring to the binding?

[vtjnash]

After Keno's change, the ::Type part of the expression makes a mutable binding in one world. The const part then replaces and shadows that in a different world.

[MasonProtter]

This probably should not be a legal expression anymore, since you are declaring it both mutable and constant, and Keno's changes are going to disallow that.

That'd be quite the breaking change.

help?> const
search: const isconst count cond cosh cosd conj! conj cos cot cosc convert codeunit count!

  const

  const is used to declare global variables whose values will not change. In almost all code (and particularly performance sensitive code) global variables
  should be declared constant in this way.

  const x = 5

  Multiple variables can be declared within a single const:

  const y, z = 7, 11

  Note that const only applies to one = operation, therefore const x = y = 1 declares x to be constant but not y. On the other hand, const x = const y = 1
  declares both x and y constant.

  Note that "constant-ness" does not extend into mutable containers; only the association between a variable and its value is constant. If x is an array or
  dictionary (for example) you can still modify, add, or remove elements.

  In some cases changing the value of a const variable gives a warning instead of an error. However, this can produce unpredictable behavior or corrupt the state
  of your program, and so should be avoided. This feature is intended only for convenience during interactive use.

in particular, note that it's explicitly documented behaviour that const refers to the binding and does not have any bearing on whether the value its bound to is mutable.

This is very widely used behaviour in the ecosystem

[johnomotani]

Users that want a mutable field should be using mutable since it is much faster than RefValue.

@vtjnash could you clarify this please? I thought the general performance advice is "use an immutable struct instead of a mutable struct". If I have some gigantic struct with 100 fields, and 99 of those can be immutable but the 100'th is a Bool I want to be able to toggle between true/false, your statement implies that I should use a mutable struct but I would find that surprising!

Edit: just to add that I tripped up on this issue recently. I definitely agree that the documentation should be clearer about the fact that Ref is an abstract type.

[vtjnash]

Yes, a mutable struct would probably be much better there most of the time, even if only because of the number of constant fields. The general advice is wrong, since it only applies to specific cases (albeit frequent cases, it is not general)

[nsajko]

Duplicate of #38133.