C Interface

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

Cでエクスポートされた共有ライブラリ内の関数を呼び出します。library.function_nameで指定され、libraryは文字列定数またはリテラルです。ライブラリは省略可能で、その場合はfunction_nameが現在のプロセス内で解決されます。あるいは、@ccallを使用して、dlsymによって返された関数ポインタ$function_pointerを呼び出すこともできます。

@ccallへの各argvalueは、unsafe_convert(argtype, cconvert(argtype, argvalue))への呼び出しを自動的に挿入することによって、対応するargtypeに変換されます。(詳細については、unsafe_convertおよびcconvertのドキュメントも参照してください。)ほとんどの場合、これは単にconvert(argtype, argvalue)への呼び出しをもたらします。

@ccall strlen(s::Cstring)::Csize_t

これはC標準ライブラリ関数を呼び出します:

size_t strlen(char *)

Julia変数sを使用しています。ccallも参照してください。

可変引数は次の規約でサポートされています:

@ccall printf("%s = %d"::Cstring ; "foo"::Cstring, foo::Cint)::Cint

セミコロンは、必須引数(少なくとも1つ必要)と可変引数を区切るために使用されます。

外部ライブラリを使用した例:

# g_uri_escape_stringのCシグネチャ:
# char *g_uri_escape_string(const char *unescaped, const char *reserved_chars_allowed, gboolean allow_utf8);

const glib = "libglib-2.0"
@ccall glib.g_uri_escape_string(my_uri::Cstring, ":/"::Cstring, true::Cint)::Cstring

文字列リテラルは、必要に応じて関数名の前に直接使用することもできます "libglib-2.0".g_uri_escape_string(...

source
ccallKeyword
ccall((function_name, library), returntype, (argtype1, ...), argvalue1, ...)
ccall(function_name, returntype, (argtype1, ...), argvalue1, ...)
ccall(function_pointer, returntype, (argtype1, ...), argvalue1, ...)

Cでエクスポートされた共有ライブラリ内の関数を呼び出します。これはタプル (function_name, library) で指定され、各コンポーネントは文字列またはシンボルのいずれかです。ライブラリを指定する代わりに、現在のプロセスで解決される function_name シンボルまたは文字列を使用することもできます。あるいは、ccall を使用して dlsym によって返された関数ポインタ function_pointer を呼び出すこともできます。

引数の型タプルはリテラルタプルでなければならず、タプル値の変数や式ではありません。

argvalue は、unsafe_convert(argtype, cconvert(argtype, argvalue)) への呼び出しを自動的に挿入することによって、対応する argtype に変換されます。(詳細については、unsafe_convert および cconvert のドキュメントも参照してください。)ほとんどの場合、これは単に convert(argtype, argvalue) への呼び出しをもたらします。

source
Core.Intrinsics.cglobalFunction
cglobal((symbol, library) [, type=Cvoid])

Cでエクスポートされた共有ライブラリ内のグローバル変数へのポインタを取得します。これはccallで指定された通りです。Type引数が指定されていない場合は、デフォルトでPtr{Cvoid}が返されます。値はそれぞれunsafe_loadまたはunsafe_store!によって読み書きできます。

source
Base.@cfunctionMacro
@cfunction(callable, ReturnType, (ArgumentTypes...,)) -> Ptr{Cvoid}
@cfunction($callable, ReturnType, (ArgumentTypes...,)) -> CFunction

与えられた型シグネチャに対して、Julia関数 callable からC呼び出し可能な関数ポインタを生成します。戻り値を ccall に渡すには、シグネチャで引数の型 Ptr{Cvoid} を使用します。

引数の型タプルはリテラルタプルでなければならず、タプル値の変数や式ではなく(ただしスプラット式を含むことはできます)。これらの引数はコンパイル時にグローバルスコープで評価されます(ランタイムまで遅延されることはありません)。関数引数の前に '$' を追加すると、ローカル変数 callable に対してランタイムクロージャを作成するように変更されます(これはすべてのアーキテクチャでサポートされているわけではありません)。

ccall と cfunction の使用に関するマニュアルセクションを参照してください。

julia> function foo(x::Int, y::Int)
           return x + y
       end

julia> @cfunction(foo, Int, (Int, Int))
Ptr{Cvoid} @0x000000001b82fcd0
source
Base.CFunctionType
CFunction 構造体

@cfunction からの戻り値のガーベジコレクションハンドルで、最初の引数が '$' で注釈付けされている場合に使用されます。すべての cfunction ハンドルと同様に、ccallPtr{Cvoid} として渡す必要があり、呼び出し時に自動的に適切な型に変換されます。

@cfunction を参照してください。

source
Base.unsafe_convertFunction
unsafe_convert(T, x)

xを型TのC引数に変換します。入力xcconvert(T, ...)の戻り値でなければなりません。

convertがJuliaオブジェクトを受け取り、それをPtrに変換する必要がある場合、この関数を使用してその変換を定義し実行するべきです。

この関数の結果が使用される間、xへのJulia参照が存在することを確認するように注意してください。したがって、この関数への引数xは決して式であってはならず、変数名またはフィールド参照のみであるべきです。例えば、x=a.b.cは許可されますが、x=[a,b,c]は許可されません。

この関数のunsafeプレフィックスは、この関数へのx引数がプログラムにとってもはやアクセス可能でなくなった後にこの関数の結果を使用すると、未定義の動作が発生する可能性があることを示しています。これには、プログラムの破損やセグメンテーションフォルトが含まれます。

詳細はcconvertを参照してください。

source
Base.cconvertFunction
cconvert(T,x)

xを型TとしてCコードに渡すための値に変換します。通常はconvert(T, x)を呼び出すことで行います。

xが安全にTに変換できない場合、convertとは異なり、cconvertTとは異なる型のオブジェクトを返すことがありますが、それはunsafe_convertが処理するのに適しています。この関数の結果は、unsafe_convertの結果が不要になるまで有効である必要があります。これは、ccallによってアクセスされるメモリを割り当てるために使用できます。複数のオブジェクトを割り当てる必要がある場合、オブジェクトのタプルを返り値として使用できます。

convertcconvertも、JuliaオブジェクトをPtrに変換してはいけません。

source
Base.unsafe_loadFunction
unsafe_load(p::Ptr{T}, i::Integer=1)
unsafe_load(p::Ptr{T}, order::Symbol)
unsafe_load(p::Ptr{T}, i::Integer, order::Symbol)

ポインタ p から始まる i 番目の要素(1-indexed)のアドレスから型 T の値を読み込みます。これは C の式 p[i-1] と同等です。オプションで、原子的なメモリ順序を指定することができます。

この関数の unsafe プレフィックスは、ポインタ p が有効であることを確認するための検証が行われないことを示しています。C と同様に、プログラマーはこの関数を呼び出している間に参照されているメモリが解放されたりガーベジコレクトされたりしないように責任を持つ必要があります。不適切な使用はプログラムをセグメンテーションフォルトさせたり、無効な結果を返す可能性があります。C とは異なり、異なる型として割り当てられたメモリ領域をデリファレンスすることは、型が互換性がある限り有効である場合があります。

Julia 1.10

order 引数は Julia 1.10 以降で利用可能です。

参照: atomic

source
Base.unsafe_store!Function
unsafe_store!(p::Ptr{T}, x, i::Integer=1)
unsafe_store!(p::Ptr{T}, x, order::Symbol)
unsafe_store!(p::Ptr{T}, x, i::Integer, order::Symbol)

ポインタ p から始まる i 番目の要素(1-indexed)のアドレスに型 T の値を格納します。これは C の式 p[i-1] = x と同等です。オプションで、原子的なメモリ順序を指定することができます。

この関数の unsafe プレフィックスは、ポインタ p が有効であることを確認するための検証が行われないことを示しています。C と同様に、プログラマーはこの関数を呼び出している間に参照されているメモリが解放されたりガーベジコレクションされないように責任を持つ必要があります。誤った使用はプログラムをセグメンテーションフォルトさせる可能性があります。C とは異なり、異なる型として割り当てられたメモリ領域に格納することは、型が互換性がある限り有効である場合があります。

Julia 1.10

order 引数は Julia 1.10 以降で利用可能です。

参照: atomic

source
Base.unsafe_modify!Function
unsafe_modify!(p::Ptr{T}, op, x, [order::Symbol]) -> Pair

これらは、関数 op を適用した後にメモリアドレスを取得および設定する操作を原子的に実行します。ハードウェアがサポートしている場合(例えば、原子的なインクリメント)、これは適切なハードウェア命令に最適化される可能性があります。そうでない場合、その実行は次のように似たものになります:

y = unsafe_load(p)
z = op(y, x)
unsafe_store!(p, z)
return y => z

この関数の unsafe プレフィックスは、ポインタ p が有効であることを確認するための検証が行われないことを示しています。Cと同様に、プログラマーはこの関数を呼び出している間に参照されているメモリが解放されたりガーベジコレクションされたりしないように責任を持つ必要があります。誤った使用はプログラムをセグメンテーションフォルトさせる可能性があります。

Julia 1.10

この関数は少なくともJulia 1.10を必要とします。

参照: modifyproperty!, atomic

source
Base.unsafe_replace!Function
unsafe_replace!(p::Ptr{T}, expected, desired,
               [success_order::Symbol[, fail_order::Symbol=success_order]]) -> (; old, success::Bool)

これらは、メモリアドレスを指定された値に条件付きで設定するための操作を原子的に実行します。ハードウェアがサポートしている場合、これは適切なハードウェア命令に最適化される可能性がありますが、そうでない場合、その実行は次のようになります:

y = unsafe_load(p, fail_order)
ok = y === expected
if ok
    unsafe_store!(p, desired, success_order)
end
return (; old = y, success = ok)

この関数の unsafe プレフィックスは、ポインタ p が有効であることを確認するための検証が行われないことを示しています。Cと同様に、プログラマーはこの関数を呼び出している間に参照されているメモリが解放されたりガーベジコレクションされたりしないことを保証する責任があります。誤った使用はプログラムをセグメンテーションフォルトさせる可能性があります。

Julia 1.10

この関数は少なくともJulia 1.10を必要とします。

関連情報: replaceproperty!, atomic

source
Base.unsafe_swap!Function
unsafe_swap!(p::Ptr{T}, x, [order::Symbol])

これらは、メモリアドレスを同時に取得して設定する操作を原子的に実行します。ハードウェアがサポートしている場合、これは適切なハードウェア命令に最適化される可能性があります。そうでない場合、その実行は次のように似ています:

y = unsafe_load(p)
unsafe_store!(p, x)
return y

この関数の unsafe プレフィックスは、ポインタ p が有効であることを確認するための検証が行われないことを示しています。Cと同様に、プログラマーはこの関数を呼び出している間に参照されているメモリが解放されたりガーベジコレクションされたりしないように責任を持つ必要があります。誤った使用はプログラムをセグメンテーションフォルトさせる可能性があります。

Julia 1.10

この関数は少なくともJulia 1.10を必要とします。

参照: swapproperty!, atomic

source
Base.unsafe_copyto!Method
unsafe_copyto!(dest::Ptr{T}, src::Ptr{T}, N)

ソースポインタからデスティネーションに N 要素をチェックなしでコピーします。要素のサイズはポインタの型によって決まります。

この関数の unsafe プレフィックスは、ポインタ destsrc が有効であることを確認するための検証が行われないことを示しています。不適切な使用は、Cと同様にプログラムを破損させたり、セグメンテーションフォルトを引き起こす可能性があります。

source
Base.unsafe_copyto!Method
unsafe_copyto!(dest::Array, do, src::Array, so, N)

ソース配列からデスティネーションに N 要素をコピーします。ソースの線形インデックス so とデスティネーションの do から始まります(1インデックス)。

この関数の unsafe プレフィックスは、N がどちらの配列でも範囲内であることを確認するための検証が行われないことを示しています。不適切な使用は、C と同様にプログラムを破損させたり、セグメンテーションフォルトを引き起こす可能性があります。

source
Base.copyto!Function
copyto!(B::AbstractMatrix, ir_dest::AbstractUnitRange, jr_dest::AbstractUnitRange,
        tM::AbstractChar,
        M::AbstractVecOrMat, ir_src::AbstractUnitRange, jr_src::AbstractUnitRange) -> B

行列 M の要素を、文字パラメータ tM に基づいて B に効率的にコピーします。以下のように条件付けられます:

tM宛先ソース
'N'B[ir_dest, jr_dest]M[ir_src, jr_src]
'T'B[ir_dest, jr_dest]transpose(M)[ir_src, jr_src]
'C'B[ir_dest, jr_dest]adjoint(M)[ir_src, jr_src]

要素 B[ir_dest, jr_dest] は上書きされます。さらに、インデックス範囲パラメータは length(ir_dest) == length(ir_src) および length(jr_dest) == length(jr_src) を満たす必要があります。

さらに copy_transpose! および copy_adjoint! も参照してください。

source
copyto!(dest::AbstractMatrix, src::UniformScaling)

UniformScaling を行列にコピーします。

Julia 1.1

Julia 1.0 ではこのメソッドは正方行列の宛先のみをサポートしていました。Julia 1.1 では長方形の行列のサポートが追加されました。

source
copyto!(dest, do, src, so, N)

コレクション src から線形インデックス so で始まる N 要素を配列 dest のインデックス do で始まる位置にコピーします。dest を返します。

source
copyto!(dest::AbstractArray, src) -> dest

コレクション src から配列 dest にすべての要素をコピーします。dest の長さは src の長さ n 以上でなければなりません。dest の最初の n 要素は上書きされ、他の要素はそのまま残ります。

関連情報としては copy!copy があります。

Warning

変更された引数が他の引数とメモリを共有している場合、動作が予期しないものになることがあります。

julia> x = [1., 0., 3., 0., 5.];

julia> y = zeros(7);

julia> copyto!(y, x);

julia> y
7-element Vector{Float64}:
 1.0
 0.0
 3.0
 0.0
 5.0
 0.0
 0.0
source
copyto!(dest, Rdest::CartesianIndices, src, Rsrc::CartesianIndices) -> dest

範囲 Rsrcsrc のブロックを範囲 Rdestdest のブロックにコピーします。2つの領域のサイズは一致している必要があります。

julia> A = zeros(5, 5);

julia> B = [1 2; 3 4];

julia> Ainds = CartesianIndices((2:3, 2:3));

julia> Binds = CartesianIndices(B);

julia> copyto!(A, Ainds, B, Binds)
5×5 Matrix{Float64}:
 0.0  0.0  0.0  0.0  0.0
 0.0  1.0  2.0  0.0  0.0
 0.0  3.0  4.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0
source
Base.pointerFunction
pointer(array [, index])

配列または文字列のネイティブアドレスを取得します。オプションで、指定された位置 index で取得できます。

この関数は「安全でない」ものです。このポインタが使用される間、array に対するJuliaの参照が存在することを確認するように注意してください。指定されたコードブロック内でガーベジコレクションから array 引数を保護するために、GC.@preserve マクロを使用する必要があります。

一般的には、Ref(array[, index]) を呼び出す方がこの関数よりも好ましいです。なぜなら、それは有効性を保証するからです。

source
Base.unsafe_wrapMethod
unsafe_wrap(Array, pointer::Ptr{T}, dims; own = false)

指定されたアドレス pointer にあるデータの周りに Julia の Array オブジェクトをラップします。コピーは作成されません。ポインタの要素型 T は配列の要素型を決定します。dims は整数(1次元配列の場合)または配列の次元のタプルです。own はオプションで、Julia がメモリの所有権を取得し、配列がもはや参照されなくなったときにポインタに対して free を呼び出すかどうかを指定します。

この関数は「unsafe」とラベル付けされています。なぜなら、pointer が要求された長さのデータに対する有効なメモリアドレスでない場合、クラッシュするからです。unsafe_loadunsafe_store! とは異なり、プログラマーは異なる要素型の2つの配列を通じて基礎データにアクセスしないことを保証する責任があります。これは C の厳密なエイリアス規則に似ています。

source
Base.pointer_from_objrefFunction
pointer_from_objref(x)

JuliaオブジェクトのメモリアドレスをPtrとして取得します。結果として得られるPtrは、オブジェクトをガーベジコレクションから保護することはないため、Ptrが使用される間はオブジェクトが参照され続けることを確認する必要があります。

この関数は不変オブジェクトに対して呼び出すことはできません。なぜなら、それらは安定したメモリアドレスを持たないからです。

関連情報としてunsafe_pointer_to_objrefを参照してください。

source
Base.unsafe_pointer_to_objrefFunction
unsafe_pointer_to_objref(p::Ptr)

Ptrをオブジェクト参照に変換します。ポインタが有効なヒープに割り当てられたJuliaオブジェクトを指していると仮定します。これが当てはまらない場合、未定義の動作が発生するため、この関数は「安全でない」と見なされ、注意して使用する必要があります。

関連情報としてpointer_from_objrefも参照してください。

source
Base.disable_sigintFunction
disable_sigint(f::Function)

現在のタスクで関数の実行中にCtrl-Cハンドラを無効にします。これは、割り込みに安全でないJuliaコードを呼び出す可能性のある外部コードを呼び出すために使用されます。以下のようにdoブロック構文を使用して呼び出すことを意図しています:

disable_sigint() do
    # 割り込みに安全でないコード
    ...
end

ワーカースレッド(Threads.threadid() != 1)では必要ありません。なぜなら、InterruptExceptionはマスタースレッドにのみ送信されるからです。JuliaコードやJuliaランタイムを呼び出さない外部関数は、その実行中に自動的にsigintを無効にします。

source
Base.exit_on_sigintFunction
exit_on_sigint(on::Bool)

exit_on_sigint フラグをジュリアランタイムに設定します。 false の場合、Ctrl-C (SIGINT) は try ブロック内で InterruptException として捕捉可能です。これはREPLのデフォルトの動作であり、-e および -E を介して実行されるコードや、-i オプションで実行されるジュリアスクリプトでも同様です。

true の場合、Ctrl-C によって InterruptException はスローされません。そのようなイベントに対してコードを実行するには atexit が必要です。これは -i オプションなしで実行されるジュリアスクリプトのデフォルトの動作です。

Julia 1.5

関数 exit_on_sigint は少なくともジュリア 1.5 を必要とします。

source
Base.systemerrorFunction
systemerror(sysfunc[, errno::Cint=Libc.errno()])
systemerror(sysfunc, iftrue::Bool)

iftruetrueの場合、sysfuncという説明的な文字列を持つerrnoに対してSystemErrorを発生させます。

source
Base.windowserrorFunction
windowserror(sysfunc[, code::UInt32=Libc.GetLastError()])
windowserror(sysfunc, iftrue::Bool)

systemerrorと同様ですが、errnoを設定するのではなく、エラーコードを返すためにGetLastErrorを使用するWindows API関数用です。

source
Core.PtrType
Ptr{T}

T のデータを指すメモリアドレスです。ただし、メモリが実際に有効であることや、指定された型のデータを実際に表していることは保証されていません。

source
Core.RefType
Ref{T}

T のデータを安全に参照するオブジェクトです。この型は、正しい型の有効な、Julia によって割り当てられたメモリを指すことが保証されています。基になるデータは、Ref 自体が参照されている限り、ガーベジコレクタによって解放されることから保護されています。

Julia では、Ref オブジェクトは [] を使ってデリファレンス(読み込みまたは格納)されます。

T の値 x への Ref の作成は通常 Ref(x) と書かれます。さらに、コンテナ(Array や Ptr など)への内部ポインタを作成するためには、Ref(a, i) と書くことで、ai 番目の要素への参照を作成できます。

Ref{T}() は初期化なしで型 T の値への参照を作成します。ビット型 T の場合、値は現在割り当てられているメモリに存在するものになります。非ビット型 T の場合、参照は未定義となり、それをデリファレンスしようとするとエラー "UndefRefError: access to undefined reference" が発生します。

Ref が未定義の参照かどうかを確認するには、isassigned(ref::RefValue) を使用します。例えば、isassigned(Ref{T}())T がビット型でない場合は false になります。T がビット型の場合、isassigned(Ref{T}()) は常に true になります。

ccall 引数(Ptr または Ref 型のいずれか)として渡されると、Ref オブジェクトはそれが参照するデータへのネイティブポインタに変換されます。ほとんどの T に対して、または Ptr{Cvoid} に変換された場合、これはオブジェクトデータへのポインタです。Tisbits 型の場合、この値は安全に変更できますが、そうでない場合は変更は厳密に未定義の動作となります。

特別なケースとして、T = Any を設定すると、Ptr{Any} に変換されたときに参照自体へのポインタが作成されます(T が不変の場合は jl_value_t const* const*、そうでない場合は jl_value_t *const *)。Ptr{Cvoid} に変換された場合でも、他の T と同様にデータ領域へのポインタが返されます。

C_NULLPtr インスタンスを ccallRef 引数に渡して初期化することができます。

ブロードキャスティングでの使用

Ref は、参照された値をスカラーとして扱うために、ブロードキャスティングで使用されることがあります。

julia> r = Ref(5) # 初期値を持つ Ref を作成
Base.RefValue{Int64}(5)

julia> r[] # Ref から値を取得
5

julia> r[] = 7 # Ref に新しい値を格納
7

julia> r # Ref は現在 7 を含んでいる
Base.RefValue{Int64}(7)

julia> isa.(Ref([1,2,3]), [Array, Dict, Int]) # ブロードキャスティング中に参照値をスカラーとして扱う
3-element BitVector:
 1
 0
 0

julia> Ref{Function}()  # 非ビット型の未定義参照、Function
Base.RefValue{Function}(#undef)

julia> try
           Ref{Function}()[] # 未定義の参照をデリファレンスするとエラーが発生
       catch e
           println(e)
       end
UndefRefError()

julia> Ref{Int64}()[]; # ビット型への参照は与えられない場合は未定義の値を参照する

julia> isassigned(Ref{Int64}()) # ビット型への参照は常に割り当てられている
true
source
Base.isassignedMethod
isassigned(ref::RefValue) -> Bool

与えられた Ref が値に関連付けられているかどうかをテストします。これは、ビットタイプオブジェクトの Ref に対して常に真です。参照が未定義の場合は false を返します。

julia> ref = Ref{Function}()
Base.RefValue{Function}(#undef)

julia> isassigned(ref)
false

julia> ref[] = (foobar(x) = x)
foobar (generic function with 1 method)

julia> isassigned(ref)
true

julia> isassigned(Ref{Int}())
true
source
Base.CstringType
Cstring

ネイティブ文字型Ccharで構成されたCスタイルの文字列です。CstringはNULで終端されています。ネイティブのワイド文字型で構成されたCスタイルの文字列については、Cwstringを参照してください。Cとの文字列相互運用性に関する詳細は、マニュアルを参照してください。

source
Base.ClongType
Clong

ネイティブの signed long C型に相当します。

source
Base.CulongType
Culong

ネイティブの unsigned long C型に相当します。

source
Base.Csize_tType
Csize_t

ネイティブの size_t C型(UInt)に相当します。

source
Base.CwstringType
Cwstring

ネイティブワイドキャラクター型Cwchar_tで構成されたCスタイルの文字列です。CwstringはNULで終端されています。ネイティブキャラクター型で構成されたCスタイルの文字列については、Cstringを参照してください。Cとの文字列の相互運用性に関する詳細については、マニュアルを参照してください。

source

LLVM Interface

Core.Intrinsics.llvmcallFunction
llvmcall(fun_ir::String, returntype, Tuple{argtype1, ...}, argvalue1, ...)
llvmcall((mod_ir::String, entry_fn::String), returntype, Tuple{argtype1, ...}, argvalue1, ...)
llvmcall((mod_bc::Vector{UInt8}, entry_fn::String), returntype, Tuple{argtype1, ...}, argvalue1, ...)

最初の引数に提供されたLLVMコードを呼び出します。この最初の引数を指定する方法はいくつかあります:

  • 関数レベルのIRを表すリテラル文字列として(LLVMのdefineブロックに似ており)、引数は連続した無名のSSA変数(%0, %1など)として利用可能です;
  • 2要素のタプルとして、モジュールIRの文字列と呼び出すエントリポイント関数の名前を表す文字列を含む;
  • 2要素のタプルとして、モジュールがビットコードのVector{UInt8}として提供される。

ccallとは異なり、引数の型はタプル型として指定する必要があり、型のタプルではありません。すべての型とLLVMコードはリテラルとして指定する必要があり、変数や式ではありません(これらのリテラルを生成するために@evalを使用する必要があるかもしれません)。

不透明ポインタptrとして記述)はLLVMコードでは許可されていません。

使用例についてはtest/llvmcall.jlを参照してください。

source