Manual: attempt to explain when to use Ptr{T} vs Ref{T} #14930
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
jiahao
force-pushed
the
cjh/ccall-examples
branch
from
115cbd0 to
3b52cb6
Compare
| The input ``n`` is passed by value, and so the function's input signature is | ||
| simply declared as ``(Csize_t,)`` without any ``Ref`` or ``Ptr`` necessary. | ||
| Furthermore, ``n`` can be any type that is convertable to a ``Csize_t`` | ||
| integer; the ``ccall`` implicitly calls ``convert(Csize_t, n)``. |
There was a problem hiding this comment.
Maybe Base.cconvert(Csize_t, n) to be more accurate.
jiahao
force-pushed
the
cjh/ccall-examples
branch
from
3b52cb6 to
626e7bb
Compare
| without requiring as much manual management of the ``Ptr`` conversions. | ||
| After #2818 is implemented, it will be true that an ``Vector{T}`` will be equivalent to | ||
| an ``Ptr{Ptr{T}}``. That is currently not true, and the conversion must be explicitly. | ||
| In C wrapper code that must handle pointers, ``Ref{T}`` should generally be |
There was a problem hiding this comment.
I first read "C wrapper code" as wrapper code written in C. Maybe say "In code wrapping C function calls" or something like that?
- Remove references to #2818 - Explain when to use `Ptr{T}` and when to use `Ref{T}` correctly. `Ptr` is generally used for return types and fields of types mirroring C structs. `Ref` is generally used for input types, allowing memory managed by either C or Julia to be referenced by `ccall`. - Provide some examples of C wrappers simplified from GSL.jl, with comments delineating the various parts of the `ccall`. - Fix description of `cconvert` in the Auto-conversion section - Better cross-referencing to the standard library - Other minor formatting changes Ref: JuliaMath/GSL.jl#43
jiahao
force-pushed
the
cjh/ccall-examples
branch
from
626e7bb to
a70ecdb
Compare
|
Thanks, the additions are really helpful! |
jiahao
added a commit
that referenced
this pull request
Feb 5, 2016
Manual: attempt to explain when to use Ptr{T} vs Ref{T}
| are passed by value. For C code accepting pointers, ``Ref{T}`` should | ||
| generally be used for the types of input arguments, allowing the use of | ||
| pointers to memory managed by either Julia or C through the implicit call to | ||
| :func:``cconvert``. In contrast, pointers returned by the C function called |
There was a problem hiding this comment.
should these be single backticks with the :func: syntax?
There was a problem hiding this comment.
Looks like it's just that one
jiahao
added a commit
that referenced
this pull request
Feb 5, 2016
| In Julia code wrapping calls to external Fortran routines, all input arguments | ||
| should be declared as of type ``Ref{T}``, as Fortran passes all variables by | ||
| reference. The return type should either be ``Void`` for Fortran subroutines, | ||
| or a ``Ptr{T}`` for Fortran functions returning the type ``T``. |
There was a problem hiding this comment.
the return type should be T for Fortran functions that return T
There was a problem hiding this comment.
Thanks for spotting the error; fixed in 3256421
jiahao
added a commit
that referenced
this pull request
Feb 6, 2016
Return type of Fortran function should be Void or T, not Ptr{T}
ref: #14930 (comment)
| result_array) <cconvert>` unpacks the Julia pointer to a Julia array data | ||
| structure into a form understandable by C. | ||
|
|
||
| Note that for this code to work correctly, ``result_array`` must be declared to |
There was a problem hiding this comment.
this isn't quite accurate – the gc-rooting is performed on the arguments without regards to the signature
There was a problem hiding this comment.
What wording would you suggest instead?
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I've attempted to update the part of the
ccalldocumentation in the manualaccording to my best understanding of current good practices for using
Ptr{T}vs
Ref{T}inccalltype declarations.The current wording summarizes my experiences from maintaining the GSL.jl
wrappers and a better understanding of what
Refdoes from offline discussionswith @jakebolewski, @JeffBezanson and @vtjnash.
Ptr{T}and when to useRef{T}correctly.Ptris generally used for return types and fields of types mirroringC structs.
Refis generally used for input types, allowing memorymanaged by either C or Julia to be referenced by
ccall.Ref: JuliaMath/GSL.jl#43