pulse_slab_flutter #

Frame-coalesced Flutter bindings for the pulse_slab typed-memory reactive data store. The adapter keeps high-rate store writes in the data plane while Flutter widgets receive only relevant, committed record changes at a chosen UI cadence.

Installation #

Add the adapter to a Flutter application:

dependencies:
  pulse_slab_flutter: ^0.3.0-beta.2

The adapter depends on pulse_slab and re-exports its public Dart API. Import one library in Flutter code:

import 'package:pulse_slab_flutter/pulse_slab_flutter.dart';

For local development in this repository, run dart pub get from the repository root. Its Pub workspace resolves the adjacent 0.3.0-beta.3 core package without an override file. The repository release automation publishes pulse_slab before this adapter and waits until the required core version is available from pub.flutter-io.cn.

Quick start #

import 'package:flutter/widgets.dart';
import 'package:pulse_slab_flutter/pulse_slab_flutter.dart';

final temperature = Float32Field('temperature');
final layout = RecordLayout(
  name: 'Sensor',
  fields: <Field<Object?>>[temperature],
);
final store = PulseStore();
final handle = store.allocate(layout);

ReactiveRecordBuilder(
  store: store,
  handle: handle,
  fields: temperature.mask,
  builder: (context, record) {
    return Text(record.get(temperature).toStringAsFixed(1));
  },
);

ReactiveRecordBuilder owns a field-filtered store subscription. Its default FlutterDeliveryPolicy.frame policy coalesces compatible changes and rebuilds at most once per rendered frame. Use FlutterDeliveryPolicy.manual and flush on the underlying ReactiveRecordListenable for deterministic widget tests or an externally managed render loop.

Examples #

The published minimal Flutter template creates one typed record, updates it from a button, and renders its latest committed value with ReactiveRecordBuilder. Copy its lib/main.dart into an application that has this package as a dependency.

The source-only telemetry integration demo drives multiple records at configurable high rates. It is useful for profiling and integration testing, but is not included in the pub.flutter-io.cn archive.

Layouts with more than 31 fields #

The legacy fields: argument is an integer-mask fast path and remains the best choice for compact layouts. For a layout with more than 31 independently tracked fields, derive a portable, layout-scoped selection and pass it through selection: instead:

final watched = layout.selectionFor(<Field<Object?>>[highIndexField]);

ReactiveRecordBuilder(
  store: store,
  handle: handle,
  selection: watched,
  builder: (context, record) => Text('${record.get(highIndexField)}'),
);

selection: cannot be combined with a nonzero fields: mask. The Flutter adapter passes the selection to PulseStore, filters the resulting committed changes, and coalesces their exact changed-field selection for the next frame.

Use unavailableBuilder when a released record needs a lifecycle-specific replacement. The builder otherwise rethrows a stale-handle read error, which makes unexpected record lifetime violations visible during development.

Package boundaries #

• pulse_slab is a Flutter-free Dart data-plane package containing layouts, segmented memory, transactions, subscriptions, journals, and worker support.
• pulse_slab_flutter contains Flutter framework imports and UI-plane adapters only.

Limitations #

This package is a UI adapter for replaceable state updates, not a lossless event transport. It does not make Dart heap memory shared between isolates, and it does not add a state-management architecture or global singleton.