Mojo struct
OwnedDLHandle
struct OwnedDLHandle
Represents an owned handle to a dynamically linked library with RAII semantics.
OwnedDLHandle owns the library handle and automatically calls dlclose()
when the object is destroyed. This prevents resource leaks and double-free
bugs.
Example usage:
from std.ffi import OwnedDLHandle
def main() raises:
var lib = OwnedDLHandle("libm.so")
var sqrt = lib.get_function[def(Float64) thin abi("C") -> Float64](
"sqrt"
)
print(sqrt(4.0)) # Prints: 2.0
# Library automatically closed when lib goes out of scopeImplemented traits
AnyType,
ImplicitlyDestructible,
Movable
Methods
__init__
__init__(out self, flags: Int = DEFAULT_RTLD)
Initialize an owned handle to all global symbols in the current process.
Args:
- flags (
Int): The flags to load the dynamic library.
Raises:
If dlopen(nullptr, flags) fails.
__init__[PathLike: PathLike, //](out self, path: PathLike, flags: Int = DEFAULT_RTLD)
Initialize an OwnedDLHandle by loading the dynamic library at the given path.
Parameters:
- PathLike (
PathLike): The type conforming to theos.PathLiketrait.
Args:
- path (
PathLike): The path to the dynamic library file. - flags (
Int): The flags to load the dynamic library.
Raises:
If dlopen(path, flags) fails.
__del__
__del__(deinit self)
Unload the associated dynamic library.
This automatically calls dlclose() on the underlying library handle.
__bool__
__bool__(self) -> Bool
Checks if the handle is valid.
Returns:
Bool: True if the handle is not null and False otherwise.
borrow
borrow(self) -> _DLHandle
Returns a non-owning reference to this handle.
The returned _DLHandle does not own the library and should not be
used after this OwnedDLHandle is destroyed.
Returns:
_DLHandle: A non-owning reference to the library handle.
check_symbol
check_symbol(self, var name: String) -> Bool
Check that the symbol exists in the dynamic library.
Args:
- name (
String): The symbol to check.
Returns:
Bool: True if the symbol exists.
get_function
get_function[result_type: TrivialRegisterPassable](self, var name: String) -> result_type
Returns a handle to the function with the given name in the dynamic library.
result_type must be a C-ABI function type (using the abi("C") effect)
to ensure correct argument and return-value passing. Using a plain Mojo
function type (fn(...) -> T) produces silent ABI corruption for any
struct argument or return value.
Example:
from std.ffi import OwnedDLHandle
var lib = OwnedDLHandle("libm.so")
var sqrt = lib.get_function[def(Float64) abi("C") -> Float64]("sqrt")Parameters:
- result_type (
TrivialRegisterPassable): The C-ABI function pointer type to return.
Args:
- name (
String): The name of the function to get the handle for.
Returns:
result_type: A handle to the function.
get_symbol
get_symbol[result_type: AnyType](self, name: StringSlice[name.origin]) -> Optional[UnsafePointer[result_type, MutAnyOrigin]]
Returns a pointer to the symbol with the given name in the dynamic library, or None if the symbol is not found.
Parameters:
- result_type (
AnyType): The type of the symbol to return.
Args:
- name (
StringSlice): The name of the symbol to get the handle for.
Returns:
Optional: An optional pointer to the symbol, or None if not found.
get_symbol[result_type: AnyType](self, *, cstr_name: UnsafePointer[Int8, cstr_name.origin]) -> Optional[UnsafePointer[result_type, MutAnyOrigin]]
Returns a pointer to the symbol with the given name in the dynamic library, or None if the symbol is not found.
Parameters:
- result_type (
AnyType): The type of the symbol to return.
Args:
- cstr_name (
UnsafePointer): The name of the symbol to get the handle for.
Returns:
Optional: An optional pointer to the symbol, or None if not found.
call
call[name: StringSlice[StaticConstantOrigin], return_type: RegisterPassable = NoneType, *T: AnyType = *?](self, *args: *T) -> return_type
Call a function with any amount of arguments.
Parameters:
- name (
StringSlice): The name of the function. - return_type (
RegisterPassable): The return type of the function. - *T (
AnyType): The types ofargs.
Args:
- *args (
*T): The arguments.
Returns:
return_type: The result.
Was this page helpful?
Thank you! We'll create more content like this.
Thank you for helping us improve!