DynamicLibrary final

final class DynamicLibrary

A dynamically loaded native library.

A dynamically loaded library is a mapping from symbols to memory addresses. These memory addresses can be accessed through lookup.

Available Extensions

• DynamicLibraryExtension

Constructors

DynamicLibrary.executable() factory

factory DynamicLibrary.executable()

Creates a DynamicLibrary containing all the symbols of the running executable.

This is useful for using dart:ffi with static libraries.

Implementation

external factory DynamicLibrary.executable();

DynamicLibrary.open() factory

factory DynamicLibrary.open(String path)

Loads a library file and provides access to its symbols.

The path must refer to a native library file which can be successfully loaded.

Calling this function multiple times with the same path, even across different isolates, only loads the library into the DartVM process once. Multiple loads of the same library file produces DynamicLibrary objects which are equal (==), but not identical.

Implementation

external factory DynamicLibrary.open(String path);

DynamicLibrary.process() factory

factory DynamicLibrary.process()

Creates a DynamicLibrary holding all global symbols.

Any symbol in a library currently loaded with global visibility (including the executable itself) may be resolved through this library.

Implementation

external factory DynamicLibrary.process();

Properties

handle no setter

Pointer<Void> get handle

The opaque handle to the dynamic library.

Similar to the return value of dlopen(3). Can be used as arguments to other functions in the dlopen API through FFI calls.

Implementation

external Pointer<Void> get handle;

hashCode no setter override

int get hashCode

The hash code for a DynamicLibrary only depends on the loaded library.

Implementation

external int get hashCode;

runtimeType no setter inherited

Type get runtimeType

A representation of the runtime type of the object.

Inherited from Object.

Implementation

external Type get runtimeType;

Methods

close()

void close()

Closes this dynamic library.

After calling close, this library object can no longer be used for lookups. Further, this information is forwarded to the operating system, which may unload the library if there are no remaining references to it in the current process.

Depending on whether another reference to this library has been opened, pointers and functions previously returned by lookup and DynamicLibraryExtension.lookupFunction may become invalid as well.

Implementation

@Since('3.1')
external void close();

lookup()

Pointer<T> lookup<T extends NativeType>(String symbolName)

Looks up a symbol in the DynamicLibrary and returns its address in memory.

Similar to the functionality of the dlsym(3) system call.

The symbol must be provided by the dynamic library. To check whether the library provides such symbol, use providesSymbol.

Implementation

external Pointer<T> lookup<T extends NativeType>(String symbolName);

lookupFunction() extension

F lookupFunction<T extends Function, F extends Function>(
  String symbolName, {
  bool isLeaf = false,
})

Looks up a native function and returns it as a Dart function.

T is the C function signature, and F is the Dart function signature.

For example:

int32_t add(int32_t a, int32_t b) {
  return a + b;
}

DynamicLibrary dylib = DynamicLibrary.executable();
final add = dylib.lookupFunction<Int32 Function(Int32, Int32), int Function(int, int)>(
        'add');

isLeaf specifies whether the function is a leaf function. Leaf functions are small, short-running, non-blocking functions which are not allowed to call back into Dart or use any Dart VM APIs. Leaf functions are invoked bypassing some of the heavier parts of the standard Dart-to-Native calling sequence which reduces the invocation overhead, making leaf calls faster than non-leaf calls. However, this implies that a thread executing a leaf function can't cooperate with the Dart runtime. A long running or blocking leaf function will delay any operation which requires synchronization between all threads associated with an isolate group until after the leaf function returns. For example, if one isolate in a group is trying to perform a GC and a second isolate is blocked in a leaf call, then the first isolate will have to pause and wait until this leaf call returns.

Available on DynamicLibrary, provided by the DynamicLibraryExtension extension

Implementation

external F lookupFunction<T extends Function, F extends Function>(
  String symbolName, {
  bool isLeaf = false,
});

noSuchMethod() inherited

dynamic noSuchMethod(Invocation invocation)

Invoked when a nonexistent method or property is accessed.

A dynamic member invocation can attempt to call a member which doesn't exist on the receiving object. Example:

dynamic object = 1;
object.add(42); // Statically allowed, run-time error

This invalid code will invoke the noSuchMethod method of the integer 1 with an Invocation representing the .add(42) call and arguments (which then throws).

Classes can override noSuchMethod to provide custom behavior for such invalid dynamic invocations.

A class with a non-default noSuchMethod invocation can also omit implementations for members of its interface. Example:

class MockList<T> implements List<T> {
  noSuchMethod(Invocation invocation) {
    log(invocation);
    super.noSuchMethod(invocation); // Will throw.
  }
}
void main() {
  MockList().add(42);
}

This code has no compile-time warnings or errors even though the MockList class has no concrete implementation of any of the List interface methods. Calls to List methods are forwarded to noSuchMethod, so this code will log an invocation similar to Invocation.method(#add, [42]) and then throw.

If a value is returned from noSuchMethod, it becomes the result of the original invocation. If the value is not of a type that can be returned by the original invocation, a type error occurs at the invocation.

The default behavior is to throw a NoSuchMethodError.

Inherited from Object.

Implementation

@pragma("vm:entry-point")
@pragma("wasm:entry-point")
external dynamic noSuchMethod(Invocation invocation);

providesSymbol()

bool providesSymbol(String symbolName)

Checks whether this dynamic library provides a symbol with the given name.

Implementation

@Since('2.14')
external bool providesSymbol(String symbolName);

toString() inherited

String toString()

A string representation of this object.

Some classes have a default textual representation, often paired with a static parse function (like int.parse). These classes will provide the textual representation as their string representation.

Other classes have no meaningful textual representation that a program will care about. Such classes will typically override toString to provide useful information when inspecting the object, mainly for debugging or logging.

Inherited from Object.

Implementation

external String toString();

Operators

operator ==() override

bool operator ==(Object other)

Dynamic libraries are equal if they load the same library.

Implementation

external bool operator ==(Object other);