flutter_cpp_bridge #

A Flutter package that simplifies calling C++ code from Dart via dart:ffi.

Instead of writing raw FFI bindings by hand, flutter_cpp_bridge gives you three building blocks — Service, ServicePool, and StandaloneService — that handle library loading, lifecycle management, and event-driven message delivery.

Target platform: Linux. This package is designed for Linux-first deployments, including embedded targets such as flutter-pi (Raspberry Pi and similar SBCs). The Dart abstractions are platform-agnostic, but the C++ build configuration and .so loading convention in this repo assume a Linux environment.

Features #

• Load any C++ shared library (.so) with a single line.
• Automatic start/stop lifecycle for your C++ services.
• Event-driven message delivery via NativeCallable: the C++ worker calls a Dart callback when a message is ready — zero CPU consumption at idle.
• Clean subclassing pattern to bind additional native functions.
• Standalone services that run independently, outside of a pool.
• Designed for embedded Linux / flutter-pi use cases.

Acknowledgements #

Special thanks to grybouilli for his significant contributions to this project !

Getting started #

Add the package to your pubspec.yaml:

dependencies:
  flutter_cpp_bridge: ^1.0.1

Or pin to a specific Git commit:

dependencies:
  flutter_cpp_bridge:
    git:
      url: https://github.com/Renaud-Barrau/flutter_cpp_bridge
      ref: main

Your project layout #

For each C++ service you want to call from Dart, you need:

• A Dart wrapper class in lib/ that extends Service or StandaloneService
• A C++ source file + CMakeLists.txt in linux/<myservice>/
• Two small additions to your app's linux/CMakeLists.txt

my_flutter_app/
├── pubspec.yaml                    ← add flutter_cpp_bridge dependency
├── lib/
│   ├── main.dart
│   └── myservice.dart             ← extends Service, binds extra C functions
└── linux/
    ├── CMakeLists.txt             ← add_subdirectory + install(TARGETS …)
    └── myservice/
        ├── CMakeLists.txt         ← add_library, PREFIX "", include dirs
        └── myservice.cpp          ← your struct + worker + FCB_EXPORT_SYMBOLS

The sections below walk through each of these files.

C++ side #

Each library must export five functions using C linkage. These are the only mandatory symbols; everything else is optional and can be added per-library.

#define EXPORT extern "C" __attribute__((visibility("default")))

EXPORT void  start_service();
EXPORT void  stop_service();
EXPORT YourMessageType* get_next_message();   // nullptr when queue is empty
EXPORT void  free_message(YourMessageType*);
EXPORT void  set_message_callback(void (*cb)());

• start_service / stop_service: start and stop the service (e.g. spawn/join a worker thread).
• get_next_message: returns a pointer to the next pending message, or nullptr if the queue is empty. The C++ side owns the memory.
• free_message: called by Dart when it is done with a message. The pointer must remain valid until this function returns.
• set_message_callback: stores the function pointer cb. The C++ worker calls cb() (from any thread) immediately after pushing a new message. Dart then drains the whole queue on the event loop — no periodic timer needed.

Any extra functions (to read fields, send commands, etc.) can be exported and bound on the Dart side through subclassing.

C++ helpers (recommended) #

The package ships a header-only helper at linux/include/flutter_cpp_bridge/service_helpers.h. It provides two template types and macros that generate all five mandatory symbols, so you only write what is unique to your service.

The complete CMake wiring (defining FCB_CPP_INCLUDE and the install rule) is covered in Compiling your C++ libraries below.

Pooled service — queue variant (fcb::Queue<T>): Each push() enqueues one message; Dart reads them FIFO. Uses std::deque so push_back() never invalidates existing pointers.

#include <chrono>
#include "flutter_cpp_bridge/service_helpers.h"

struct my_message_t { int value; };

static fcb::Queue<my_message_t> g_svc;

static void worker(fcb::Queue<my_message_t>& svc) {
    int i = 0;
    while (!svc.stopped()) {
        svc.push({i++});
        std::this_thread::sleep_for(std::chrono::seconds(1));
    }
}

FCB_EXPORT_SYMBOLS(g_svc, worker)

FCB_EXPORT int get_value(my_message_t* msg) { return msg->value; }

Pooled service — current-value variant (fcb::CurrentValue<T>): set() overwrites the single stored value; Dart reads it once then releases. Useful when only the latest value matters (e.g. a sensor reading).

#include <chrono>
#include "flutter_cpp_bridge/service_helpers.h"

struct sensor_msg_t { float temperature; };

static fcb::CurrentValue<sensor_msg_t> g_svc;

static void worker(fcb::CurrentValue<sensor_msg_t>& svc) {
    while (!svc.stopped()) {
        svc.set({read_sensor()});
        std::this_thread::sleep_for(std::chrono::milliseconds(500));
    }
}

FCB_EXPORT_SYMBOLS(g_svc, worker)

Standalone service (no message queue):

#include <cstdio>
#include "flutter_cpp_bridge/service_helpers.h"

FCB_EXPORT_STANDALONE_NOOP()

FCB_EXPORT void hello() {
    printf("Hello from C++!\n");
    fflush(stdout);
}

For standalone services that need real start/stop logic, use FCB_EXPORT_STANDALONE(start_fn, stop_fn) instead.

Manual implementation (without helpers) #

If you prefer to write the five symbols by hand — or need behaviour not covered by the helpers — see the full manual example below. The pattern used by the helpers (std::deque + _ready flag) is described in the comments.

Pooled service (manual):

#include <deque>
#include <mutex>
#include <thread>
#include <chrono>
#include <atomic>

#define FCB_EXPORT extern "C" __attribute__((visibility("default")))

struct my_message_t { int value; };

static std::deque<my_message_t> queue;  // deque: push_back never invalidates pointers
static std::mutex mtx;
static std::atomic<bool> running{false};
static void (*g_callback)() = nullptr;

FCB_EXPORT void set_message_callback(void (*cb)()) { g_callback = cb; }

FCB_EXPORT void start_service() {
    running = true;
    std::thread([] {
        int i = 0;
        while (running) {
            { std::lock_guard<std::mutex> lock(mtx); queue.push_back({i++}); }
            if (g_callback) g_callback();
            std::this_thread::sleep_for(std::chrono::seconds(1));
        }
    }).detach();
}

FCB_EXPORT void stop_service()  { running = false; }

FCB_EXPORT my_message_t* get_next_message() {
    std::lock_guard<std::mutex> lock(mtx);
    return queue.empty() ? nullptr : &queue.front();
}

FCB_EXPORT void free_message(my_message_t* msg) {
    std::lock_guard<std::mutex> lock(mtx);
    for (auto it = queue.begin(); it != queue.end(); ++it)
        if (&(*it) == msg) { queue.erase(it); break; }
}

FCB_EXPORT int get_value(my_message_t* msg) { return msg->value; }

Standalone service (manual):

#include <cstdio>

#define FCB_EXPORT extern "C" __attribute__((visibility("default")))

FCB_EXPORT void  start_service()  {}
FCB_EXPORT void  stop_service()   {}
FCB_EXPORT void* get_next_message() { return nullptr; }
FCB_EXPORT void  free_message([[maybe_unused]] void* msg) {}
FCB_EXPORT void  set_message_callback([[maybe_unused]] void (*cb)()) {}

FCB_EXPORT void hello() {
    printf("Hello from C++!\n");
    fflush(stdout);
}

Dart / Flutter side #

1. Subclass Service to bind your library #

import 'dart:ffi';
import 'package:flutter_cpp_bridge/flutter_cpp_bridge.dart';

class MyService extends Service {
  MyService(super.libname) {
    getValue = lib
        .lookup<NativeFunction<Int32 Function(Pointer<BackendMsg>)>>('get_value')
        .asFunction<int Function(Pointer<BackendMsg>)>();
  }

  late final int Function(Pointer<BackendMsg>) getValue;
}

2. Lifecycle management #

Register a job before starting the service so no message is ever dropped, then choose the lifecycle approach that fits your app.

Option A — ServicePool (no extra dependencies)

final pool    = ServicePool();
final service = MyService('libmyservice.so');

// Register first — before addService — so no early message is missed.
service.assignJob((msg) {
  print('value: ${service.getValue(msg)}');
  // freeMessage is called automatically after this callback returns.
});

pool.addService(service);   // calls start_service; Dart wakes up on demand
// ...
pool.dispose();             // stops all services, releases native callbacks

ServicePool is a thin convenience wrapper: it calls startService() for you and lets you stop all services with a single pool.dispose(). It carries no state beyond the list of registered services.

Option B — Riverpod Notifier (for apps already using flutter_riverpod)

Each service lives inside its own Notifier. Riverpod manages the lifecycle automatically: build() starts the service, ref.onDispose stops it when the provider is no longer needed. No ServicePool is required.

import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'myservice.dart';

class MyState {
  final int value;
  const MyState({required this.value});
  MyState copyWith({int? value}) => MyState(value: value ?? this.value);
}

class MyNotifier extends Notifier<MyState> {
  @override
  MyState build() {
    final service = MyService('libmyservice.so');

    // assignJob before startService — same rule as with ServicePool.
    service.assignJob((msg) {
      state = state.copyWith(value: service.getValue(msg));
    });

    service.startService();
    ref.onDispose(service.dispose);

    return const MyState(value: 0);
  }
}

final myProvider = NotifierProvider<MyNotifier, MyState>(MyNotifier.new);

The provider is then consumed like any other Riverpod provider:

// In a ConsumerWidget:
final myState = ref.watch(myProvider);
Text('value: ${myState.value}');

3. Standalone services #

For libraries that don't produce a message queue (command sinks, loggers, one-shot callers…), extend StandaloneService. The C++ start_service is called automatically in the constructor:

class HelloService extends StandaloneService {
  HelloService(super.libname) {
    hello = lib
        .lookup<NativeFunction<Void Function()>>('hello')
        .asFunction<void Function()>();
  }

  late final void Function() hello;
}

final greeter = HelloService('libhello.so');
greeter.hello(); // prints "Hello from C++!" — C++ service already running
// ...
greeter.dispose(); // calls stop_service and releases the NativeCallable

4. Sharing service instances across the app #

Without a state-management library, use static members on a dedicated class:

// app_services.dart
class Services {
  static final MyService    my      = MyService('libmyservice.so');
  static final HelloService greeter = HelloService('libhello.so');
}

// Anywhere in the app:
Services.greeter.hello();

With Riverpod, each NotifierProvider is already globally accessible through ref — no extra singleton class needed. Instantiation, lifecycle, and state are all handled by the provider graph.

How event-driven delivery works #

C++ worker thread                 Dart event loop
─────────────────                 ───────────────
push message to queue
call g_callback()   ──────────►  _onNotify() scheduled
                                  └─ drains queue with get_next_message()
                                  └─ emits each Pointer on messageStream
                                  └─ assignJob callback runs
                                  └─ free_message called automatically

NativeCallable.listener (Dart SDK ≥ 3.1) makes this safe: the C++ thread calls the native function pointer and returns immediately; Dart processes the notification asynchronously on its event loop without any blocking or busy-wait.

Compiling your C++ libraries (Linux) #

CMakeLists for your library #

Create one CMakeLists.txt per library. The PREFIX "" prevents CMake from generating libmyservice.so instead of myservice.so, which must match the name you pass to DynamicLibrary.open:

cmake_minimum_required(VERSION 3.13)
project(myservice LANGUAGES CXX)

add_library(myservice SHARED myservice.cpp)
target_compile_features(myservice PRIVATE cxx_std_17)
target_include_directories(myservice PRIVATE "${FCB_CPP_INCLUDE}")
set_target_properties(myservice PROPERTIES
  CXX_VISIBILITY_PRESET default
  PREFIX ""               # produce myservice.so, not libmyservice.so
)

Wiring into the Flutter app's CMakeLists.txt #

Add the following to your Flutter app's linux/CMakeLists.txt (after the standard Flutter boilerplate and before include(flutter/generated_plugins.cmake)):

# Path to the flutter_cpp_bridge C++ helpers header.
# Flutter creates this symlink automatically during `flutter pub get`.
set(FCB_CPP_INCLUDE
  "${CMAKE_CURRENT_SOURCE_DIR}/flutter/ephemeral/.plugin_symlinks/flutter_cpp_bridge/linux/include"
)

# Build the service library.
add_subdirectory("myservice")

# Install the .so alongside the app (INSTALL_BUNDLE_LIB_DIR is set by Flutter).
install(TARGETS myservice
  LIBRARY DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime
)

The Flutter Linux runner automatically sets RPATH to $ORIGIN/lib, so the dynamic linker will find .so files in bundle/lib/ at runtime without any extra LD_LIBRARY_PATH configuration.

flutter-pi note: bundle and deploy the .so files to the same lib/ directory relative to your app executable. flutter-pi honours the same $ORIGIN/lib RPATH convention as the desktop Linux runner.

Example #

A complete working example is in the example/ folder. It demonstrates:

Platform support #