FFI & Native Library Binding

Real-world analogy

What is it?

dart:ffi (Foreign Function Interface) provides a direct bridge between Dart and C/C++ code, bypassing the platform channel mechanism entirely. It is used for performance-critical native integrations and reusing existing C/C++ libraries on both Android and iOS from a single Dart binding.

Real-world relevance

On a field survey app that processed offline map tiles, the team integrated a C-based image compression library via FFI instead of a platform channel. The channel-based approach took 8ms per tile (unacceptable for real-time map rendering). FFI reduced it to 0.3ms — a 26x improvement.

Key points

• What dart:ffi is — dart:ffi (Foreign Function Interface) allows Dart code to call C and C++ functions directly, passing native types without the overhead of channel message serialisation. It is the lowest-level native integration available in Flutter.
• When FFI is needed over platform channels — FFI is for: calling existing C/C++ libraries (image processing, cryptography, audio codecs, ML model inference), achieving sub-millisecond latency where channel overhead matters, and cross-platform native code reused on both Android and iOS.
• FFI performance characteristics — FFI eliminates the channel serialisation overhead (~1-5ms per call). For single calls, the difference is negligible. For tight loops calling native code thousands of times per second (audio processing, video frames), FFI is the correct choice.
• Native types in FFI — dart:ffi provides C-equivalent types: Int32, Int64, Float, Double, Pointer, Struct. Dart types (int, double, String) must be converted to these native types before passing to C functions.
• DynamicLibrary loading — Load a shared library with DynamicLibrary.open('libname.so') on Android or DynamicLibrary.process() for statically linked libraries. On iOS, most native code is statically linked — use process().
• Struct binding — Use Struct subclasses to represent C structs in Dart. Fields must be annotated with @Int32(), @Float() etc. Allows passing complex data to native functions without manual serialisation.
• package:ffigen for auto-generation — ffigen parses C header files (.h) and generates Dart FFI bindings automatically. This is the production approach for large libraries — manually writing bindings for a 500-function library is impractical and error-prone.
• Memory management in FFI — C does not have garbage collection. Memory allocated with malloc() must be freed with free(). Use calloc from package:ffi for automatic zeroing. Use Arena (package:ffi) for scoped allocation that frees on exit.
• Isolate considerations — FFI calls on the main Dart isolate block the event loop if the C function is slow. For long-running C operations, use compute() or Isolate.run() to offload to a background isolate, then call FFI from there.
• When to mention FFI in interviews — FFI is an advanced topic. Mentioning it signals you understand the full Flutter-to-native stack. Practical examples: integrating a PDF rendering library, using a C-based crypto library for FIPS compliance, integrating a C++ ML inference engine.

Code example

// === Simple FFI example: calling C sqrt function ===
import 'dart:ffi';
import 'dart:io' show Platform;

// 1. Define the C function signature in Dart FFI types
typedef SqrtC = Double Function(Double);          // C type
typedef SqrtDart = double Function(double);       // Dart type

// 2. Load the library
final DynamicLibrary stdlib = Platform.isAndroid
    ? DynamicLibrary.open('libm.so')              // Android: libm.so
    : DynamicLibrary.process();                   // iOS: statically linked

// 3. Look up the function and get a Dart callable
final SqrtDart nativeSqrt = stdlib
    .lookup<NativeFunction<SqrtC>>('sqrt')
    .asFunction<SqrtDart>();

void main() {
  print(nativeSqrt(9.0));  // 3.0 — called directly, no channel overhead
}

// === Real-world FFI: custom C library for NFC data parsing ===
// native/nfc_parser.h:
// struct NfcPayload { int32_t length; uint8_t* data; };
// int32_t parse_nfc_ndef(uint8_t* raw, int32_t len, NfcPayload* out);

// Dart binding generated by ffigen or written manually:
final class NfcPayload extends Struct {
  @Int32()
  external int length;

  external Pointer<Uint8> data;
}

typedef ParseNdefC = Int32 Function(
  Pointer<Uint8> raw,
  Int32 len,
  Pointer<NfcPayload> out,
);
typedef ParseNdefDart = int Function(
  Pointer<Uint8> raw,
  int len,
  Pointer<NfcPayload> out,
);

class NfcParser {
  static final _lib = DynamicLibrary.open('libnfc_parser.so');
  static final _parseNdef = _lib
      .lookup<NativeFunction<ParseNdefC>>('parse_nfc_ndef')
      .asFunction<ParseNdefDart>();

  static Uint8List parseNdef(Uint8List rawBytes) {
    // Allocate native memory
    final arena = Arena();
    try {
      final rawPtr = arena<Uint8>(rawBytes.length);
      rawPtr.asTypedList(rawBytes.length).setAll(0, rawBytes);

      final outPtr = arena<NfcPayload>();
      final result = _parseNdef(rawPtr, rawBytes.length, outPtr);

      if (result < 0) throw NfcParseException('Parse failed: $result');

      return outPtr.ref.data.asTypedList(outPtr.ref.length);
    } finally {
      arena.releaseAll(); // Frees all arena-allocated memory
    }
  }
}

// === pubspec.yaml for ffigen ===
// dev_dependencies:
//   ffigen: ^9.0.0
//
// ffigen:
//   output: 'lib/src/native/bindings.dart'
//   headers:
//     entry-points:
//       - 'native/nfc_parser.h'

Line-by-line walkthrough

1. 1. typedef SqrtC = Double Function(Double) — the C function signature in FFI native types
2. 2. typedef SqrtDart = double Function(double) — the equivalent Dart callable type
3. 3. DynamicLibrary.open('libm.so') on Android — loads the C math library from the Android system
4. 4. stdlib.lookup>('sqrt').asFunction() — finds the 'sqrt' symbol and wraps it as a Dart-callable function
5. 5. nativeSqrt(9.0) — calls C sqrt directly; no channel overhead, no serialisation
6. 6. final class NfcPayload extends Struct — maps a C struct to Dart; @Int32() annotation tells FFI the field size
7. 7. Arena arena — scoped allocator; all allocations freed in the finally block via arena.releaseAll()
8. 8. rawPtr.asTypedList(rawBytes.length).setAll(0, rawBytes) — copies Dart Uint8List bytes into native memory for the C function to read

Spot the bug

import 'dart:ffi';

typedef AddC = Int32 Function(Int32, Int32);
typedef AddDart = int Function(int, int);

final lib = DynamicLibrary.open('libmath.so');
final add = lib.lookup<NativeFunction<AddC>>('add')
    .asFunction<AddDart>();

void processItems(List<int> items) {
  for (final item in items) {
    final result = add(item, 10);
    print(result);
  }
}

Explain like I'm 5

Fun fact

Hands-on challenge

More resources

• dart:ffi — Dart FFI overview (Dart Docs)
• ffigen package (pub.dev)
• package:ffi — Arena and helpers (pub.dev)
• Flutter — Dart and C interop (Flutter Docs)