@@ -75,7 +75,7 @@ julia> typeof(ans)
75
75
Int32
76
76
```
77
77
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
79
79
argument types must be written with a trailing comma. For example, to call the ` getenv ` function
80
80
to get a pointer to the value of an environment variable, one makes a call like this:
81
81
@@ -87,7 +87,7 @@ julia> unsafe_string(path)
87
87
"/bin/bash"
88
88
```
89
89
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
91
91
is because ` (Cstring) ` is just the expression ` Cstring ` surrounded by parentheses, rather than
92
92
a 1-tuple containing ` Cstring ` :
93
93
@@ -101,7 +101,7 @@ julia> (Cstring,)
101
101
102
102
In practice, especially when providing reusable functionality, one generally wraps [ ` ccall ` ] ( @ref )
103
103
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
105
105
important since C and Fortran APIs are notoriously inconsistent about how they indicate error
106
106
conditions. For example, the ` getenv ` C library function is wrapped in the following Julia function,
107
107
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()
146
146
end
147
147
```
148
148
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
151
151
pointer to a Julia string, assuming that it is a NUL-terminated C string. It is common for C libraries
152
152
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
154
154
uninitialized array and passing a pointer to its data to the C function. This is why we don't
155
155
use the ` Cstring ` type here: as the array is uninitialized, it could contain NUL bytes. Converting
156
156
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:
177
177
178
178
!!! note
179
179
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`
181
181
function on 32-bit Windows, but can be used on WIN64 (where `stdcall` is unified with the
182
182
C calling convention).
183
183
@@ -193,8 +193,8 @@ each. `compare` is a callback function which takes pointers to two elements `a`
193
193
an integer less/greater than zero if ` a ` should appear before/after ` b ` (or zero if any order
194
194
is permitted).
195
195
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
198
198
calling ` qsort ` and passing arguments, we need to write a comparison function:
199
199
200
200
``` jldoctest mycompare
@@ -238,7 +238,7 @@ julia> A
238
238
4.4
239
239
```
240
240
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
242
242
[ takes care of converting the array to a ` Ptr{Cdouble} ` ] (@ref automatic-type-conversion)), computing
243
243
the size of the element type in bytes, and so on.
244
244
@@ -265,7 +265,7 @@ to the specified type. For example, the following call:
265
265
ccall ((:foo , " libfoo" ), Cvoid, (Int32, Float64), x, y)
266
266
```
267
267
268
- will behave as if the following were written:
268
+ will behave as if it were written like this :
269
269
270
270
``` julia
271
271
ccall ((:foo , " libfoo" ), Cvoid, (Int32, Float64),
@@ -349,7 +349,7 @@ same:
349
349
350
350
On all systems we currently support, basic C/C++ value types may be translated to Julia types
351
351
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
353
353
an ` Int ` in Julia).
354
354
355
355
@@ -410,7 +410,7 @@ checks and is only meant to improve readability of the call.
410
410
411
411
!!! warning
412
412
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
414
414
effect), as described above, not ` String ` . Similarly, for array arguments (` T[] ` or ` T* ` ), the
415
415
Julia type should again be ` Ptr{T} ` , not ` Vector{T} ` .
416
416
@@ -419,19 +419,19 @@ checks and is only meant to improve readability of the call.
419
419
` wint_t ` ) on all platforms.
420
420
421
421
!!! 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
423
423
` _Noreturn ` (e.g. ` jl_throw ` or ` longjmp ` ). Do not use this for functions that return no value
424
424
(` void ` ) but do return, use ` Cvoid ` instead.
425
425
426
426
!!! note
427
427
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
429
429
internally NUL-terminated, so it can be passed to C functions expecting NUL-terminated data without
430
430
making a copy (but using the ` Cwstring ` type will cause an error to be thrown if the string itself
431
431
contains NUL characters).
432
432
433
433
!!! 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}} `
435
435
type within Julia. For example, C functions of the form:
436
436
437
437
```c
@@ -450,7 +450,7 @@ checks and is only meant to improve readability of the call.
450
450
are provided as * hidden arguments* . Type and position of these arguments in the list are compiler
451
451
specific, where compiler vendors usually default to using ` Csize_t ` as type and append the hidden
452
452
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).
454
454
For example, Fortran subroutines of the form
455
455
456
456
```fortran
@@ -479,7 +479,7 @@ checks and is only meant to improve readability of the call.
479
479
480
480
### Struct Type Correspondences
481
481
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
483
483
of F77), can be mirrored in Julia by creating a ` struct ` definition with the same
484
484
field layout.
485
485
@@ -855,12 +855,12 @@ When passing data to a [`ccall`](@ref), it is best to avoid using the [`pointer`
855
855
Instead define a convert method and pass the variables directly to the [ ` ccall ` ] ( @ref ) . [ ` ccall ` ] ( @ref )
856
856
automatically arranges that all of its arguments will be preserved from garbage collection until
857
857
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
860
860
the C library notifies you that it is finished with them.
861
861
862
862
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
864
864
[ ` String ` ] ( @ref ) make copies of data instead of taking ownership of the buffer, so that it is
865
865
safe to free (or alter) the original data without affecting Julia. A notable exception is
866
866
[ ` 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.
888
888
A similar example can be constructed for [ ` @cfunction ` ] ( @ref ) .
889
889
890
890
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.
892
893
893
894
## Indirect Calls
894
895
0 commit comments