stdlib_load_library Module
-
- experimental
- 305 statements
- Source File
Cross-platform run-time loading of shared libraries (.so / .dll / .dylib),
in the spirit of numpy.ctypeslib.load_library.
(Specification)
This file is standard Fortran 2008 and needs no preprocessing: the OS-specific
calls (dlopen / LoadLibraryExW, ...) live in stdlib_load_library_c.c,
which must be compiled and linked with it. Platform naming conventions, on
the other hand, are resolved in Fortran through stdlib_system.
## Example
type(shared_library_type) :: lib
procedure(my_iface), pointer :: f
lib = load_library("kernels", path="./plugins") ! libkernels.so / kernels.dll / ...
call c_f_procpointer(lib%symbol("my_func"), f)
call f(...)
call lib%close()
Error handling follows the stdlib convention: when err is present the error
is returned through it, otherwise the program stops with an error message.
Caveats:
* Copying a shared_library_type (intrinsic assignment) copies the OS handle.
Closing one copy invalidates procedure pointers obtained from any copy.
There is deliberately no finalizer: unloading must be explicit.
* Exported symbols should use bind(C, name="...") so their names do not
depend on the compiler that built the library.
* global (RTLD_GLOBAL) has no meaning on Windows and is ignored there.
Uses
-
- iso_c_binding
- stdlib_error
- stdlib_strings
- stdlib_kinds
- stdlib_system
- stdlib_string_type
Derived Types
type, public :: shared_library_type
Handle on a loaded shared library. (Specification)
Type-Bound Procedures
| procedure, public :: close => lib_close | Unload the library |
| procedure, public :: data => lib_data | Address of an exported variable |
| procedure, public :: filename => lib_filename | Path of the file that was actually loaded |
| procedure, public :: has_symbol => lib_has_symbol | Test whether a symbol is exported |
| procedure, public :: is_loaded => lib_is_loaded | Test whether a library is currently loaded |
| procedure, public :: open => lib_open | Load a shared library into this handle |
| procedure, public :: symbol => lib_symbol | Address of an exported procedure |
Functions
public function library_filename(name) result(fname)
- License
- Version
- experimental
Platform-decorated file name of a library, e.g. "fft" -> "libfft.so" / "fft.dll".
(Specification)
Arguments
| Type | Intent | Optional | Attributes | Name | ||
|---|---|---|---|---|---|---|
| character(len=*), | intent(in) | :: | name |
Undecorated library name |
Return Value character(len=:), allocatable
Platform-specific file name
public function load_library(name, path, global, err) result(lib)
- License
- Version
- experimental
Load a shared library and return a handle on it.
Arguments
| Type | Intent | Optional | Attributes | Name | ||
|---|---|---|---|---|---|---|
| character(len=*), | intent(in) | :: | name |
Library name, file name or path |
||
| character(len=*), | intent(in), | optional | :: | path |
Optional directory to search in, instead of the OS search rules |
|
| logical, | intent(in), | optional | :: | global |
Optional flag to make the library symbols available to libraries
loaded afterwards ( |
|
| type(state_type), | intent(out), | optional | :: | err |
Optional state return flag. On error, if not requested, the code stops |
Return Value type(shared_library_type)
Handle on the loaded library
public function shared_library_suffix() result(suffix)
- License
- Version
- experimental
Shared library file extension on this platform (".so", ".dll", ".dylib").
(Specification)
Arguments
NoneReturn Value character(len=:), allocatable
Platform-specific extension, dot included