调用 C 和 Fortran 代码¶

创建与 C 兼容的 Julia 函数指针¶

可以把 Julia 函数传递给本地的接受函数指针为输入的 C 函数。 比如，

typedef returntype (*functiontype)(argumenttype,...)

函数 cfunction() 会生成对应的与 C 兼容的函数指针来调用 Julia 的库函数。

cfunction() 的参数形式如下 :

1. 一个 Julia 函数
2. 返回类型
3. 输入的类型的多元组

一个经典的例子就是 C 标准库的 qsort， 声明为:

void qsort(void *base, size_t nmemb, size_t size,
           int(*compare)(const void *a, const void *b));

base 是长度为 nmemb 数组指针， 所有的元素都是 size 字节， compare 是一个回调函数， 其输入为两个指针， 返回为一个小于/大于零的整数。 假设我们有一个 Julia 里的一维数组 A， 希望调用 qsort 进行排序(而不是用 Julia 内部的 sort 函数)。 我们得先写一个关于任意类型 T 的比较函数:

function mycompare{T}(a::T, b::T)
    return convert(Cint, a < b ? -1 : a > b ? +1 : 0)::Cint
end

注意， 我们必须仔细处理返回类型: qsort 需要函数返回一个 C int， 所以我们需要用 convert 和 typeassert 保证返回的是一个 Cint。

为了将这个函数传递到 C， 我们还需用 cfunction 得到它的地址:

const mycompare_c = cfunction(mycompare, Cint, (Ref{Cdouble}, Ref{Cdouble}))

cfunction() 要接受三个参数: Julia 函数 (mycompare), 返回类型 (Cint), and 参数类型的多元组, 来对元素为 Cdouble (Float64) 的数组进行排序。

最终调用 qsort 如下:

A = [1.3, -2.7, 4.4, 3.1]
ccall(:qsort, Void, (Ptr{Cdouble}, Csize_t, Csize_t, Ptr{Void}),
      A, length(A), sizeof(eltype(A)), mycompare_c)

运行后， A 变成有序的数组 [-2.7, 1.3, 3.1, 4.4]。 注意， Julia 可以转换数组到 Ptr{Cdouble}， 可以计算一种类型的大小 (和 C 里的 sizeof 一致)。 有意思的是， 将 println("mycompare($a,$b)") 写到 mycompare 里可以打印出 qsort 进行的所有比较。

把 C 类型映射到 Julia¶

在 Julia 里， 正确地匹配 C 类型很重要， 不一致的类型会导致在一个系统下正确的代码在另一个系统下发生错误。

注意， 调用 C 函数时， C 头文件是不需要的: 你需要保证 Julia 类型和函数签名和头文件里的一致。

ccall( (:foo, "libfoo"), Void, (Int32, Float64), x, y)

ccall((:foo, "libfoo"), Void, (Int32, Float64),
      Base.unsafe_convert(Int32, Base.cconvert(Int32, x)),
      Base.unsafe_convert(Float64, Base.cconvert(Float64, y)))

int main(int argc, char **argv);

argv = [ "a.out", "arg1", "arg2" ]
ccall(:main, Int32, (Int32, Ptr{Ptr{Uint8}}), length(argv), argv)

in C:
struct B {
    int A[3];
};
b_a_2 = B.A[2];

in Julia:
immutable B_A
    A_1::Cint
    A_2::Cint
    A_3::Cint
end
type B
    A::B_A
end
b_a_2 = B.A.(2)

#include <immintrin.h>

__m256 dist( __m256 a, __m256 b ) {
    return _mm256_sqrt_ps(_mm256_add_ps(_mm256_mul_ps(a, a),
                                        _mm256_mul_ps(b, b)));
}

typealias m256 NTuple{8,VecElement{Float32}}

a = m256(ntuple(i->VecElement(sin(Float32(i))),8))
b = m256(ntuple(i->VecElement(cos(Float32(i))),8))

function call_dist(a::m256, b::m256)
    ccall((:dist, "libdist"), m256, (m256, m256), a, b)
end

println(call_dist(a,b))

将 C 函数映射到 Julia¶

用指针传递修改值¶

因为 C 不支持多返回值， 所以通常 C 函数会用指针来修改值。 在 ccall 里完成这些需要把值放在适当类型的数组里。当你用 Ptr 传递整个数组时， Julia 会自动传递一个 C 指针到被这个值:

width = Cint[0]
range = Cfloat[0]
ccall(:foo, Void, (Ptr{Cint}, Ptr{Cfloat}), width, range)

在返回时， width 和 range 会被 width[] and range[] 接收。

function compute_dot(DX::Vector{Float64}, DY::Vector{Float64})
  assert(length(DX) == length(DY))
  n = length(DX)
  incx = incy = 1
  product = ccall( (:ddot_, "libLAPACK"),
                  Float64,
                  (Ptr{Int32}, Ptr{Float64}, Ptr{Int32}, Ptr{Float64}, Ptr{Int32}),
                  &n, DX, &incx, DY, &incy)
  return product
end

Some Examples of C Wrappers¶

Here is a simple example of a C wrapper that returns a Ptr type:

type gsl_permutation
end

# The corresponding C signature is
#     gsl_permutation * gsl_permutation_alloc (size_t n);
function permutation_alloc(n::Integer)
    output_ptr = ccall(
        (:gsl_permutation_alloc, :libgsl), #name of C function and library
        Ptr{gsl_permutation},              #output type
        (Csize_t,),                        #tuple of input types
        n                                  #name of Julia variable to pass in
    )
    if output_ptr==C_NULL # Could not allocate memory
        throw(OutOfMemoryError())
    end
    return output_ptr
end

The GNU Scientific Library (here assumed to be accessible through :libgsl) defines an opaque pointer, gsl_permutation *, as the return type of the C function gsl_permutation_alloc(). As user code never has to look inside the gsl_permutation struct, the corresponding Julia wrapper simply needs a new type declaration, gsl_permutation, that has no internal fields and whose sole purpose is to be placed in the type parameter of a Ptr type. The return type of the ccall() is declared as Ptr{gsl_permutation}, since the memory allocated and pointed to by output_ptr is controlled by C (and not Julia).

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. (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 reference.) Furthermore, n can be any type that is convertable to a Csize_t integer; the ccall() implicitly calls Base.cconvert(Csize_t, n).

Here is a second example wrapping the corresponding destructor:

# The corresponding C signature is
#     void gsl_permutation_free (gsl_permutation * p);
function permutation_free(p::Ref{gsl_permutation})
    ccall(
        (:gsl_permutation_free, :libgsl), #name of C function and library
        Void,                             #output type
        (Ref{gsl_permutation},),          #tuple of input types
        p                                 #name of Julia variable to pass in
    )
end

Here, the input p is declared to be of type Ref{gsl_permutation}, meaning that the memory that p points to may be managed by Julia or by C. A pointer to memory allocated by C should be of type Ptr{gsl_permutation}, but it is convertable using cconvert() and therefore can be used in the same (covariant) context of the input argument to a ccall(). A pointer to memory allocated by Julia must be of type Ref{gsl_permutation}, to ensure that the memory address pointed to is valid and that Julia’s garbage collector manages the chunk of memory pointed to correctly. Therefore, the Ref{gsl_permutation} declaration allows pointers managed by C or Julia to be used.

If the C wrapper never expects the user to pass pointers to memory managed by Julia, then using p::Ptr{gsl_permutation} for the method signature of the wrapper and similarly in the ccall() is also acceptable.

Here is a third example passing Julia arrays:

# The corresponding C signature is
#    int gsl_sf_bessel_Jn_array (int nmin, int nmax, double x,
#                                double result_array[])
function sf_bessel_Jn_array(nmin::Integer, nmax::Integer, x::Real)
    if nmax<nmin throw(DomainError()) end
    result_array = Array{Cdouble}(nmax-nmin+1)
    errorcode = ccall(
        (:gsl_sf_bessel_Jn_array, :libgsl), #name of C function and library
        Cint,                               #output type
        (Cint, Cint, Cdouble, Ref{Cdouble}),#tuple of input types
        nmin, nmax, x, result_array         #names of Julia variables to pass in
    )
    if errorcode!= 0 error("GSL error code $errorcode") end
    return result_array
end

The C function wrapped returns an integer error code; the results of the actual evaluation of the Bessel J function populate the Julia array result_array. This variable can only be used with corresponding input type declaration Ref{Cdouble}, since its memory is allocated and managed by Julia, not C. The implicit call to Base.cconvert(Ref{Cdouble}, result_array) 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 be of type Ref{Cdouble} and not Ptr{Cdouble}. The memory is managed by Julia and the Ref signature alerts Julia’s garbage collector to keep managing the memory for result_array while the ccall() executes. If Ptr{Cdouble} were used instead, the ccall() may still work, but Julia’s garbage collector would not be aware that the memory declared for result_array is being used by the external C function. As a result, the code may produce a memory leak if result_array never gets freed by the garbage collector, or if the garbage collector prematurely frees result_array, the C function may end up throwing an invalid memory access exception.

垃圾回收机制的安全¶

给 ccall 传递数据时，最好避免使用 pointer() 函数。应当定义一个转换方法，将变量直接传递给 ccall 。ccall 会自动安排，使得在调用返回前，它的所有参数都不会被垃圾回收机制处理。如果 C API 要存储一个由 Julia 分配好的内存的引用，当 ccall 返回后，需要自己设置，使对象对垃圾回收机制保持可见。推荐的方法为，在一个类型为 Array{Any,1} 的全局变量中保存这些值，直到 C 接口通知它已经处理完了。

只要构造了指向 Julia 数据的指针，就必须保证原始数据直至指针使用完之前一直存在。Julia 中的许多方法，如 unsafe_ref() 和 bytestring() ，都复制数据而不是控制缓冲区，因此可以安全释放（或修改）原始数据，不会影响到 Julia 。有一个例外需要注意，由于性能的原因， pointer_to_array() 会共享（或控制）底层缓冲区。

垃圾回收并不能保证回收的顺序。例如，当 a 包含对 b 的引用，且两者都要被垃圾回收时，不能保证 b 在 a 之后被回收。这需要用其它方式来处理。

非常量函数说明¶

(name, library) 函数说明应为常量表达式。可以通过 eval ，将计算结果作为函数名：

@eval ccall(($(string("a","b")),"lib"), ...

表达式用 string 构造名字，然后将名字代入 ccall 表达式进行计算。注意 eval 仅在顶层运行，因此在表达式之内，不能使用本地变量（除非本地变量的值使用 $ 进行过内插）。 eval 通常用来作为顶层定义，例如，将包含多个相似函数的库封装在一起。

间接调用¶

ccall 的第一个参数可以是运行时求值的表达式。此时，表达式的值应为 Ptr 类型，指向要调用的原生函数的地址。这个特性用于 ccall 的第一参数包含对非常量（本地变量或函数参数）的引用时。

调用方式¶

ccall 的第二个（可选）参数指定调用方式（在返回值之前）。如果没指定，将会使用操作系统的默认 C 调用方式。其它支持的调用方式为: stdcall , cdecl , fastcall 和 thiscall 。例如 (来自 base/libc.jl)：

hn = Array(Uint8, 256)
err=ccall(:gethostname, stdcall, Int32, (Ptr{Uint8}, Uint32), hn, length(hn))

更多信息请参考 LLVM Language Reference.

访问全局变量¶

Global variables exported by native libraries can be accessed by name using the cglobal() function. The arguments to cglobal() are a symbol specification identical to that used by ccall(), and a type describing the value stored in the variable:

julia> cglobal((:errno,:libc), Int32)
Ptr{Int32} @0x00007f418d0816b8

The result is a pointer giving the address of the value. The value can be manipulated through this pointer using unsafe_load() and unsafe_store!().

通过指针读取数据¶

下列方法是“不安全”的，因为坏指针或类型声明可能会导致意外终止或损坏任意进程内存。

指定 Ptr{T} ，常使用 unsafe_ref(ptr, [index]) 方法，将类型为 T 的内容从所引用的内存复制到 Julia 对象中。 index 参数是可选的（默认为 1 ），它是从 1 开始的索引值。此函数类似于 getindex() 和 setindex!() 的行为（如 [] 语法）。

返回值是一个被初始化的新对象，它包含被引用内存内容的浅拷贝。被引用的内存可安全释放。

如果 T 是 Any 类型，被引用的内存会被认为包含对 Julia 对象 jl_value_t* 的引用，结果为这个对象的引用，且此对象不会被拷贝。需要谨慎确保对象始终对垃圾回收机制可见（指针不重要，重要的是新的引用），来确保内存不会过早释放。注意，如果内存原本不是由 Julia 申请的，新对象将永远不会被 Julia 的垃圾回收机制释放。如果 Ptr 本身就是 jl_value_t* ，可使用 unsafe_pointer_to_objref(ptr) 将其转换回 Julia 对象引用。（可通过调用 pointer_from_objref(v) 将Julia 值 v 转换为 jl_value_t* 指针 Ptr{Void} 。）

逆操作（向 Ptr{T} 写数据）可通过 unsafe_store!(ptr, value, [index]) 来实现。目前，仅支持位类型和其它无指针（ isbits ）不可变类型。

现在任何抛出异常的操作，估摸着都是还没实现完呢。来写个帖子上报 bug 吧，就会有人来解决啦。

如果所关注的指针是（位类型或不可变）的目标数据数组， pointer_to_array(ptr,dims,[own]) 函数就非常有用啦。如果想要 Julia “控制”底层缓冲区并在返回的 Array 被释放时调用 free(ptr) ，最后一个参数应该为真。如果省略 own 参数或它为假，则调用者需确保缓冲区一直存在，直至所有的读取都结束。

Ptr 的算术(比如 +) 和 C 的指针算术不同， 对 Ptr 加一个整数会将指针移动一段距离的 字节 ， 而不是元素。这样从指针运算上得到的地址不会依赖指针类型。

线程安全¶

Some C libraries execute their callbacks from a different thread, and since Julia isn’t thread-safe you’ll need to take some extra precautions. In particular, you’ll need to set up a two-layered system: the C callback should only schedule (via Julia’s event loop) the execution of your “real” callback. To do this, create a AsyncCondition object and wait on it:

cond = Base.AsyncCondition()
wait(cond)

The callback you pass to C should only execute a ccall() to :uv_async_send, passing cb.handle as the argument, taking care to avoid any allocations or other interactions with the Julia runtime.

Note that events may be coalesced, so multiple calls to uv_async_send may result in a single wakeup notification to the condition.

更多关于回调¶

For more details on how to pass callbacks to C libraries, see this blog post.

C++¶

Limited support for C++ is provided by the Cpp, Clang, and Cxx packages.