Native<T> final

final class Native<T>

Annotations: @Since.new('2.19')

Annotation binding an external declaration to its native implementation.

Can only be applied to external declarations of static and top-level functions and variables.

A Native-annotated external function is implemented by native code. The implementation is found in the native library denoted by assetId. Similarly, a Native-annotated external variable is implemented by reading from or writing to native memory.

The compiler and/or runtime provides a binding from assetId to native library, which depends on the target platform. The compiler/runtime can then resolve/lookup symbols (identifiers) against the native library, to find a native function or a native global variable, and bind an external Dart function or variable declaration to that native declaration. By default, the runtime expects a native symbol with the same name as the annotated function or variable in Dart. This can be overridden with the symbol parameter on the annotation.

When used on a function, T must be a function type that represents the native function's parameter and return types. The parameter and return types must be subtypes of NativeType.

When used on a variable, T must be a compatible native type. For example, an int field can be annotated with Int32.

If the type argument T is omitted in the @Native annotation, it is inferred from the static type of the declaration, which must meet the following constraints:

For function or method declarations:

• The return type must be one of the following: - Pointer
  • void
  • Subtype of compound types, such as Struct or Union
• The parameter types must be subtypes of compound types or Pointer

For variable declarations, the type can be any of the following:

• Pointer
• Subtype of compound types, such as Struct or Union

For native global variables that cannot be reassigned, a final variable in Dart or a getter can be used to prevent modifications to the native field.

Example:

@Native<Int64 Function(Int64, Int64)>()
external int sum(int a, int b);

@Native()
external void free(Pointer p);

@Native<Int64>()
external int aGlobalInt;

@Native()
external final Pointer<Char> aGlobalString;

Calling a @Native function, as well as reading or writing to a @Native variable, will try to resolve the symbol in (in the order):

1. the provided or default assetId,
2. the native resolver set with Dart_SetFfiNativeResolver in dart_api.h, and
3. the current process.

At least one of those three must provide a binding for the symbol, otherwise the method call or the variable access fails.

NOTE: This is an experimental feature and may change in the future.

Constructors

Native() const

const Native({String? assetId, bool isLeaf = false, String? symbol})

Implementation

const Native({this.assetId, this.isLeaf = false, this.symbol});

Properties

assetId final

final String? assetId

The ID of the asset in which symbol is resolved, if not using the default.

If no asset name is specified, the default is to use an asset ID specified using an DefaultAsset annotation on the current library's library declaration, and if there is no DefaultAsset annotation on the current library, the library's URI (as a string) is used instead.

Example (file package:a/a.dart):

@Native<Int64 Function(Int64, Int64)>()
external int sum(int a, int b);

Example 2 (file package:a/a.dart):

@DefaultAsset('package:a/a.dart')
library a;

import 'dart:ffi';

@Native<Int64 Function(Int64, Int64)>()
external int sum(int a, int b);

Example 3 (file package:a/a.dart):

@Native<Int64 Function(Int64, Int64)>(assetId: 'package:a/a.dart')
external int sum(int a, int b);

The above three examples are all equivalent.

Prefer using the library URI as an asset name over specifying it. Prefer using an DefaultAsset on the library declaration over specifying the asset name in a Native annotation.

Implementation

final String? assetId;

hashCode no setter inherited

int get hashCode

The hash code for this object.

A hash code is a single integer which represents the state of the object that affects operator == comparisons.

All objects have hash codes. The default hash code implemented by Object represents only the identity of the object, the same way as the default operator == implementation only considers objects equal if they are identical (see identityHashCode).

If operator == is overridden to use the object state instead, the hash code must also be changed to represent that state, otherwise the object cannot be used in hash based data structures like the default Set and Map implementations.

Hash codes must be the same for objects that are equal to each other according to operator ==. The hash code of an object should only change if the object changes in a way that affects equality. There are no further requirements for the hash codes. They need not be consistent between executions of the same program and there are no distribution guarantees.

Objects that are not equal are allowed to have the same hash code. It is even technically allowed that all instances have the same hash code, but if clashes happen too often, it may reduce the efficiency of hash-based data structures like HashSet or HashMap.

If a subclass overrides hashCode, it should override the operator == operator as well to maintain consistency.

Inherited from Object.

Implementation

external int get hashCode;

isLeaf final

final bool isLeaf

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.

This value has no meaning for native fields.

Implementation

final bool isLeaf;

runtimeType no setter inherited

Type get runtimeType

A representation of the runtime type of the object.

Inherited from Object.

Implementation

external Type get runtimeType;

symbol final

final String? symbol

The native symbol to be resolved, if not using the default.

If not specified, the default symbol used for native function lookup is the annotated function's name.

Example:

@Native<Int64 Function(Int64, Int64)>()
external int sum(int a, int b);

Example 2:

@Native<Int64 Function(Int64, Int64)>(symbol: 'sum')
external int sum(int a, int b);

The above two examples are equivalent.

Prefer omitting the symbol when possible.

Implementation

final String? symbol;

Methods

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);

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 ==() inherited

bool operator ==(Object other)

The equality operator.

The default behavior for all Objects is to return true if and only if this object and other are the same object.

Override this method to specify a different equality relation on a class. The overriding method must still be an equivalence relation. That is, it must be:

• Total: It must return a boolean for all arguments. It should never throw.

• Reflexive: For all objects o, o == o must be true.

• Symmetric: For all objects o1 and o2, o1 == o2 and o2 == o1 must either both be true, or both be false.

• Transitive: For all objects o1, o2, and o3, if o1 == o2 and o2 == o3 are true, then o1 == o3 must be true.

The method should also be consistent over time, so whether two objects are equal should only change if at least one of the objects was modified.

If a subclass overrides the equality operator, it should override the hashCode method as well to maintain consistency.

Inherited from Object.

Implementation

external bool operator ==(Object other);

Static Methods

addressOf()

Pointer<T> addressOf<T extends NativeType>(Object native)

The native address of the implementation of native.

When calling this function, the argument for native must be an expression denoting a variable or function declaration which is annotated with Native. For a variable declaration, the type T must be the same native type as the type argument to that @Native annotation. For a function declaration, the type T must be NativeFunction<F> where F was the type argument to that @Native annotation.

For example, for a native C library exposing a function:

#include <stdint.h>
int64_t sum(int64_t a, int64_t b) { return a + b; }

The following code binds sum to a Dart function declaration, and extracts the address of the native sum implementation:

import 'dart:ffi';

typedef NativeAdd = Int64 Function(Int64, Int64);

@Native<NativeAdd>()
external int sum(int a, int b);

void main() {
  Pointer<NativeFunction<NativeAdd>> addressSum = Native.addressOf(sum);
}

Similarly, for a native C library exposing a global variable:

const char* myString;

The following code binds myString to a top-level variable in Dart, and extracts the address of the underlying native field:

import 'dart:ffi';

@Native()
external Pointer<Char> myString;

void main() {
  // This pointer points to the memory location where the loader has
  // placed the `myString` global itself. To get the string value, read
  // the myString field directly.
  Pointer<Pointer<Char>> addressMyString = Native.addressOf(myString);
}

Implementation

@Since('3.3')
external static Pointer<T> addressOf<T extends NativeType>(
  @DartRepresentationOf('T') Object native,
);