LocusReliabilityRegistry class

Singleton that holds the SDK's reliability event stream and counters.

The public surface (Locus.reliability, Locus.metrics) is a thin re-export of this registry. Internal SDK code (sync, storage, quarantine janitor, ...) calls the record* / emit methods to feed it.

Per-isolate scope

instance is a static final inside this Dart library, which means one registry per Dart isolate, not one per process. Headless callbacks (geofence triggers, sync-on-boot) execute in a secondary isolate spawned by the Flutter engine. Events that fire there land in that isolate's registry, not the foreground app's.

Practical consequences for embedders:

  • Subscribing to Locus.reliability from a Riverpod provider only sees events emitted from the foreground isolate.
  • Locus.metrics.snapshot() read from the foreground only reflects foreground-side counters — captures and syncs that happen during headless execution don't show up there.
  • Background-isolate observability is best read via the structured logs the SDK emits (e.g. tracking_heartbeat), which the platform side forwards into the unified log stream.

Plumbing headless events into the foreground registry would require a platform-channel bridge with explicit ordering guarantees and is tracked as a follow-up.

Properties

hashCode → int
The hash code for this object.
no setterinherited
metrics → LocusMetrics
Public read-only metrics view.
no setter
reliability → Stream<LocusReliabilityEvent>
Public stream of reliability events.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
syncHealthMonitor → SyncHealthMonitor?
Currently installed sync health monitor, if any. Internal callers may use it to call SyncHealthMonitor.evaluate from a heartbeat tick.
no setter

Methods

emit(LocusReliabilityEvent event) → void
Emit a reliability event to subscribers. Safe to call at any time: after resetForTests closes the controller, the next call will see a fresh broadcast stream.
installSyncHealthMonitor(SyncHealthMonitor monitor) → Future<void>
Installs a SyncHealthMonitor. Detaches and replaces any previously installed monitor.
installSyncMetricsRecorder(SyncMetricsRecorder recorder) → Future<void>
Installs a SyncMetricsRecorder. Detaches and replaces any previously installed recorder. Held by the registry so the subscription stays alive without callers needing to hold the reference themselves.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
recordCaptured(int count) → void
Increment the captured-points counter.
recordDropped(int count) → void
Record an eviction (queue overflow or age limit) that dropped count points. Increments the cumulative pointsDropped counter.
recordSent(int count, {DateTime? at}) → void
Record a successful sync that flushed count points.
recordSyncFailure({int? httpStatus, DateTime? at}) → void
Record a failed sync attempt. Optionally carries the HTTP status seen.
resetForTests() → Future<void>
Resets the registry to a pristine state. Intended for tests only. Closes the existing event stream and creates a fresh one.
setQuarantinedNow(int count) → void
Update the current quarantine size. This is a gauge, not a counter, so the value is replaced wholesale.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Properties

instance → LocusReliabilityRegistry
Per-isolate singleton — see the class-level dartdoc on isolate scope.
final