declareBackgroundQueryable method

Stream<Query> declareBackgroundQueryable(Object keyExpr, { bool complete = false, Locality? allowedOrigin, })

Declares a fire-and-forget background queryable on the given keyExpr.

Returns a Stream of Querys. Delivered queries are fully replyable and disposable, exactly like those from declareQueryable. Unlike declareQueryable, the background queryable has no handle and cannot be explicitly closed. It lives until the session is closed, at which point the stream completes automatically.

The complete parameter indicates whether this queryable is a complete source of data for its key expression (default: false).

allowedOrigin restricts whose traffic this declaration accepts. Omitting it — or passing null — means canon decides, which is Locality.any. See Locality.

⚠️ This stream is UNBOUNDED, and pausing it does not stop the flow — see declareQueryable, including the native cost of a retained query clone. No bounded form of this surface exists: a background declaration hands back no handle. Use declarePullQueryable when you need a bound.

Throws ZenohException if the key expression is invalid. Throws StateError if the session has been closed.

Implementation

Stream<Query> declareBackgroundQueryable(
  Object keyExpr, {
  bool complete = false,
  Locality? allowedOrigin,
}) {
  return _withKeyExprArg(keyExpr, 'keyExpr', (loanedSession, loanedKe) {
    // ALLOCATE-LAST: the channel is created only once the key expression has
    // been accepted, so a rejected one cannot strand an open ReceivePort.
    final channel = QueryChannel.create();
    final rc = bindings.zd_declare_background_queryable(
      loanedSession.cast(),
      loanedKe.cast(),
      channel.receivePort.sendPort.nativePort,
      complete ? 1 : 0,
      allowedOrigin?.value ?? -1,
    );

    if (rc != 0) {
      channel.abandon();
      throw ZenohException('Failed to declare background queryable', rc);
    }

    return channel.stream;
  });
}