Document how to cast / recast / change type of pointer inside Ptr docs

[freemin7]

It took me a while to figure out how to do this and wished it would be documented here or in a similar place.

[github-actions]

Hello! I am a bot.

Thank you for your pull request!

I have assigned @LilithHafner to this pull request.

@LilithHafner can either choose to review this pull request themselves, or they can choose to find someone else to review this pull request.

Note: If you are a Julia committer, please make sure that your organization membership is public.

[freemin7]

This is a pure change to documentation making it easier for people to mess or observe via Julias memory.
This is only possible through other unsafe methods in the same file. While using reinterpret makes perfect sense
to change the type of pointers i did not consider it but i checked the docs and didn't find it either. Finally i found an issue which had this information and wanted to save others the same hunt.

[LilithHafner]

Thanks! Would you please format this as a see also section? You can grep for "see also" in the julia repo to see examples.

It doesn't necessarily have to be a "see also", but this note should come after the rest of the docstring as it is not core functionality of Ptr.

[freemin7]

I took the syntax from an See also section but decided to add additional information as the documentation of reinterpret does not have a subsection on pointers. It is not necessarily obvious that Ptr is just a type and falls under the generic reinterpret(::Type{Out}, x::In) from reading that doc string to people comming from other languages and it wasn't to me despite me being quite aware of that function. I feel like downgrading this to a "See also" would require adding info the docs of reinterpret to contain the same information (albeit with one more look up).

I also just noticed convert(::Type{Ptr{T}}, p::Ptr) where {T} = bitcast(Ptr{T}, p)::Ptr{T} does the same as reinterpret.

However https://github.com/freemin7/julia/blob/6c425515e68e29944c06852906e2f8754aca2268/base/pointer.jl#L21 is ambigous who deep it refers to.

This turned a bit more complicated then i thought.

I see 3 top level options i have no preference between:

1. Undo changes to Ptr, add see also to convert and possibly cconvert. Write doc string showing how to use convert with pointers and document the property: convert(In, convert(Out, x)) === x and a warning that no exceptions will be raised by it unlike in the base case of convert and that a pointer of non isbits type is ambigous (for reference see below). Check with someone core Julia developer that convert between pointers is not meant to be deprectated and remove/update the ToDo based on their statement.
2. Leave as is.
3. Undo changes to Ptr, add see also to reinterpret. Modify doc string for reinterpret(::Type{Out}, x::In). I am not sure how i would choose to do that. My ideas so far are:
   3.1 Add example on pointers to reinterpret doc string. This would not fit so well with the other examples since it would involve a lot of other functions to explain. A mininal example would be:

unsafe_wrap(Vector{UInt64},reinterpret(Ptr{UInt64},pointer(rand(Float32,6))),3;own=true)

There are smaller minimal examples which involve pointer to integer conversion.

3.2 Add note to reinterpret doc string which explains something special about a pointers
3.3 A warning to reinterpret doc string which explains something special about pointers such as documenting the fact that.

The fundamental issue is that Ptr of non bitstype is ambiguious.
from #30276 (comment)

Any choice {1, 2, 3.1, 3.2, 3.3} is fine by me but also open to hear other ideas.

[LilithHafner]

1. is not ideal because conversion is much more widely used than Ptr, so offering this method to people who query ?convert is less precise than offering it to people who query ?Ptr. 3 suffers from a similar issue.

Perhaps a variant of 2 would be good: adding a sentence after the existing Ptr docstring rather than in the middle of it.

[freemin7]

I added a more sections which elaborates on the role the type T plays in pointers. I think this information is best collected in a central place. It also makes the reinterpret sentence stand out less.

[LilithHafner]

Thanks, this is much better :)

[LilithHafner]

unsafe_wrap is a good see also, but it is not an alternative to Ptr in many cases so this is not appropriate as a "while" clause.

[freemin7]

It is not meant as an alternative to pointers. unsafe_wrap takes a pointer as an argument and if it is a Ptr{T} where T is an abstract type it will still worked, while unsafe_load will throw an error if given such a pointer.

[LilithHafner]

Pointers are not just for arrays. For example, you can get a pointer to a field in an mutable struct.

[vtjnash]

s/immutable/mutable I assume

[freemin7]

"what data type it pointed to." would that be better?

[LilithHafner]

It's still possible to retrieve an object, you just have to know what type you're looking for.

[freemin7]

Well then you would manually de-unionize the pointer and it no longer the "same" pointer.

I will think of a different phrasing.