被调用的代码应该是共享库的格式。大多数 C 和 Fortran 库都已经被编译为共享库。如果自己使用 GCC (或 Clang )编译代码,需要添加 -shared
和 -fPIC
选项。Julia 调用这些库的开销与本地 C 语言相同。
调用共享库和函数时使用多元组形式: (:function, "library")
或 ("function", "library")
,其中 function
是 C 的导出函数名, library
是共享库名。共享库依据名字来解析,路径由环境变量来确定,有时需要直接指明。
多元组内有时仅有函数名(仅 :function
或 "function"
)。此时,函数名由当前进程解析。这种形式可以用来调用 C 库函数, Julia 运行时函数,及链接到 Julia 的应用中的函数。
使用 ccall
来生成库函数调用。 ccall
的参数如下:
Int32
, Int64
, Float64
,或者指向任意类型参数 T
的指针 Ptr{T}
,或者仅仅是指向无类型指针 void*
的 Ptr
下例调用标准 C 库中的 clock
:
julia> t = ccall( (:clock, "libc"), Int32, ())
2292761
julia> t
2292761
julia> typeof(ans)
Int32
clock
函数没有参数,返回 Int32
类型。输入的类型如果只有一个,常写成一元多元组,在后面跟一逗号。例如要调用 getenv
函数取得指向一个环境变量的指针,应这样调用:
julia> path = ccall( (:getenv, "libc"), Ptr{Uint8}, (Ptr{Uint8},), "SHELL")
Ptr{Uint8} @0x00007fff5fbffc45
julia> bytestring(path)
"/bin/bash"
注意,类型多元组的参数必须写成 (Ptr{Uint8},)
,而不是 (Ptr{Uint8})
。这是因为 (Ptr{Uint8})
等价于 Ptr{Uint8}
,它并不是一个包含 Ptr{Uint8}
的一元多元组:
julia> (Ptr{Uint8})
Ptr{Uint8}
julia> (Ptr{Uint8},)
(Ptr{Uint8},)
实际中要提供可复用代码时,通常要使用 Julia 的函数来封装 ccall
,设置参数,然后检查 C 或 Fortran 函数中可能出现的任何错误,将其作为异常传递给 Julia 的函数调用者。下例中, getenv
C 库函数被封装在 env.jl 里的 Julia 函数中:
function getenv(var::String)
val = ccall( (:getenv, "libc"),
Ptr{Uint8}, (Ptr{Uint8},), var)
if val == C_NULL
error("getenv: undefined variable: ", var)
end
bytestring(val)
end
上例中,如果函数调用者试图读取一个不存在的环境变量,封装将抛出异常:
julia> getenv("SHELL")
"/bin/bash"
julia> getenv("FOOBAR")
getenv: undefined variable: FOOBAR
下例稍复杂些,显示本地机器的主机名:
function gethostname()
hostname = Array(Uint8, 128)
ccall( (:gethostname, "libc"), Int32,
(Ptr{Uint8}, Uint),
hostname, length(hostname))
return bytestring(convert(Ptr{Uint8}, hostname))
end
此例先分配出一个字节数组,然后调用 C 库函数 gethostname
向数组中填充主机名,取得指向主机名缓冲区的指针,在默认其为空结尾 C 字符串的前提下,将其转换为 Julia 字符串。 C 库函数一般都用这种方式从函数调用者那儿,将申请的内存传递给被调用者,然后填充。在 Julia 中分配内存,通常都需要通过构建非初始化数组,然后将指向数据的指针传递给 C 函数。
调用 Fortran 函数时,所有的输入都必须通过引用来传递。
&
前缀说明传递的是指向标量参数的指针,而不是标量值本身。下例使用 BLAS 函数计算点积:
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
前缀 &
的意思与 C 中的不同。对引用的变量的任何更改,都是对 Julia 不可见的。 &
并不是真正的地址运算符,可以在任何语法中使用它,例如 &0
和 &f(x)
。
注意在处理过程中,C 的头文件可以放在任何地方。目前还不能将 Julia 的结构和其他非基础类型传递给 C 库。通过传递指针来生成、使用非透明结构类型的 C 函数,可以向 Julia 返回 Ptr{Void}
类型的值,这个值以 Ptr{Void}
的形式被其它 C 函数调用。可以像任何 C 程序一样,通过调用库中对应的程序,对对象进行内存分配和释放。
Julia 自动调用 convert
函数,将参数转换为指定类型。例如:
ccall( (:foo, "libfoo"), Void, (Int32, Float64),
x, y)
会按如下操作:
ccall( (:foo, "libfoo"), Void, (Int32, Float64),
convert(Int32, x), convert(Float64, y))
如果标量值与 &
一起被传递作为 Ptr{T}
类型的参数时,值首先会被转换为 T
类型。
把数组作为一个 Ptr{T}
参数传递给 C 时,它不进行转换。Julia 仅检查元素类型是否为 T
,然后传递首元素的地址。这样做可以避免不必要的复制整个数组。
因此,如果 Array
中的数据格式不对时,要使用显式转换,如 int32(a)
。
如果想把数组 不经转换 而作为一个不同类型的指针传递时,要么声明参数为 Ptr{Void}
类型,要么显式调用 convert(Ptr{T}, pointer(A))
。
基础的 C/C++ 类型和 Julia 类型对照如下。每个 C 类型也有一个对应名称的 Julia 类型,不过冠以了前缀 C 。这有助于编写简便的代码(但 C 中的 int 与 Julia 中的 Int 不同)。
与系统无关:
unsigned char | Cuchar | Uint8 |
---|---|---|
short | Cshort | Int16 |
unsigned short | Cushort | Uint16 |
int | Cint | Int32 |
unsigned int | Cuint | Uint32 |
long long | Clonglong | Int64 |
unsigned long long | Culonglong | Uint64 |
intmax_t | Cintmax_t | Int64 |
uintmax_t | Cuintmax_t | Uint64 |
float | Cfloat | Float32 |
double | Cdouble | Float64 |
ptrdiff_t | Cptrdiff_t | Int |
ssize_t | Cssize_t | Int |
size_t | Csize_t | Uint |
void | Void | |
void* | Ptr{Void} | |
char* (or char[], e.g. a string) | Ptr{Uint8} | |
char* (or char[]) | Ptr{Ptr{Uint8}} | |
struct T* (T 正确表示一个定义好的 bit 类型) | Ptr{T} (在参数列表中使用 &variable_name 调用) | |
struct T (T 正确表示一个定义好的 bit 类型) | T (在参数列表中使用 &variable_name 调用) | |
jl_value_t* (任何 Julia 类型) | Ptr{Any} |
对应于字符串参数( char*
)的 Julia 类型为 Ptr{Uint8}
,而不是 ASCIIString
。参数中有 char**
类型的 C 函数,在 Julia 中调用时应使用 Ptr{Ptr{Uint8}}
类型。例如,C 函数:
int main(int argc, char **argv);
在 Julia 中应该这样调用:
argv = [ "a.out", "arg1", "arg2" ]
ccall(:main, Int32, (Int32, Ptr{Ptr{Uint8}}), length(argv), argv)
对于 wchar_t*
参数,Julia 类型为 Ptr{Wchar_t}
,并且数据可以通过 wstring(s)
方法转换为原始的 Julia 字符串(等同于 utf16(s)
或utf32(s)
,这取决于 Cwchar_t
的宽度)。还要注意 ASCII, UTF-8, UTF-16, 和UTF-32 字符串数据在 Julia 内部是以 NUL 结尾的,所以它能够传递到 C 函数中以 NUL 为结尾的数据,而不用再做一个拷贝。
下列方法是“不安全”的,因为坏指针或类型声明可能会导致意外终止或损坏任意进程内存。
指定 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
加一个整数会将指针移动一段距离的 字节 , 而不是元素。这样从指针运算上得到的地址不会依赖指针类型。
因为 C 不支持多返回值, 所以通常 C 函数会用指针来修改值。 在 ccall
里完成这些需要把值放在适当类型的数组里。当你用 Ptr
传递整个数组时,
Julia 会自动传递一个 C 指针到被这个值:
width = Cint[0]
range = Cfloat[0]
ccall(:foo, Void, (Ptr{Cint}, Ptr{Cfloat}), width, range)
这被广泛用在了 Julia 的 LAPACK 接口上, 其中整数类型的 info
被以引用的方式传到 LAPACK, 再返回是否成功。
给 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
当全局变量导出到本地库时可以使用 cglobal
方法,通过名称进行访问。cglobal
的参数和 ccall
的指定参数是相同的符号,并且其表述了存储在变量中的值类型:
julia> cglobal((:errno,:libc), Int32)
Ptr{Int32} @0x00007f418d0816b8
该结果是一个该值的地址的指针。可以通过这个指针对这个值进行操作,但需要使用 unsafe_load
和 unsafe_store
。
可以将 Julia 函数传递给本地的函数,只要该函数有指针参数。一个典型的例子为标准 C 库 qsort
函数,描述如下:
void qsort(void *base, size_t nmemb, size_t size,
int(*compare)(const void *a, const void *b));
base
参数是一个数组长度 nmemb
的指针,每个元素大小为 size
字节。compare
是一个回调函数,带有两个元素 a
和 b
的指针,并且如果 a
在 b
之前或之后出现,则返回一个大于或者小于 0 的整数(如果允许任意顺序的话,结果为 0)。现在假设我们在 Julia 值中有一个一维数组 A
,我们想给这个数组进行排序,使用 qsort
函数(不用 Julia 的内置函数)。在我们调用 qsort
和传递参数之前,我们需要写一个比较函数,来适应任意类型 T:
function mycompare{T}(a_::Ptr{T}, b_::Ptr{T})
a = unsafe_load(a_)
b = unsafe_load(b_)
return convert(Cint, a < b ? -1 : a > b ? +1 : 0)
end
请注意,我们必须注意返回值类型:qsort
需要的是 C 语言的 int
类型变量作为返回值,所以我们必须通过调用 convert
来确保返回 Cint
。
为了能够传递这个函数给 C,我们要通过 cfunction
来得到它的地址:
const mycompare_c = cfunction(mycompare, Cint, (Ptr{Cdouble}, Ptr{Cdouble}))
cfunction
接受三个参数:Julia 函数(mycompare
),返回值类型 (Cint
),和一个参数类型的元组,在这种情况下对 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
是相同的)等等。如果你有兴趣,你可以尝试在 mycompare
插入一个 println("mycompare($a,$b)")
,这将允许你以比较的方式去查看 qsort
(并且确认它的确调用了 你传递的 Julia 函数)。
一些 C 从不同的线程中执行他们的回调函数,并且 Julia 不含有线程安全,你需要做一些额外的预防措施。特别是,你需要设置两层系统:C 的回调应该只调度(通过 Julia 的时间循环)你“真正”的回调函数的执行。你的回调需要两个输入(你很可能会忘记)并且通过 SingleAsyncWork
进行包装::
cb = Base.SingleAsyncWork(data -> my_real_callback(args))
你传递给 C 的回调应该仅仅执行 ccall
到 :uv_async_send
,传递 cb.handle
作为参数。
对于更多的如何传递回调到 C 库的细节,请参考 blog post。
当处理不同的平台库的时候,经常要针对特殊平台提供特殊函数。这时常用到变量 OS_NAME
。此外,还有一些常用的宏: @windows
, @unix
, @linux
, 及 @osx
。注意, linux 和 osx 是 unix 的不相交的子集。宏的用法类似于三元条件运算符。
简单的调用:
ccall( (@windows? :_fopen : :fopen), ...)
复杂的调用:
@linux? (
begin
some_complicated_thing(a)
end
: begin
some_different_thing(a)
end
)
链式调用(圆括号可以省略,但为了可读性,最好加上):
@windows? :a : (@osx? :b : :c)