Skip to content

Commit 9ef8ba2

Browse files
mark-summerfieldKristofferC
authored andcommitted
Minor documentation improvements [#29286]
1 parent 3208679 commit 9ef8ba2

File tree

1 file changed

+23
-22
lines changed

1 file changed

+23
-22
lines changed

doc/src/manual/calling-c-and-fortran-code.md

Lines changed: 23 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ julia> typeof(ans)
7575
Int32
7676
```
7777

78-
`clock` takes no arguments and returns an [`Int32`](@ref). One common gotcha is that a 1-tuple of
78+
`clock` takes no arguments and returns an [`Int32`](@ref). One common mistake is forgetting that a 1-tuple of
7979
argument types must be written with a trailing comma. For example, to call the `getenv` function
8080
to get a pointer to the value of an environment variable, one makes a call like this:
8181

@@ -87,7 +87,7 @@ julia> unsafe_string(path)
8787
"/bin/bash"
8888
```
8989

90-
Note that the argument type tuple must be written as `(Cstring,)`, rather than `(Cstring)`. This
90+
Note that the argument type tuple must be written as `(Cstring,)`, not `(Cstring)`. This
9191
is because `(Cstring)` is just the expression `Cstring` surrounded by parentheses, rather than
9292
a 1-tuple containing `Cstring`:
9393

@@ -101,7 +101,7 @@ julia> (Cstring,)
101101

102102
In practice, especially when providing reusable functionality, one generally wraps [`ccall`](@ref)
103103
uses in Julia functions that set up arguments and then check for errors in whatever manner the
104-
C or Fortran function indicates them, propagating to the Julia caller as exceptions. This is especially
104+
C or Fortran function specifies. And if an error occurs it is thrown as a normal Julia exception. This is especially
105105
important since C and Fortran APIs are notoriously inconsistent about how they indicate error
106106
conditions. For example, the `getenv` C library function is wrapped in the following Julia function,
107107
which is a simplified version of the actual definition from [`env.jl`](https://github.com/JuliaLang/julia/blob/master/base/env.jl):
@@ -146,11 +146,11 @@ function gethostname()
146146
end
147147
```
148148

149-
This example first allocates an array of bytes, then calls the C library function `gethostname`
150-
to fill the array in with the hostname, takes a pointer to the hostname buffer, and converts the
149+
This example first allocates an array of bytes. It then calls the C library function `gethostname`
150+
to populate the array with the hostname. Finally, it takes a pointer to the hostname buffer, and converts the
151151
pointer to a Julia string, assuming that it is a NUL-terminated C string. It is common for C libraries
152152
to use this pattern of requiring the caller to allocate memory to be passed to the callee and
153-
filled in. Allocation of memory from Julia like this is generally accomplished by creating an
153+
populated. Allocation of memory from Julia like this is generally accomplished by creating an
154154
uninitialized array and passing a pointer to its data to the C function. This is why we don't
155155
use the `Cstring` type here: as the array is uninitialized, it could contain NUL bytes. Converting
156156
to a `Cstring` as part of the [`ccall`](@ref) checks for contained NUL bytes and could therefore
@@ -177,7 +177,7 @@ Julia function. The arguments to [`@cfunction`](@ref) are:
177177
178178
!!! note
179179
Currently, only the platform-default C calling convention is supported. This means that
180-
`@cfunction`-generated pointers cannot be used in calls where WINAPI expects `stdcall`
180+
`@cfunction`-generated pointers cannot be used in calls where WINAPI expects a `stdcall`
181181
function on 32-bit Windows, but can be used on WIN64 (where `stdcall` is unified with the
182182
C calling convention).
183183
@@ -193,8 +193,8 @@ each. `compare` is a callback function which takes pointers to two elements `a`
193193
an integer less/greater than zero if `a` should appear before/after `b` (or zero if any order
194194
is permitted).
195195

196-
Now, suppose that we have a 1d array `A` of values in Julia that we want to sort
197-
using the `qsort` function (rather than Julia's built-in `sort` function). Before we worry about
196+
Now, suppose that we have a 1-d array `A` of values in Julia that we want to sort
197+
using the `qsort` function (rather than Julia's built-in `sort` function). Before we consider
198198
calling `qsort` and passing arguments, we need to write a comparison function:
199199

200200
```jldoctest mycompare
@@ -238,7 +238,7 @@ julia> A
238238
4.4
239239
```
240240

241-
As can be seen, `A` is changed to the sorted array `[-2.7, 1.3, 3.1, 4.4]`. Note that Julia
241+
As the example shows, the original Julia array `A` has now been sorted: `[-2.7, 1.3, 3.1, 4.4]`. Note that Julia
242242
[takes care of converting the array to a `Ptr{Cdouble}`](@ref automatic-type-conversion)), computing
243243
the size of the element type in bytes, and so on.
244244

@@ -265,7 +265,7 @@ to the specified type. For example, the following call:
265265
ccall((:foo, "libfoo"), Cvoid, (Int32, Float64), x, y)
266266
```
267267

268-
will behave as if the following were written:
268+
will behave as if it were written like this:
269269

270270
```julia
271271
ccall((:foo, "libfoo"), Cvoid, (Int32, Float64),
@@ -349,7 +349,7 @@ same:
349349

350350
On all systems we currently support, basic C/C++ value types may be translated to Julia types
351351
as follows. Every C type also has a corresponding Julia type with the same name, prefixed by C.
352-
This can help for writing portable code (and remembering that an `int` in C is not the same as
352+
This can help when writing portable code (and remembering that an `int` in C is not the same as
353353
an `Int` in Julia).
354354

355355

@@ -410,7 +410,7 @@ checks and is only meant to improve readability of the call.
410410

411411
!!! warning
412412
For string arguments (`char*`) the Julia type should be `Cstring` (if NUL- terminated data is
413-
expected) or either `Ptr{Cchar}` or `Ptr{UInt8}` otherwise (these two pointer types have the same
413+
expected), or either `Ptr{Cchar}` or `Ptr{UInt8}` otherwise (these two pointer types have the same
414414
effect), as described above, not `String`. Similarly, for array arguments (`T[]` or `T*`), the
415415
Julia type should again be `Ptr{T}`, not `Vector{T}`.
416416

@@ -419,19 +419,19 @@ checks and is only meant to improve readability of the call.
419419
`wint_t`) on all platforms.
420420

421421
!!! warning
422-
A return type of `Union{}` means the function will not return i.e. C++11 `[[noreturn]]` or C11
422+
A return type of `Union{}` means the function will not return, i.e., C++11 `[[noreturn]]` or C11
423423
`_Noreturn` (e.g. `jl_throw` or `longjmp`). Do not use this for functions that return no value
424424
(`void`) but do return, use `Cvoid` instead.
425425

426426
!!! note
427427
For `wchar_t*` arguments, the Julia type should be [`Cwstring`](@ref) (if the C routine expects a
428-
NUL-terminated string) or `Ptr{Cwchar_t}` otherwise. Note also that UTF-8 string data in Julia is
428+
NUL-terminated string), or `Ptr{Cwchar_t}` otherwise. Note also that UTF-8 string data in Julia is
429429
internally NUL-terminated, so it can be passed to C functions expecting NUL-terminated data without
430430
making a copy (but using the `Cwstring` type will cause an error to be thrown if the string itself
431431
contains NUL characters).
432432

433433
!!! note
434-
C functions that take an argument of the type `char**` can be called by using a `Ptr{Ptr{UInt8}}`
434+
C functions that take an argument of type `char**` can be called by using a `Ptr{Ptr{UInt8}}`
435435
type within Julia. For example, C functions of the form:
436436

437437
```c
@@ -450,7 +450,7 @@ checks and is only meant to improve readability of the call.
450450
are provided as *hidden arguments*. Type and position of these arguments in the list are compiler
451451
specific, where compiler vendors usually default to using `Csize_t` as type and append the hidden
452452
arguments at the end of the argument list. While this behaviour is fixed for some compilers (GNU),
453-
others *optionally* permit placing hidden arguments directly after the character argument (Intel,PGI).
453+
others *optionally* permit placing hidden arguments directly after the character argument (Intel, PGI).
454454
For example, Fortran subroutines of the form
455455

456456
```fortran
@@ -479,7 +479,7 @@ checks and is only meant to improve readability of the call.
479479

480480
### Struct Type Correspondences
481481

482-
Composite types, aka `struct` in C or `TYPE` in Fortran90 (or `STRUCTURE` / `RECORD` in some variants
482+
Composite types such as `struct` in C or `TYPE` in Fortran90 (or `STRUCTURE` / `RECORD` in some variants
483483
of F77), can be mirrored in Julia by creating a `struct` definition with the same
484484
field layout.
485485

@@ -855,12 +855,12 @@ When passing data to a [`ccall`](@ref), it is best to avoid using the [`pointer`
855855
Instead define a convert method and pass the variables directly to the [`ccall`](@ref). [`ccall`](@ref)
856856
automatically arranges that all of its arguments will be preserved from garbage collection until
857857
the call returns. If a C API will store a reference to memory allocated by Julia, after the [`ccall`](@ref)
858-
returns, you must arrange that the object remains visible to the garbage collector. The suggested
859-
way to handle this is to make a global variable of type `Array{Ref,1}` to hold these values, until
858+
returns, you must ensure that the object remains visible to the garbage collector. The suggested
859+
way to do this is to make a global variable of type `Array{Ref,1}` to hold these values, until
860860
the C library notifies you that it is finished with them.
861861

862862
Whenever you have created a pointer to Julia data, you must ensure the original data exists until
863-
you are done with using the pointer. Many methods in Julia such as [`unsafe_load`](@ref) and
863+
you have finished using the pointer. Many methods in Julia such as [`unsafe_load`](@ref) and
864864
[`String`](@ref) make copies of data instead of taking ownership of the buffer, so that it is
865865
safe to free (or alter) the original data without affecting Julia. A notable exception is
866866
[`unsafe_wrap`](@ref) which, for performance reasons, shares (or can be told to take ownership of) the
@@ -888,7 +888,8 @@ when wrapping libraries that contain many similar functions.
888888
A similar example can be constructed for [`@cfunction`](@ref).
889889

890890
However, doing this will also be very slow and leak memory, so you should usually avoid this and instead keep
891-
reading. The next section discusses how to use indirect calls to efficiently accomplish a similar effect.
891+
reading.
892+
The next section discusses how to use indirect calls to efficiently achieve a similar effect.
892893

893894
## Indirect Calls
894895

0 commit comments

Comments
 (0)