Calling C and Fortran Code

ほとんどのコードはJuliaで記述できますが、数値計算の分野には、CやFortranで書かれた高品質で成熟したライブラリがすでに数多く存在します。こうした既存のコードを容易に利用できるよう、JuliaではCやFortranの関数を簡単かつ効率的に呼び出せます。Juliaは「ボイラープレート不要」という方針を採用しており、「グルー」コード、コード生成、コンパイルを一切行わずに、対話プロンプトからでも関数を直接呼び出せます。必要なのは、@ccallマクロを使って適切な呼び出しを記述することだけです(やや使い勝手は劣りますが、ccall構文も使えます。ccall syntax sectionを参照してください)。

呼び出すコードは共有ライブラリとして利用できる必要があります。ほとんどのCおよびFortranライブラリは、すでに共有ライブラリとしてコンパイルされた形で配布されていますが、GCC(またはClang)で自分でコンパイルする場合は、-sharedおよび-fPICオプションが必要です。JuliaのJITが生成する機械語命令は、ネイティブのC呼び出しで生成されるものと同じなので、オーバーヘッドもCコードからライブラリ関数を呼び出す場合と同じです。[1]

デフォルトでは、Fortranコンパイラはgenerate mangled namesを行います(たとえば、関数名を小文字や大文字に変換し、多くの場合は末尾にアンダースコアを付けます)。そのため、Fortran関数を呼び出すには、使用するFortranコンパイラの規則に従ってマングリングされた識別子を渡す必要があります。また、Fortran関数を呼び出す際は、すべての入力を、ヒープまたはスタック上に確保された値へのポインタとして渡さなければなりません。これは、通常ヒープ上に確保される配列やその他の可変オブジェクトだけでなく、通常スタック上に確保され、CやJuliaの呼び出し規約では一般にレジスタで渡される整数や浮動小数点数などのスカラー値にも当てはまります。

@ccallでライブラリ関数の呼び出しを生成する構文は、次のとおりです。

@ccall library.function_name(argvalue1::argtype1, ...)::returntype
@ccall function_name(argvalue1::argtype1, ...)::returntype
@ccall $function_pointer(argvalue1::argtype1, ...)::returntype

ここで、libraryは文字列定数またはグローバル変数名です(後述のNon-constant Function -Specificationsを参照)。ライブラリは名前だけでも、フルパスでも指定できます。ライブラリを省略すると、関数名は現在の実行ファイル、現在のlibc、またはlibjulia(-internal)内で解決されます。この形式は、Cライブラリ関数、Juliaランタイム内の関数、Juliaとリンクされたアプリケーション内の関数を呼び出す際に使用できます。ライブラリの省略によって、任意のライブラリ内の関数を呼び出すことはできません(dlsymにRTLD_DEFAULTを指定するような動作は行えません)。そのような動作は低速で複雑であり、すべてのプラットフォームに実装されているわけではないためです。別の方法として、@ccallを使い、Libdl.dlsymが返すような関数ポインタ$function_pointerを呼び出すこともできます。argtypeはC関数のシグネチャに対応し、argvalueは関数に渡す実際の引数値です。

Note

map C types to Julia typesの方法については、後述の説明を参照してください。

単純ながら完全な例として、次のコードは、ほとんどのUnix系システムで標準Cライブラリのclock関数を呼び出します。

julia> t = @ccall clock()::Int32
2292761

julia> typeof(t)
Int32

clockは引数を取らず、Int32を返します。getenv関数を呼び出して環境変数の値へのポインタを取得するには、次のように記述します。

julia> path = @ccall getenv("SHELL"::Cstring)::Cstring
Cstring(@0x00007fff5fbffc45)

julia> unsafe_string(path)
"/bin/bash"

実際には、特に再利用可能な機能を提供する場合、通常は@ccallの使用箇所をJulia関数でラップし、その中で引数を準備してから、CまたはFortran関数が規定する方法でエラーをチェックします。エラーが発生した場合は、通常のJulia例外として送出します。CやFortranのAPIはエラー状態の通知方法がきわめて不統一なことで知られているため、この処理は特に重要です。たとえば、Cライブラリのgetenv関数は、次のJulia関数でラップできます。これはenv.jlにある実際の定義を簡略化したものです。

function getenv(var::AbstractString)
    val = @ccall getenv(var::Cstring)::Cstring
    if val == C_NULL
        error("getenv: undefined variable: ", var)
    end
    return unsafe_string(val)
end

Cのgetenv関数はC_NULLを返すことでエラーを通知しますが、ほかの標準C関数では、-1、0、1、その他の特別な値を返すなど、さまざまな方法でエラーを通知します。このラッパーは、呼び出し元が存在しない環境変数を取得しようとした場合、問題を示す例外を送出します。

julia> getenv("SHELL")
"/bin/bash"

julia> getenv("FOOBAR")
ERROR: getenv: undefined variable: FOOBAR

次に、ローカルマシンのホスト名を取得する、少し複雑な例を示します。

function gethostname()
    hostname = Vector{UInt8}(undef, 256) # MAXHOSTNAMELEN
    err = @ccall gethostname(hostname::Ptr{UInt8}, sizeof(hostname)::Csize_t)::Int32
    Base.systemerror("gethostname", err != 0)
    hostname[end] = 0 # ensure null-termination
    return GC.@preserve hostname unsafe_string(pointer(hostname))
end

この例では、まずバイト配列を確保します。次にCライブラリのgethostname関数を呼び出し、配列にホスト名を書き込みます。最後に、ホスト名バッファへのポインタを取得し、ヌル終端のC文字列であると仮定して、そのポインタをJulia文字列に変換します。

Cライブラリでは、呼び出し元がメモリを確保し、それを呼び出し先に渡して内容を書き込ませる、というパターンがよく使われます。Juliaからこのようなメモリを確保するには、一般に未初期化の配列を作成し、そのデータへのポインタをC関数に渡します。ここでCstring型を使わないのはそのためです。未初期化の配列にはヌルバイトが含まれている可能性があります。@ccallの一部としてCstringに変換すると、ヌルバイトが含まれていないかチェックされるため、変換エラーが送出される可能性があります。

unsafe_stringでpointer(hostname)を逆参照する操作は安全ではありません。hostnameに割り当てられたメモリへアクセスする必要がありますが、そのメモリはその間にガベージコレクションで回収されている可能性があるためです。GC.@preserveマクロは、この回収と、それに伴う無効なメモリ位置へのアクセスを防ぎます。

最後に、ライブラリをパスで指定する例を示します。次の内容の共有ライブラリを作成し、

#include <stdio.h>

void say_y(int y)
{
    printf("Hello from C: got y = %d.\n", y);
}

gcc -fPIC -shared -o mylib.so mylib.cでコンパイルします。その後、ライブラリ名として(絶対)パスを指定すれば呼び出せます。

julia> @ccall "./mylib.so".say_y(5::Cint)::Cvoid
Hello from C: got y = 5.

Creating C-Compatible Julia Function Pointers

関数ポインタを引数として受け取るネイティブC関数に、Julia関数を渡すことができます。たとえば、次の形式のCプロトタイプに対応させる場合を考えます。

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

@cfunctionマクロは、Julia関数を呼び出すためのC互換の関数ポインタを生成します。@cfunctionの引数は次のとおりです。

  1. Julia関数
  2. 関数の戻り値の型
  3. 関数シグネチャに対応する入力型のタプル
Note

@ccallと同様に、戻り値の型と入力型はリテラル定数でなければなりません。

Note

現在サポートされているのは、プラットフォームのデフォルトのC呼び出し規約のみです。したがって、32ビットWindowsでWINAPIがstdcall関数を要求する呼び出しには、@cfunctionが生成したポインタを使用できません。一方、WIN64では使用できます(WIN64ではstdcallがC呼び出し規約に統合されています)。

Note

@cfunctionを通じて公開するコールバック関数では、エラーを送出しないでください。エラーを送出すると、予期せずJuliaランタイムに制御が戻り、プログラムが未定義の状態になる可能性があります。

典型的な例として、標準Cライブラリのqsort関数があります。この関数は次のように宣言されています。

void qsort(void *base, size_t nitems, size_t size,
           int (*compare)(const void*, const void*));

base引数は、各要素がsizeバイトで、長さがnitemsの配列へのポインタです。compareは、2つの要素aおよびbへのポインタを受け取るコールバック関数です。aをbより前に置く場合は負の整数、後に置く場合は正の整数を返します(どちらの順序でもよい場合は0を返します)。

ここで、Juliaの値を格納した1次元配列Aを、Julia組み込みのsort関数ではなく、qsort関数でソートするとします。qsortの呼び出しと引数の受け渡しを考える前に、比較関数を記述する必要があります。

julia> function mycompare(a, b)::Cint
           return (a < b) ? -1 : ((a > b) ? +1 : 0)
       end;

qsortは、Cのintを返す比較関数を要求するため、戻り値の型をCintと注釈します。

この関数をCに渡すには、@cfunctionマクロを使ってアドレスを取得します。

julia> mycompare_c = @cfunction(mycompare, Cint, (Ref{Cdouble}, Ref{Cdouble}));

@cfunctionには3つの引数が必要です。Julia関数(mycompare)、戻り値の型(Cint)、入力引数の型を表すリテラルタプルです。この例では、Cdouble(Float64)要素の配列をソートするための型を指定します。

最終的なqsortの呼び出しは、次のようになります。

julia> A = [1.3, -2.7, 4.4, 3.1];

julia> @ccall qsort(A::Ptr{Cdouble}, length(A)::Csize_t, sizeof(eltype(A))::Csize_t, mycompare_c::Ptr{Cvoid})::Cvoid

julia> A
4-element Vector{Float64}:
 -2.7
  1.3
  3.1
  4.4

この例が示すように、元のJulia配列Aはソートされ、[-2.7, 1.3, 3.1, 4.4]となりました。Juliaはtakes care of converting the array to a Ptr{Cdouble}や、要素型のバイト単位のサイズ計算などを行うことに注意してください。

試しにmycompareにprintln("mycompare($a, $b)")の行を挿入してみてください。qsortがどのような比較を行っているかを確認できます(そして、渡したJulia関数が実際に呼び出されていることも確かめられます)。

Mapping C Types to Julia

Cで宣言されている型とJulia側の宣言を正確に一致させることが非常に重要です。不一致があると、あるシステムでは正しく動作するコードでも、別のシステムでは失敗したり、不定の結果を生じたりする可能性があります。

C関数の呼び出し過程では、Cヘッダーファイルは一切使用されないことに注意してください。Juliaの型と呼び出しシグネチャがCヘッダーファイルの内容を正確に反映していることは、自分で保証する必要があります。[2]

Automatic Type Conversion

Juliaは、各引数を指定された型に変換するため、Base.cconvert関数の呼び出しを自動的に挿入します。たとえば、次の呼び出しは、

@ccall "libfoo".foo(x::Int32, y::Float64)::Cvoid

次のように記述した場合と同じように動作します。

c_x = Base.cconvert(Int32, x)
c_y = Base.cconvert(Float64, y)
GC.@preserve c_x c_y begin
    @ccall "libfoo".foo(
        Base.unsafe_convert(Int32, c_x)::Int32,
        Base.unsafe_convert(Float64, c_y)::Float64
    )::Cvoid
end

Base.cconvertは通常、単にconvertを呼び出しますが、Cに渡すのにより適した任意の新しいオブジェクトを返すように定義することもできます。Cコードからアクセスするメモリの確保は、すべてここで行うべきです。たとえば、文字列などのオブジェクトを格納したArrayを、ポインタの配列に変換するために使われます。

Base.unsafe_convertはPtr型への変換を処理します。この操作が安全でないとされるのは、オブジェクトをネイティブポインタに変換すると、ガベージコレクタからオブジェクトが見えなくなり、早期に解放される可能性があるためです。

Type Correspondences

まず、関連するJuliaの型の用語を確認しましょう。

構文 / キーワード例説明
mutable structBitSet「具象型」:: 型タグを含む関連データの集合で、JuliaのGCによって管理され、オブジェクトの同一性によって定義されます。インスタンスを構築するには、具象型の型パラメータが完全に定義されていなければなりません(TypeVarsは許可されません)。isconcretetypeも参照してください。
abstract typeAny, AbstractArray{T, N}, Complex{T}「スーパータイプ」:: インスタンス化できないスーパータイプ(具象型ではありません)で、型のグループを表すために使えます。isabstracttypeも参照してください。
T{A}Vector{Int}「型パラメータ」:: 型を特殊化するものです(通常、ディスパッチや格納方法の最適化に使われます)。
「TypeVar」:: 型パラメータ宣言内のTは、TypeVar(type variable、型変数の略)と呼ばれます。
primitive typeInt, Float64「プリミティブ型」:: フィールドは持たず、サイズを持つ型です。値として格納され、値によって定義されます。
structPair{Int, Int}「Struct」:: すべてのフィールドが定数として定義された型です。値によって定義され、型タグとともに格納される場合があります。
ComplexF64 (isbits)「Is-Bits」:: primitive type、またはすべてのフィールドが別のisbits型であるstruct型です。値によって定義され、型タグなしで格納されます。
struct ...; endnothing「シングルトン」:: フィールドを持たない具象型またはStructです。
(...)またはtuple(...)(1, 2, 3)「タプル」:: 無名の構造体型や定数配列に似た、不変のデータ構造です。配列または構造体として表現されます。

Bits Types

ほかの型では同じ振る舞いを定義できない、いくつかの特別な型に注意する必要があります。

  • Float32

    Cのfloat型(またはFortranのREAL*4)に正確に対応します。

  • Float64

    Cのdouble型(またはFortranのREAL*8)に正確に対応します。

  • ComplexF32

    Cのcomplex float型(またはFortranのCOMPLEX*8)に正確に対応します。

  • ComplexF64

    Cのcomplex double型(またはFortranのCOMPLEX*16)に正確に対応します。

  • Signed

    Cのsigned型注釈(またはFortranの任意のINTEGER型)に正確に対応します。SignedのサブタイプでないJulia型は、すべて符号なしと見なされます。

  • Ref{T}

    Ptr{T}と同様に振る舞いますが、JuliaのGCを通じてメモリを管理できます。

  • Array{T,N}

    配列をPtr{T}引数としてCに渡しても、再解釈キャストは行われません。Juliaでは配列の要素型がTと一致している必要があり、最初の要素のアドレスが渡されます。

    したがって、Arrayに格納されているデータの形式が適切でない場合は、trunc.(Int32, A)のような呼び出しで明示的に変換する必要があります。

    データを事前に変換せずに、配列Aを異なる型のポインタとして渡すには、引数をPtr{Cvoid}と宣言できます。たとえば、Float64配列を、バイト列を解釈せずに処理する関数に渡す場合などです。

    要素型がPtr{T}の配列をPtr{Ptr{T}}引数として渡すと、Base.cconvertは、まず各要素をBase.cconvert版に置き換えたヌル終端のコピーを作成しようとします。これにより、たとえば、Vector{String}型のargvポインタ配列を、Ptr{Ptr{Cchar}}型の引数に渡すことができます。

現在サポートしているすべてのシステムで、C/C++の基本的な値型は次のようにJuliaの型に対応付けられます。各C型には、同じ名前の先頭にCを付けたJulia型も用意されています。これは移植可能なコードを書く際に役立ちます(また、CのintはJuliaのIntとは異なる、という点を覚えておく助けにもなります)。

システムに依存しない型

Cでの名前Fortranでの名前Juliaの標準エイリアスJuliaの基本型
unsigned charCHARACTERCucharUInt8
bool(C99以降では_Bool)CucharUInt8
shortINTEGER*2, LOGICAL*2CshortInt16
unsigned shortCushortUInt16
int, BOOL(Cでの典型例)INTEGER*4, LOGICAL*4CintInt32
unsigned intCuintUInt32
long longINTEGER*8, LOGICAL*8ClonglongInt64
unsigned long longCulonglongUInt64
intmax_tCintmax_tInt64
uintmax_tCuintmax_tUInt64
floatREAL*4CfloatFloat32
doubleREAL*8CdoubleFloat64
complex floatCOMPLEX*8ComplexF32Complex{Float32}
complex doubleCOMPLEX*16ComplexF64Complex{Float64}
ptrdiff_tCptrdiff_tInt
ssize_tCssize_tInt
size_tCsize_tUInt
voidCvoid
voidと[[noreturn]]、または_NoreturnUnion{}
void*Ptr{Cvoid}(または同様にRef{Cvoid})
T*(Tは適切に定義された型を表します)Ref{T}(Tを安全に変更できるのは、Tがisbits型の場合のみです)
char*(またはchar[]、たとえば文字列)CHARACTER*Nヌル終端ならCstring、そうでなければPtr{UInt8}
char**(または*char[])Ptr{Ptr{UInt8}}
jl_value_t*(任意のJulia型)Any
jl_value_t* const*(Juliaの値への参照)Ref{Any}(変更には書き込みバリアが必要ですが、これを正しく挿入することはできないため、constです)
va_arg非対応
...(可変長引数関数の指定)T...(ccall関数を使う場合。Tは上記の型のいずれかです)
...(可変長引数関数の指定); va_arg1::T, va_arg2::S, etc.(@ccallマクロでのみサポート)

Cstring型は、基本的にはPtr{UInt8}の別名です。ただし、Julia文字列の途中にヌル文字が含まれている場合、Cstringへの変換ではエラーが送出されます(Cルーチンがヌルを終端として扱うと、その位置で文字列が通知なく切り詰められてしまうためです)。ヌル終端を前提としないCルーチンにchar*を渡す場合(たとえば文字列長を明示的に渡す場合)や、Julia文字列にヌルが含まれないことが確実でチェックを省略したい場合は、引数型にPtr{UInt8}を使えます。Cstringはccallの戻り値の型にも使えますが、その場合は当然ながら追加のチェックは行われず、呼び出しの可読性を高めることだけが目的です。

システムに依存する型

Cでの名前Juliaの標準エイリアスJuliaの基本型
charCcharInt8 (x86, x86_64), UInt8 (powerpc, arm)
longClongInt (UNIX), Int32 (Windows)
unsigned longCulongUInt (UNIX), UInt32 (Windows)
wchar_tCwchar_tInt32 (UNIX), UInt16 (Windows)
Note

Fortranを呼び出す場合、すべての入力はヒープまたはスタック上に確保された値へのポインタで渡す必要があります。そのため、上記の型対応では、型指定をさらにPtr{..}またはRef{..}でラップする必要があります。

Warning

文字列引数(char*)のJulia型は、上述のとおり、ヌル終端データが期待される場合はCstring、それ以外の場合はPtr{Cchar}またはPtr{UInt8}(この2つのポインタ型の効果は同じ)にすべきであり、Stringにしてはいけません。同様に、配列引数(T[]またはT*)のJulia型も、Vector{T}ではなくPtr{T}にすべきです。

Warning

JuliaのChar型は32ビットです。ワイド文字型(wchar_tまたはwint_t)とすべてのプラットフォームで一致するわけではありません。

Warning

戻り値の型がUnion{}であることは、関数から制御が戻らないことを意味します。これはC++11の[[noreturn]]またはC11の_Noreturnに相当します(たとえばjl_throwやlongjmp)。値は返さなくても(void)、制御は戻る関数には使用しないでください。その場合は代わりにCvoidを使います。

Note

wchar_t*引数のJulia型は、Cルーチンがヌル終端文字列を期待する場合はCwstring、それ以外の場合はPtr{Cwchar_t}にすべきです。また、JuliaのUTF-8文字列データは内部でヌル終端されているため、ヌル終端データを期待するC関数にコピーなしで渡せます(ただし、Cwstring型を使うと、文字列自体にヌル文字が含まれている場合にエラーが送出されます)。

Note

char**型の引数を取るC関数は、Julia側でPtr{Ptr{UInt8}}型を使うことで呼び出せます。たとえば、次の形式のC関数は、

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

次のJuliaコードで呼び出せます。

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

character(len=*)型の可変長文字列を受け取るFortran関数では、文字列長は隠し引数として渡されます。これらの引数の型と引数リスト内の位置はコンパイラに依存しますが、通常はCsize_t型がデフォルトで使われ、隠し引数は引数リストの末尾に追加されます。この動作が固定されているコンパイラ(GNU)もあれば、文字引数の直後に隠し引数を置くことをオプションで許可するコンパイラ(Intel、PGI)もあります。たとえば、次の形式のFortranサブルーチンは、

subroutine test(str1, str2)
character(len=*) :: str1,str2

長さを末尾に追加した次のJuliaコードで呼び出せます。

str1 = "foo"
str2 = "bar"
ccall(:test, Cvoid, (Ptr{UInt8}, Ptr{UInt8}, Csize_t, Csize_t),
                    str1, str2, sizeof(str1), sizeof(str2))
Warning

Fortranコンパイラは、ポインタ、形状引継ぎ配列(:)、大きさ引継ぎ配列(*)についても、ほかの隠し引数を追加する可能性があります。この動作を避けるには、ISO_C_BINDINGを使用し、サブルーチンの定義にbind(c)を含めます。相互運用するコードでは、この方法を強く推奨します。この場合、隠し引数はなくなりますが、一部の言語機能が制限されます(たとえば、文字列の受け渡しにはcharacter(len=1)のみが許可されます)。

Note

Cvoidを返すと宣言されたC関数は、Juliaではnothingという値を返します。

Struct Type Correspondences

CのstructやFortran90のTYPE(または一部のF77派生版のSTRUCTURE / RECORD)などの複合型は、同じフィールドレイアウトのstruct定義を作成することで、Julia側に対応する型を用意できます。

再帰的に使用される場合、isbits型はインラインで格納されます。それ以外の型は、データへのポインタとして格納されます。Cで別の構造体の内部に値として格納される構造体を再現する際は、フィールドを手作業でコピーしてはなりません。それでは正しいフィールドのアラインメントを保てないためです。代わりに、isbitsな構造体型を宣言して使用してください。無名の構造体をJuliaに変換することはできません。

Juliaは、パックされた構造体と共用体の宣言をサポートしていません。

どのフィールドのサイズが最大になるか(パディングを含む場合もあります)をあらかじめ把握しているなら、unionを近似的に表現できます。フィールドをJuliaに変換する際、Julia側のフィールドはその型だけで宣言してください。

パラメータの配列はNTupleで表現できます。たとえば、C表記で次のように書かれる構造体は、

struct B {
    int A[3];
};

b_a_2 = B.A[2];

Juliaでは次のように書けます。

struct B
    A::NTuple{3, Cint}
end

b_a_2 = B.A[3]  # note the difference in indexing (1-based in Julia, 0-based in C)

サイズが不明な配列([]または[0]で指定する、C99準拠の可変長構造体)は直接サポートされていません。多くの場合、バイトオフセットを直接扱うのが最善の方法です。たとえば、Cライブラリが独自の文字列型を宣言し、そのポインタを返す場合を考えます。

struct String {
    int strlen;
    char data[];
};

Juliaでは、各部分に個別にアクセスして、その文字列のコピーを作成できます。

str = from_c::Ptr{Cvoid}
len = unsafe_load(Ptr{Cint}(str))
unsafe_string(str + Core.sizeof(Cint), len)

Type Parameters

@ccallと@cfunctionの型引数は、それらを使用するメソッドが定義されるときに静的に評価されます。そのため、変数ではなくリテラルタプルの形式で指定する必要があり、ローカル変数を参照することもできません。

奇妙な制約に聞こえるかもしれませんが、CはJuliaのような動的言語ではないため、関数が受け取れる引数型は、静的に判明している固定のシグネチャに限られることを思い出してください。

ただし、対象のC ABIを算出するには型のレイアウトが静的に判明している必要がある一方で、関数の静的パラメータもこの静的環境の一部と見なされます。型のレイアウトに影響しない限り、呼び出しシグネチャの型パラメータとして関数の静的パラメータを使えます。たとえば、Ptrは常にワードサイズのプリミティブ型なので、f(x::T) where {T} = @ccall valid(x::Ptr{T})::Ptr{T}は有効です。一方、Tの型レイアウトは静的には判明しないため、g(x::T) where {T} = @ccall notvalid(x::T)::Tは無効です。

SIMD Values

C/C++ルーチンの引数や戻り値がネイティブのSIMD型である場合、対応するJulia型は、そのSIMD型に自然に対応付けられるVecElementの同種タプルです。具体的には、次の条件を満たす必要があります。

  • タプルのサイズと要素はSIMD型と同じでなければなりません。たとえば、x86の__m128を表すタプルは、サイズが16バイトで、要素がFloat32でなければなりません。
  • タプルの要素型はVecElement{T}のインスタンスでなければならず、TはInt8やFloat64のように、バイト数が2の累乗(1、2、4、8、16など)であるプリミティブ型でなければなりません。

例として、AVX組み込み関数を使用する次のCルーチンを考えます。

#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)));
}

次のJuliaコードは、ccallを使ってdistを呼び出します。

const 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 "libdist".dist(a::m256, b::m256)::m256
end

println(call_dist(a,b))

ホストマシンには必要なSIMDレジスタがなければなりません。たとえば、上のコードはAVX非対応のホストでは動作しません。

Memory Ownership

malloc/free

このようなオブジェクトのメモリ確保と解放は、通常のCプログラムと同様に、使用しているライブラリの適切なクリーンアップルーチンを呼び出して処理する必要があります。Cライブラリから受け取ったオブジェクトを、JuliaのLibc.freeで解放しようとしてはいけません。誤ったライブラリ経由でfree関数が呼び出され、プロセスが異常終了する可能性があります。逆に、Juliaで確保したオブジェクトを外部ライブラリに渡して解放させることも、同様に無効です。

When to use T, Ptr{T} and Ref{T}

外部Cルーチンの呼び出しをラップするJuliaコードでは、通常の(ポインタではない)データは値渡しされるため、@ccall内でT型として宣言すべきです。ポインタを受け取るCコードでは、入力引数の型には一般にRef{T}を使うべきです。これにより、Base.cconvertの暗黙的な呼び出しを通じて、JuliaまたはCのどちらが管理するメモリへのポインタも使えるようになります。対照的に、呼び出したC関数が返すポインタは、指し先のメモリがCだけによって管理されることを反映し、出力型をPtr{T}と宣言すべきです。C構造体に含まれるポインタは、その内部構造を再現する対応するJulia構造体型の中で、Ptr{T}型のフィールドとして表現すべきです。

外部Fortranルーチンの呼び出しをラップするJuliaコードでは、Fortranがすべての変数をメモリ位置へのポインタとして渡すため、すべての入力引数をRef{T}型として宣言すべきです。戻り値の型は、Fortranサブルーチンの場合はCvoid、T型を返すFortran関数の場合はTにすべきです。

Mapping C Functions to Julia

@ccall / @cfunction argument translation guide

Cの引数リストをJuliaに変換する際の規則は次のとおりです。

  • T。ここでTは、プリミティブ型char、int、long、short、float、double、complex、enum、またはそれらに対応するtypedefのいずれかです。

    • T。ここでTは、上の表に従う、対応するJuliaのビット型です。
    • Tがenumの場合、引数型はCintまたはCuintに相当する型にすべきです。
    • 引数値はコピーされます(値渡し)。
  • struct T(構造体へのtypedefを含む)

    • T。ここでTはJuliaの具象型です。
    • 引数値はコピーされます(値渡し)。
  • vector T(または__attribute__ vector_size、あるいは__m128のようなtypedef)

    • NTuple{N, VecElement{T}}。ここでTは適切なサイズのJuliaのプリミティブ型で、Nはベクトル内の要素数(vector_size / sizeof Tに等しい)です。
  • void*

    • このパラメータの用途によります。まず意図するポインタ型に変換し、次にこのリストのほかの規則を使って対応するJulia型を決定します。
    • 本当に型が不明なポインタにすぎない場合は、引数をPtr{Cvoid}と宣言できます。
  • jl_value_t*

    • Any
    • 引数値は有効なJuliaオブジェクトでなければなりません。
  • jl_value_t* const*

    • Ref{Any}
    • 引数リストは有効なJuliaオブジェクト(またはC_NULL)でなければなりません。
    • オブジェクトがGCから保護されるようにユーザーが別途手配できる場合を除き、出力パラメータには使えません。
  • T*

    • Ref{T}。ここでTはTに対応するJulia型です。
    • 引数値がinlinealloc型(isbitsを含む)の場合はコピーされます。それ以外の場合、値は有効なJuliaオブジェクトでなければなりません。
  • T (*)(...)(たとえば関数へのポインタ)

    • Ptr{Cvoid}(このポインタを作成するには、@cfunctionを明示的に使う必要がある場合があります)
  • ...(たとえば可変長引数)

    • [ccallの場合]: T...。ここでTは、残りのすべての引数に共通する単一のJulia型です。
    • [@ccallの場合]: ; va_arg1::T, va_arg2::S, etc。ここでTとSはJulia型です(つまり、通常の引数と可変長引数を;で区切ります)。
    • 現在、@cfunctionではサポートされていません。
  • va_arg

    • ccallでも@cfunctionでもサポートされていません。

@ccall / @cfunction return type translation guide

Cの戻り値の型をJuliaに変換する際の規則は次のとおりです。

  • void

    • Cvoid(シングルトンインスタンスnothing::Cvoidを返します)
  • T。ここでTは、プリミティブ型char、int、long、short、float、double、complex、enum、またはそれらに対応するtypedefのいずれかです。

    • Cの引数リストの場合と同じです。
    • 引数値はコピーされます(値として返されます)。
  • struct T(構造体へのtypedefを含む)

    • Cの引数リストの場合と同じです。
    • 引数値はコピーされます(値として返されます)。
  • vector T

    • Cの引数リストの場合と同じです。
  • void*

    • このパラメータの用途によります。まず意図するポインタ型に変換し、次にこのリストのほかの規則を使って対応するJulia型を決定します。
    • 本当に型が不明なポインタにすぎない場合は、引数をPtr{Cvoid}と宣言できます。
  • jl_value_t*

    • Any
    • 引数値は有効なJuliaオブジェクトでなければなりません。
  • jl_value_t**

    • Ptr{Any}(Ref{Any}は戻り値の型として無効です)
  • T*

    • メモリがすでにJuliaによって所有されているか、isbits型であり、かつヌルでないことがわかっている場合:

      • Ref{T}。ここでTはTに対応するJulia型です。
      • 戻り値の型としてRef{Any}は無効です。Any(jl_value_t*に対応)またはPtr{Any}(jl_value_t**に対応)にすべきです。
      • Tがisbits型の場合、C側でRef{T}を通じて返されたメモリを変更してはいけません。
    • メモリがCによって所有されている場合:

      • Ptr{T}。ここでTはTに対応するJulia型です。
  • T (*)(...)(たとえば関数へのポインタ)

    • Ptr{Cvoid}。これをJuliaから直接呼び出すには、@ccallの最初の引数として渡す必要があります。Indirect Callsを参照してください。

Passing Pointers for Modifying Inputs

Cは複数の戻り値をサポートしていないため、C関数はしばしば、変更対象のデータへのポインタを受け取ります。@ccall内でこれを行うには、まず値を適切な型のRef{T}に格納する必要があります。このRefオブジェクトを引数として渡すと、Juliaは格納されたデータへのCポインタを自動的に渡します。

width = Ref{Cint}(0)
range = Ref{Cfloat}(0)
@ccall foo(width::Ref{Cint}, range::Ref{Cfloat})::Cvoid

呼び出しから戻った後、widthとrangeの内容は、width[]とrange[]で取得できます(fooによって変更されていれば、その変更後の値が得られます)。つまり、これらは0次元配列のように振る舞います。

C Wrapper Examples

まず、Ptr型を返すCラッパーの簡単な例から始めましょう。

mutable struct gsl_permutation
end

# The corresponding C signature is
#     gsl_permutation * gsl_permutation_alloc (size_t n);
function permutation_alloc(n::Integer)
    output_ptr = @ccall "libgsl".gsl_permutation_alloc(n::Csize_t)::Ptr{gsl_permutation}
    if output_ptr == C_NULL # Could not allocate memory
        throw(OutOfMemoryError())
    end
    return output_ptr
end

GNU Scientific Library(ここでは:libgslを通じてアクセスできると仮定します)は、C関数gsl_permutation_allocの戻り値の型として、不透明なポインタgsl_permutation *を定義しています。ユーザーコードがgsl_permutation構造体の内部を見る必要はないため、対応するJuliaラッパーでは、新しい型gsl_permutationを宣言するだけで十分です。この型は内部フィールドを持たず、Ptr型の型パラメータに使うことだけを目的とします。output_ptrが指す確保済みメモリはCによって管理されるため、ccallの戻り値の型はPtr{gsl_permutation}と宣言します。

入力nは値渡しされるため、関数の入力シグネチャは単に::Csize_tと宣言し、RefやPtrは必要ありません。(ラッパーが代わりにFortran関数を呼び出す場合、Fortran変数はポインタで渡されるため、対応する関数の入力シグネチャは::Ref{Csize_t}になります。)また、nは、Csize_t整数に変換できる任意の型でかまいません。ccallが暗黙的にBase.cconvert(Csize_t, n)を呼び出します。

2つ目の例として、対応するデストラクタをラップします。

# The corresponding C signature is
#     void gsl_permutation_free (gsl_permutation * p);
function permutation_free(p::Ptr{gsl_permutation})
    @ccall "libgsl".gsl_permutation_free(p::Ptr{gsl_permutation})::Cvoid
end

3つ目の例では、Juliaの配列を渡します。

# 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 = Vector{Cdouble}(undef, nmax - nmin + 1)
    errorcode = @ccall "libgsl".gsl_sf_bessel_Jn_array(
                    nmin::Cint, nmax::Cint, x::Cdouble, result_array::Ref{Cdouble})::Cint
    if errorcode != 0
        error("GSL error code $errorcode")
    end
    return result_array
end

ラップされたC関数は整数のエラーコードを返し、ベッセルJ関数の実際の計算結果はJulia配列result_arrayに書き込まれます。この変数のメモリはJuliaによって確保・管理されるため、Ref{Cdouble}として宣言します。Base.cconvert(Ref{Cdouble}, result_array)の暗黙的な呼び出しが、Julia配列のデータ構造を指すJuliaのポインタを、Cが理解できる形式に変換します。

Fortran Wrapper Example

次の例では、ccallを使って一般的なFortranライブラリ(libBLAS)の関数を呼び出し、内積を計算します。JuliaからFortranへの対応付けが必要なため、引数の対応付けが前の例とは少し異なることに注意してください。すべての引数型にRefまたはPtrを指定します。このマングリング規約は、使用するFortranコンパイラやオペレーティングシステムに固有で、文書化されていない可能性があります。ただし、各型をRef(または同等であればPtr)でラップすることは、Fortranコンパイラの実装でよく要求されます。

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

Garbage Collection Safety

@ccallにデータを渡す際は、pointer関数の使用を避けるのが最善です。代わりにBase.cconvertメソッドを定義し、変数を@ccallに直接渡してください。@ccallは、呼び出しから戻るまで、そのすべての引数がガベージコレクションで回収されないよう自動的に保護します。C APIがJuliaで確保されたメモリへの参照を保存する場合、@ccallから戻った後も、そのオブジェクトがガベージコレクタから見える状態に保つ必要があります。推奨される方法は、Vector{Ref}型のグローバル変数を作成し、Cライブラリが使用を終えたと通知するまで、これらの値を保持することです。

Juliaのデータへのポインタを作成した場合は常に、そのポインタを使い終えるまで元のデータが存在し続けることを保証しなければなりません。unsafe_loadやStringなど、Juliaの多くのメソッドは、バッファの所有権を取得するのではなくデータをコピーするため、元のデータを解放(または変更)してもJuliaに影響はありません。主な例外はunsafe_wrapで、性能上の理由から、基になるバッファを共有します(または、その所有権を取得するよう指定できます)。

ガベージコレクタは、ファイナライズの順序を保証しません。つまり、aがbへの参照を含み、aとbの両方がガベージコレクションの対象になっている場合、bがaより後にファイナライズされる保証はありません。aを正しくファイナライズするためにbが有効である必要があるなら、別の方法で対処しなければなりません。

Non-constant Function Specifications

必要なライブラリの正確な名前やパスが事前にはわからず、実行時に計算しなければならない場合があります。そのような場合に対応するため、ライブラリ部分の指定にはLibdl.LazyLibraryのような値を使えます。ランタイムは、ccallで最初に使用されたときに、そのオブジェクトに対してLibdl.dlopenを呼び出します。

Using LazyLibrary for Lazy Loading

Libdl.LazyLibraryは、最初に使用するまでライブラリのロードを遅延させる、スレッドセーフな仕組みを提供します。現代のJuliaコードでは、ライブラリの初期化にこの方法を推奨します。

LazyLibraryは、ccall()、@ccall、dlopen()、dlsym()、dlpath()、またはcglobal()で最初に使われたとき、自身とその依存ライブラリを自動的に開くライブラリを表します。ライブラリはスレッドセーフな方法で一度だけロードされ、以降の呼び出しではロード済みのライブラリハンドルが再利用されます。

Basic Usage

using Libdl

# Define a LazyLibrary as a const for optimal performance
const libz = LazyLibrary("libz")

# Use directly in @ccall - library loads automatically on first call
@ccall libz.deflate(strm::Ptr{Cvoid}, flush::Cint)::Cint

# Also works with ccall
ccall((:inflate, libz), Cint, (Ptr{Cvoid}, Cint), strm, flush)

Platform-Specific Libraries

複数のプラットフォームで動作する必要があるコードでは、次のようにします。

const mylib = LazyLibrary(
    if Sys.iswindows()
        "mylib.dll"
    elseif Sys.isapple()
        "libmylib.dylib"
    else
        "libmylib.so"
    end
)

Libraries with Dependencies

ライブラリがほかのライブラリに依存する場合は、正しい順序でロードされるよう依存関係を指定します。

const libfoo = LazyLibrary("libfoo")
const libbar = LazyLibrary("libbar"; dependencies=[libfoo])

# When libbar is first used, libfoo is loaded first automatically
@ccall libbar.bar_function(x::Cint)::Cint

Lazy Path Construction

パスが実行時に決まるライブラリには、LazyLibraryPathを使います。

# Path is constructed when library is first accessed
const mylib = LazyLibrary(LazyLibraryPath(artifact_dir, "lib", "libmylib.so"))

Initialization Callbacks

ロード後にライブラリの初期化が必要な場合は、次のようにします。

const mylib = LazyLibrary("libmylib";
    on_load_callback = () -> @ccall mylib.initialize()::Cvoid
)
Warning

on_load_callbackの処理は最小限にし、どのタスクに対してもwait()を呼び出してはいけません。これは、ライブラリをロードするスレッドによって一度だけ呼び出されます。

Conversion from __init__() Pattern

LazyLibraryより前は、ライブラリのパスを__init__()関数内で計算することがよくありました。このパターンはLazyLibraryに置き換えることで、性能とスレッド安全性を改善できます。

__init__()を使う従来のパターン:

# Old: Library path computed in __init__()
libmylib_path = ""

function __init__(
    # Loads library on startup, whether it is used or not
    global libmylib_path = find_library(["libmylib"])
end

function myfunc(x)
    ccall((:cfunc, libmylib_path), Cint, (Cint,), x)
end

LazyLibraryを使う新しいパターン:

# New: Library as const, no __init__() needed
const libmylib = LazyLibrary("libmylib")

function myfunc(x)
    # Library loads automatically just before calling `cfunc`
    @ccall libmylib.cfunc(x::Cint)::Cint
end

詳細は、Libdl.LazyLibraryのドキュメントを参照してください。

Overloading dlopen for Custom Types

ランタイムは、@ccallが実行されるとdlsym(:function, dlopen(library)::Ptr{Cvoid})を呼び出します。Libdl.dlopen関数をカスタム型に対してオーバーロードし、別の動作を提供することもできます。ただし、ライブラリの場所とハンドルは一度決まると変わらないと仮定されるため、呼び出し結果がキャッシュされ、再利用されることがあります。したがって、dlopen式の実行回数は規定されておらず、呼び出すたびに異なる値を返すと、動作は未規定(ただし有効)になります。

Computed Function Names

さらに柔軟性が必要な場合は、次のようにevalを介して段階的に評価することで、計算した値を関数名として使えます。

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

この式はstringを使って名前を構築し、その名前を新しい@ccall式に埋め込んでから評価します。evalはトップレベルでのみ動作するため、この式の中ではローカル変数を利用できないことに注意してください($で値を埋め込んだ場合を除きます)。このため、evalは通常、多数の似た関数を含むライブラリをラップする場合など、トップレベルの定義を作成するときにのみ使われます。

Indirect Calls

@ccallの最初の引数には、使用するたびに実行時に評価される式を指定することもできます。この場合、式の評価結果はPtrでなければならず、これが呼び出すネイティブ関数のアドレスとして使われます。この動作は、@ccallの最初の引数に$を付けた場合、およびccallの最初の引数が()における単純な定数リテラルまたは式ではない場合に適用されます。引数には任意の式を使うことができ、ローカル変数や引数を参照できるほか、毎回異なる値を返すこともできます。

たとえば、cglobalに似たマクロを実装し、dlsymで関数を検索して、そのポインタを共有参照にキャッシュすることが考えられます(この参照は、プリコンパイル結果の保存時に自動的にC_NULLにリセットされます)。例を示します。

macro dlsym(lib, func)
    z = Ref(C_NULL)
    quote
        local zlocal = $z[]
        if zlocal == C_NULL
            zlocal = dlsym($(esc(lib))::Ptr{Cvoid}, $(esc(func)))::Ptr{Cvoid}
            $z[] = zlocal
        end
        zlocal
    end
end

const mylibvar = LazyLibrary("mylib")
@ccall $(@dlsym(dlopen(mylibvar), "myfunc"))()::Cvoid

Closure cfunctions

@cfunctionの最初の引数には$を付けることができます。その場合、戻り値は、その引数をキャプチャするstruct CFunctionになります。この戻り値のオブジェクトは、使用がすべて終わるまで生存するよう保証しなければなりません。この参照が失われたときとatexit時に、finalizerを通じてcfunctionポインタの内容とコードが消去されます。Cにはこの機能がないため通常は必要ありませんが、クロージャ環境用の独立したパラメータを提供しない、設計の不十分なAPIを扱う際に役立つことがあります。

function qsort(a::Vector{T}, cmp) where T
    isbits(T) || throw(ArgumentError("this method can only qsort isbits arrays"))
    callback = @cfunction $cmp Cint (Ref{T}, Ref{T})
    # Here, `callback` isa Base.CFunction, which will be converted to Ptr{Cvoid}
    # (and protected against finalization) by the ccall
    @ccall qsort(a::Ptr{T}, length(a)::Csize_t, Base.elsize(a)::Csize_t, callback::Ptr{Cvoid})
    # We could instead use:
    #    GC.@preserve callback begin
    #        use(Base.unsafe_convert(Ptr{Cvoid}, callback))
    #    end
    # if we needed to use it outside of a `ccall`
    return a
end
Note

クロージャ形式の@cfunctionはLLVMのトランポリンに依存しており、すべてのプラットフォームで利用できるわけではありません(たとえばARMやPowerPCでは利用できません)。

Closing a Library

ライブラリを再ロードできるように、いったん閉じる(アンロードする)ことが役立つ場合があります。たとえば、Juliaから使うCコードを開発する際、コンパイルし、JuliaからCコードを呼び出した後、ライブラリを閉じ、編集・再コンパイルしてから変更内容をロードしたいことがあります。Juliaを再起動するか、Libdl関数群を使って、次のようにライブラリを明示的に管理できます。

lib = Libdl.dlopen("./my_lib.so") # Open the library explicitly.
sym = Libdl.dlsym(lib, :my_fcn)   # Get a symbol for the function to call.
@ccall $sym(...) # Use the pointer `sym` instead of the library.symbol tuple.
Libdl.dlclose(lib) # Close the library explicitly.

@ccallに入力(たとえば@ccall "./my_lib.so".my_fcn(...)::Cvoid)を指定する場合、ライブラリは暗黙的に開かれ、明示的には閉じられないことに注意してください。

Variadic function calls

可変長引数を取るC関数を呼び出すには、引数リスト内でsemicolonを使い、必須引数と可変長引数を区切ります。printf関数を使う例を次に示します。

julia> @ccall printf("%s = %d\n"::Cstring ; "foo"::Cstring, foo::Cint)::Cint
foo = 3
8

ccall interface

@ccallには、別のインターフェースもあります。使い勝手はやや劣りますが、calling conventionを指定できます。

ccallの引数は次のとおりです。

  1. (:function, "library")のペア(最も一般的)、

    または

    :functionの名前シンボル、もしくは"function"の名前文字列(現在のプロセスまたはlibc内のシンボルの場合)、

    または

    関数ポインタ(たとえばdlsymから取得したもの)。

  2. 関数の戻り値の型

  3. 関数シグネチャに対応する入力型のタプル。よくある間違いは、引数型が1つだけのタプルには末尾のカンマが必要であることを忘れることです。

  4. 関数に渡す実際の引数値(引数がある場合)。それぞれを個別のパラメータとして指定します。

Note

(:function, "library")のペアと入力型リストは、構文上のタプルでなければなりません(つまり、変数やTuple型の値にはできません)。

rettypeと引数型の値は、実行時ではなく、それを含むメソッドが定義されるときに評価されます。

関数名による構文とポインタによる構文

ccallの最初の引数の構文によって、名前で呼び出すか、ポインタで呼び出すかが決まります。

  • 名前による呼び出し(タプルリテラル構文):
  • 関数名とライブラリ名には、どちらもクォートされたSymbol、String、変数名(GlobalRef)、または変数名で終わるドット式を使えます。
  • 名前のみ:(:function_name,)または"function_name"。デフォルトのライブラリ検索を使います。
  • ライブラリ付きの名前:(:function_name, "library")。関数とライブラリの両方を指定します。
  • シンボル、文字列、タプルのリテラル定数(それらの定数に評価される式ではなく、実際のリテラル)は、自動的にタプル形式へ正規化されます。
  • ポインタによる呼び出し(タプル以外の構文):
  • 上述のリテラルタプル式に該当しないものは、実行時に関数ポインタへ評価される式と見なされます。
  • 関数ポインタ変数:fptr。ここでfptrは実行時のポインタ値です。
  • 関数ポインタの計算:dlsym(:something)。結果は実行時に毎回計算されます(通常は何らかのキャッシュ処理も併用します)。
  • ライブラリ名の式:
  • 変数として指定したライブラリ名は、Symbol、String、またはその他の任意の値に解決できます。ランタイムは、その値に対して規定されていない回数だけLibdl.dlopen(name)を呼び出し、結果をキャッシュします。束縛の値が変わったり未定義になったりしても、結果は無効化されません。過去または未来のいずれかのワールドでその束縛に何らかの値が存在する限り、その値が使われる可能性があります。
  • A.B().cのようなドット式は、最後のcに至るまで、メソッド定義時に実行されます。最初の部分はModuleに、2番目の部分はクォートされたシンボルに解決されなければなりません。そのグローバル変数の値は、実行時にccallが最初に実行されるときに解決されます。

マクロ形式と関数形式の対応を次の表に示します。

@ccallccall
@ccall clock()::Int32ccall(:clock, Int32, ())
@ccall f(a::Cint)::Cintccall(:f, Cint, (Cint,), a)
@ccall "mylib".f(a::Cint, b::Cdouble)::Cvoidccall((:f, "mylib"), Cvoid, (Cint, Cdouble), a, b)
@ccall $fptr.f()::Cvoidccall(fptr, f, Cvoid, ())
@ccall printf("%s = %d\n"::Cstring ; "foo"::Cstring, foo::Cint)::Cint<unavailable>
@ccall printf("%s = %s\n"::Cstring ; "2 + 2"::Cstring, "5"::Cstring)::Cintccall(:printf, Cint, (Cstring, Cstring...), "%s = %s\n", "2 + 2", "5")
<unavailable>ccall(:gethostname, stdcall, Int32, (Ptr{UInt8}, UInt32), hn, length(hn))

Calling Convention

ccallの2番目の引数(戻り値の型の直前)には、オプションで呼び出し規約の指定子を置くことができます(@ccallマクロは現在、呼び出し規約の指定をサポートしていません)。指定子がない場合は、プラットフォームのデフォルトのC呼び出し規約が使われます。ほかにサポートされている規約は、stdcall、cdecl、fastcall、thiscall(64ビットWindowsでは何もしません)です。たとえば、base/libc.jlの例では、前述と同じgethostnameのccallを、Windows向けの正しいシグネチャで呼び出しています。

hn = Vector{UInt8}(undef, 256)
err = ccall(:gethostname, stdcall, Int32, (Ptr{UInt8}, UInt32), hn, length(hn))

詳細はLLVM Language Referenceを参照してください。

さらに、LLVM組み込み関数の呼び出しを直接挿入できる、特別な呼び出し規約llvmcallもあります。これは、GPGPUのような特殊なプラットフォームを対象にする場合に特に役立ちます。たとえばCUDAでは、スレッドのインデックスを読み取る必要があります。

ccall("llvm.nvvm.read.ptx.sreg.tid.x", llvmcall, Int32, ())

ほかのccallと同様に、引数シグネチャを正確に指定することが不可欠です。また、Core.Intrinsicsが公開する同等のJulia関数とは異なり、その組み込み関数が現在のターゲットで意味を持ち、正しく動作することを保証する互換性レイヤーはないことに注意してください。

Accessing Global Variables

ネイティブライブラリがエクスポートするグローバル変数には、cglobal関数を使い、名前でアクセスできます。cglobalの引数は、ccallで使うものと同じシンボル指定と、その変数に格納される値を表す型です。

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

結果は、値のアドレスを示すポインタです。このポインタを通じて、unsafe_loadとunsafe_store!を使って値を操作できます。

Note

このerrnoシンボルは、システムのコンパイラの実装詳細に属するため、"libc"という名前のライブラリでは見つからない場合があります。通常、標準ライブラリのシンボルには名前だけでアクセスし、正しいライブラリの選択はコンパイラに任せるべきです。ただし、この例のerrnoシンボルは、ほとんどのコンパイラで特別に扱われるため、ここで得られる値は期待する値や必要な値ではない可能性があります。マルチスレッド対応のシステムで同等のCコードをコンパイルすると、通常は実際には別の関数が(マクロプリプロセッサによる置き換えを通じて)呼び出され、ここで表示される従来の値とは異なる結果になることがあります。

Accessing Data through a Pointer

以下のメソッドは、不正なポインタや型宣言によってJuliaが突然終了する可能性があるため、「unsafe」とされています。

Ptr{T}が与えられた場合、通常はunsafe_load(ptr, [index])を使い、参照先メモリにあるT型の内容をJuliaオブジェクトにコピーできます。インデックス引数は省略可能で(デフォルトは1)、Juliaの慣例に従う1始まりのインデックスです。この関数は、getindexやsetindex!(たとえば[]というアクセス構文)の振る舞いに意図的に似せてあります。

戻り値は、参照先メモリの内容のコピーで初期化された、新しいオブジェクトになります。参照先メモリは安全に解放できます。

TがAnyの場合、メモリにはJuliaオブジェクトへの参照(jl_value_t*)が格納されていると見なされます。結果はそのオブジェクトへの参照となり、オブジェクト自体はコピーされません。この場合、メモリが早期に解放されないよう、オブジェクトが常にガベージコレクタから見える状態だったことを確認する必要があります(ポインタはそのための参照には数えられませんが、新しく得られた参照は数えられます)。なお、そのオブジェクトが元々Juliaによって確保されたものでない場合、新しいオブジェクトがJuliaのガベージコレクタによってファイナライズされることはありません。Ptr自体が実際にはjl_value_t*である場合、unsafe_pointer_to_objref(ptr)でJuliaオブジェクトへの参照に戻せます。(Juliaの値vは、pointer_from_objref(v)を呼び出すことで、Ptr{Cvoid}のようにjl_value_t*ポインタに変換できます。)

逆の操作(Ptr{T}へのデータの書き込み)は、unsafe_store!(ptr, value, [index])で行えます。現在、この操作がサポートされるのは、プリミティブ型、またはポインタを含まない(isbits)その他の不変な構造体型のみです。

エラーを送出する操作は、現時点では未実装である可能性が高いため、対応できるようバグとして報告してください。

対象のポインタがプレーンデータ(プリミティブ型または不変な構造体)の配列を指している場合、unsafe_wrap(Array, ptr,dims, own = false)関数のほうが便利かもしれません。Juliaに基になるバッファの「所有権を取得」させ、返されたArrayオブジェクトのファイナライズ時にfree(ptr)を呼び出させる場合は、最後のパラメータをtrueにします。ownパラメータを省略するかfalseにした場合、呼び出し元はすべてのアクセスが終わるまでバッファが存在し続けることを保証しなければなりません。

JuliaのPtr型に対する算術演算(たとえば+を使う演算)は、Cのポインタ演算とは異なる動作をします。Juliaでは、Ptrに整数を加えると、常に要素数ではなくバイト数だけポインタが移動します。このため、ポインタ演算で得られるアドレス値は、ポインタの要素型に依存しません。

Thread-safety

一部のCライブラリは別のスレッドからコールバックを実行します。Juliaはスレッドセーフではないため、追加の注意が必要です。具体的には、2層の仕組みを用意し、Cのコールバックでは「本来の」コールバックの実行を、Juliaのイベントループを介してスケジュールするだけにする必要があります。そのためには、AsyncConditionオブジェクトを作成し、それに対してwaitを行います。

cond = Base.AsyncCondition()
wait(cond)

Cに渡すコールバックでは、cond.handleを引数として、ccallで:uv_async_sendを呼び出すことだけを行ってください。メモリ確保や、Juliaランタイムとのその他のやり取りを一切行わないよう注意が必要です。

イベントはまとめられることがあるため、uv_async_sendを複数回呼び出しても、conditionへの起床通知は1回だけになる可能性があることに注意してください。

More About Callbacks

Cライブラリにコールバックを渡す方法の詳細は、こちらのblog postを参照してください。

C++

C++バインディングを作成するツールについては、CxxWrapパッケージを参照してください。

  • 1CでもJuliaでも、ライブラリを介さない関数呼び出しはインライン化できるため、共有ライブラリ関数の呼び出しよりさらにオーバーヘッドが小さくなる可能性があります。本文で述べているのは、外部関数を実際に呼び出すコストは、どちらの言語でネイティブに呼び出す場合ともほぼ同じだということです。
  • 2Clang packageを使うと、CヘッダーファイルからJuliaコードを自動生成できます。