docs: fix remaining uses of "by reference" for calling convention #26447
Conversation
|
Perhaps you could add a link to https://en.m.wikipedia.org/wiki/Evaluation_strategy#Call_by_sharing? I think call by sharing is less known compared to the other strategies. |
StefanKarpinski
force-pushed
the
sk/sharing
branch
from
8a74a9e to
332ee93
Compare
|
Good idea. Updated. |
|
closes #23127 |
doc/src/devdocs/callconv.md
Outdated
| * LLVM scalars and vectors are passed by value. | ||
| * LLVM aggregates (arrays and structs) are passed by reference. | ||
| * LLVM aggregates (arrays and structs) are [passed by | ||
| sharing](https://en.wikipedia.org/wiki/Evaluation_strategy#Call_by_sharing) (i.e. as pointers). |
There was a problem hiding this comment.
This refers to the ABI, so I don't think the call-by-sharing terminology is really necessary or helpful.
| underscore), and so to call a Fortran function via [`ccall`](@ref) you must pass | ||
| the mangled identifier corresponding to the rule followed by your Fortran | ||
| compiler. Also, when calling a Fortran function, all inputs must be passed as | ||
| pointers to heap-allocated values. This applies not only to arrays and other |
There was a problem hiding this comment.
They don't have to be heap-allocated.
StefanKarpinski
force-pushed
the
sk/sharing
branch
4 times, most recently
from
ff4c71a to
6fb38df
Compare
| simply declared as `(Csize_t,)` without any `Ref` or `Ptr` necessary. (If the | ||
| wrapper was calling a Fortran function instead, the corresponding function input | ||
| signature should instead be `(Ref{Csize_t},)`, since Fortran variables are | ||
| passed by pointers.) Furthermore, `n` can be any type that is convertable to a |
There was a problem hiding this comment.
This should still say "by reference", since we're referring to Fortran here.
"GNU Fortran passes most arguments by reference, i.e. by passing a pointer to the data" (https://gcc.gnu.org/onlinedocs/gfortran/Argument-passing-conventions.html)
There was a problem hiding this comment.
It should not since there's a different and conflicting meaning of the term even though Fortran did use it in a different way first.
There was a problem hiding this comment.
IIRC, Fortran actually does pass arguments by reference though, since it doesn't have pointers and the variables themselves are values, not bindings.
There was a problem hiding this comment.
Yes, but from Julia's perspective nothing is "passed by reference" – mutable objects are passed by sharing (via pointers) to a function which cannot change any bindings in the caller but can mutate shared objects.
There was a problem hiding this comment.
Yes, that's fine. But the text above is literally "... Fortran variables are passed by reference". We can reword it to clarify that the subject is Julia "..., since Fortran expects Julia to pass a pointer to the value." But in the above clause, the subject is Fortran. Another way to say it is that "..., since Fortran passes variables by reference, which is equivalent in Julia to passing a pointer"
There was a problem hiding this comment.
That would be fine but saying that they are "passed by pointers" is also correct.
doc/src/manual/arrays.md
Outdated
| while this prevents accidental modification by callees of a value in the caller, | ||
| it makes avoiding unwanted copying of arrays difficult. In Julia, modifications | ||
| made to input arrays within a function will be visible in the parent function. | ||
| Unless a function ends with a `!` indicating that it mutates one or more of its |
There was a problem hiding this comment.
Alternate wording? "By convention, a function name ending with a ! indicates that it will mutate or destroy the value of one or more of its arguments. Callees must make explicit copies to ensure that they don't modify inputs that they don't intent to change. Many non-mutating functions are implemented by calling a function of the same name with an added ! at the end on an explicit copy of the input, and returning that copy."
StefanKarpinski
force-pushed
the
sk/sharing
branch
from
6fb38df to
d29b167
Compare
StefanKarpinski
force-pushed
the
sk/sharing
branch
from
d29b167 to
7692240
Compare
All uses of "by reference" in docs are technically incorrect. Several of the explanations of behavior around this were also wrong. This corrects them. Inspired by #26427.
closes #23127