Libdl — Module

Julia の Libdl モジュールは、共有ライブラリの動的リンクに特化した、より低レベルの機能を提供します。Julia は ccall 組み込み機能を通じて、実行時に共有ライブラリをリンクする機能を標準で備えていますが、Libdl を使うと、さらに細かな制御が可能になります。共有ライブラリをメモリ上とファイルシステムの両方から検索したり、実行時リンカーのオプションを指定して手動で読み込んだり、ライブラリのシンボルを低レベルのポインターとして取得したりできます。

source

Dynamic Linker

Base.Libc.Libdl.dlopen — Function
dlopen(libfile::AbstractString [, flags::Integer]; throw_error:Bool = true)

共有ライブラリを読み込み、不透明なハンドルを返します。

定数 dlext(.so、.dll、または .dylib)で指定される拡張子は、必要に応じて自動的に追加されるため、libfile 文字列から省略できます。libfile が絶対パス名でない場合、配列 DL_LOAD_PATH 内のパスを検索して libfile を探し、その後、システムのロードパスを検索します。

省略可能な flags 引数には、RTLD_LOCAL、RTLD_GLOBAL、RTLD_LAZY、RTLD_NOW、RTLD_NODELETE、RTLD_NOLOAD、RTLD_DEEPBIND、RTLD_FIRST のうち、0 個以上をビット単位の OR で組み合わせて指定します。これらは可能であれば、POSIX(および/または GNU libc、MacOS)の dlopen コマンドに対応するフラグに変換されます。指定された機能が現在のプラットフォームで利用できない場合は無視されます。デフォルトのフラグはプラットフォームによって異なります。MacOS ではデフォルトの dlopen フラグは RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL ですが、その他のプラットフォームでは RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL です。これらのフラグの重要な用途の一つは、動的ライブラリローダーがライブラリ参照をエクスポートされたシンボルにバインドする際のデフォルト以外の動作を指定することと、バインドされた参照をプロセス内のローカルスコープまたはグローバルスコープのどちらに置くかを指定することです。たとえば、RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL を指定すると、そのライブラリのシンボルを他の共有ライブラリから利用できるようになり、共有ライブラリ間に依存関係がある場合に役立ちます。

ライブラリが見つからない場合、このメソッドはエラーをスローします。ただし、キーワード引数 throw_error を false に設定した場合は、nothing を返します。

Note

Julia 1.6 以降では、このメソッドは @executable_path/ で始まるパスを Julia 実行ファイルへのパスに置き換えるため、相対パスを使った再配置可能な読み込みが可能です。Julia 1.5 以前では、これは macOS でのみ機能していました。

source
Base.Libc.Libdl.dlopen_e — Function
dlopen_e(libfile::AbstractString [, flags::Integer])

dlopenと似ていますが、エラーをスローする代わりにC_NULLを返します。このメソッドは非推奨となり、今後はdlopen(libfile::AbstractString [, flags::Integer]; throw_error=false)を使用してください。

source
Base.Libc.Libdl.RTLD_NOW — Constant
RTLD_DEEPBIND
RTLD_FIRST
RTLD_GLOBAL
RTLD_LAZY
RTLD_LOCAL
RTLD_NODELETE
RTLD_NOLOAD
RTLD_NOW

dlopen の列挙定数。該当する場合は、詳細についてプラットフォームのマニュアルページを参照してください。

source
Base.Libc.Libdl.dlsym — Function
dlsym(handle, sym; throw_error::Bool = true)

共有ライブラリのハンドルからシンボルを検索し、成功した場合は呼び出し可能な関数ポインターを返します。

シンボルが見つからない場合、このメソッドはエラーをスローします。ただし、キーワード引数throw_errorがfalseに設定されている場合は、nothingを返します。

source
Base.Libc.Libdl.dlsym_e — Function
dlsym_e(handle, sym)

共有ライブラリのハンドルからシンボルを検索し、見つからない場合はエラーを出さずに C_NULL を返します。このメソッドは非推奨となり、代わりに dlsym(handle, sym; throw_error=false) を使用してください。

source
Base.Libc.Libdl.dlclose — Function
dlclose(::Nothing)

非常によく使われる次のパターンに対して、

try
    hdl = dlopen(library_name)
    ... do something
finally
    dlclose(hdl)
end

Nothing 型のパラメーターを受け取る dlclose() メソッドを定義します。これにより、library_name が見つからなかった場合でも、ユーザーコードの動作を変更する必要がありません。

source
dlclose(handle)

ハンドルが参照する共有ライブラリを閉じます。

source
Base.Libc.Libdl.dlext — Constant
dlext

現在のプラットフォームにおける動的ライブラリのファイル拡張子(例: dll、dylib、so)。

source
Base.Libc.Libdl.dllist — Function
dllist()

Vector{String} で現在読み込まれている動的ライブラリのパスを返します。

source
Base.Libc.Libdl.dlpath — Function
dlpath(libname::Union{AbstractString, Symbol})

ライブラリ libname のフルパスを取得します。

Examples

julia> dlpath("libjulia")
source
dlpath(handle::Ptr{Cvoid})

dlopenからhandleを取得し、フルパスを返します。

source
Base.Libc.Libdl.find_library — Function
find_library(names [, locations])

names 内で最初に見つかり、locations のリストにあるパス、DL_LOAD_PATH、またはシステムのライブラリパス(この順)から正常に dlopen できるライブラリを検索します。成功すると、戻り値はライブラリ名のいずれかになります(locations 内のパスが前置される場合があります)。この文字列は global const に代入し、以降の ccall でライブラリ名として使用できます。失敗した場合は空文字列を返します。

source
Base.DL_LOAD_PATH — Constant
DL_LOAD_PATH

dlopenを呼び出すと、このリスト内のパスが記載順に検索され、その後、システムの場所から有効なライブラリハンドルが検索されます。

source

Lazy Library Loading

Base.Libc.Libdl.LazyLibrary — Type
LazyLibrary(name; flags = <default dlopen flags>,
            dependencies = LazyLibrary[], on_load_callback = nothing)

ccall()、@ccall、dlopen()、dlsym()、dlpath()、またはcglobal()で初めて使用されるまで、自身と依存関係の読み込みを遅延する、遅延読み込み型の共有ライブラリを表します。これは、ライブラリを必要に応じて初期化するためのスレッドセーフな仕組みです。

Arguments

  • name: ライブラリ名(または遅延パス計算)。String、LazyLibraryPath、またはBundledLazyLibraryPathとして指定します。
  • flags: 省略可能なdlopenフラグ(既定値: RTLD_LAZY | RTLD_DEEPBIND)。dlopenを参照してください。
  • dependencies: このライブラリより先に読み込むLazyLibraryオブジェクト参照のベクトル。
  • on_load_callback: 初回読み込み時に任意のコードを実行する省略可能な関数(使用は控えめにしてください。ccall()によって大量のJuliaコードが実行されることは想定されていません。on_load_callback内からccall()を呼び出せるのは、現在のライブラリとその依存関係に限られます。また、デッドロックする可能性があるため、ロード時コールバック内のタスクに対してwait()を呼び出してはいけません)。

dlopen操作はスレッドセーフです。ライブラリを読み込むスレッドは1つだけで、各依存関係の読み込み時に、その依存関係への参照がrelease storeされた後に取得されます。読み込みが完了するまで、ほかのタスクはブロックされます。その後、ハンドルはキャッシュされ、以降のすべての呼び出しで再利用されます(遅延読み込みライブラリにはdlcloseがなく、返されたハンドルに対してdlcloseを呼び出してはいけません)。

Examples

# Basic usage
const mylib = LazyLibrary("libmylib")
@ccall mylib.myfunc(42::Cint)::Cint

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

プラットフォーム固有のライブラリ、遅延パスの構築、__init__()パターンからの移行など、さらに詳しい例については、Using LazyLibrary for Lazy Loadingのマニュアルセクションを参照してください。

Julia 1.11

LazyLibraryはJulia 1.11で追加されました。

LazyLibraryPath、BundledLazyLibraryPath、dlopen、dlsym、add_dependency!も参照してください。

source
Base.Libc.Libdl.LazyLibraryPath — Type
LazyLibraryPath(path_pieces...)

LazyLibraryで使用する、ライブラリのパスを遅延構築するためのヘルパー型です。パスの各要素は評価されずに保持され、ライブラリへの初回アクセス時にjoinpath()で結合されます。引数にはstring()を呼び出せる必要があります。

Example

const mylib = LazyLibrary(LazyLibraryPath(artifact_dir, "lib", "libmylib.so.1.2.3"))
Julia 1.11

LazyLibraryPathはJulia 1.11で追加されました。

関連項目:LazyLibrary、BundledLazyLibraryPath。

source
Base.Libc.Libdl.BundledLazyLibraryPath — Function
BundledLazyLibraryPath(subpath)

Julia ディストリビューション内のライブラリパスを遅延構築するためのヘルパー型です。Julia の非公開共有ライブラリディレクトリを基準にパスを構築します。

主に Julia の標準ライブラリで使用されます。たとえば、次のように使います。

const libgmp = LazyLibrary(BundledLazyLibraryPath("libgmp.so.10"))
Julia 1.11

BundledLazyLibraryPath は Julia 1.11 で追加されました。

関連項目: LazyLibrary、LazyLibraryPath。

source
Base.Libc.Libdl.add_dependency! — Function
add_dependency!(library::LazyLibrary, dependency::LazyLibrary)

libraryより前に読み込む必要がある依存関係を、動的に追加します。依存関係を構築時に特定できない場合にのみ使用してください。

Warning

この関数で追加した依存関係は一時的なもので、現在のプロセス内でのみ有効です。プリコンパイルの境界を越えて保持されることはありません。

可能な場合は、LazyLibraryコンストラクターで依存関係を指定してください。

Julia 1.11

add_dependency!はJulia 1.11で追加されました。

LazyLibraryも参照してください。

source