declareQuerier method

Querier declareQuerier(Object keyExpr, { QueryTarget target = QueryTarget.bestMatching, ConsolidationMode consolidation = ConsolidationMode.auto, Duration? timeout, CongestionControl? congestionControl, Priority? priority, bool? isExpress, Locality? allowedDestination, ReplyKeyExpr? acceptReplies, bool enableMatchingListener = false, })

Declares a querier on the given keyExpr.

Returns a Querier that can efficiently send multiple queries to the same key expression with pre-configured options. Call Querier.close when done.

Send options

congestionControl, priority, isExpress, allowedDestination and acceptReplies are each optional, and omitting one — or passing null — means the same thing: canon decides. This binding substitutes no value of its own. On this path canon's defaults are CongestionControl.block (a request operation; put, deleteResource and declarePublisher default to CongestionControl.drop instead), Priority.data, isExpress: false, Locality.any, and ReplyKeyExpr.matchingQuery.

⚠️ Read CongestionControl before selecting CongestionControl.block: it can park the calling thread for seconds and then close the transport.

target controls which queryables are targeted (default: bestMatching). consolidation controls reply consolidation (default: auto). timeout sets the query timeout, fixed at declaration time for every Querier.get this querier sends. Omitting it means canon decides (the session's configured default, itself 10 seconds by default).

⚠️ A timeout that marshals to 0 ms is refused with ArgumentError, on the wire value rather than on Duration.zero identity — the same rule get carries, and for the same reason: zenoh reads wire 0 as "use the configured default", so an instant-expiry request would silently become ~10 seconds. Canon's per-get options struct has no timeout field, so this declaration is the only place the value can be refused.

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

⛔ Throws ArgumentError if congestionControl is CongestionControl.blockFirst and the loaded native was built without Z_FEATURE_UNSTABLE_API. canon declares Z_CONGESTION_CONTROL_BLOCK_FIRST only under that flag, so on such a build there is no value to send. Pass CongestionControl.block or CongestionControl.drop, or select the unstable native through your app's user_defines.

Implementation

Querier declareQuerier(
  Object keyExpr, {
  QueryTarget target = QueryTarget.bestMatching,
  ConsolidationMode consolidation = ConsolidationMode.auto,
  Duration? timeout,
  CongestionControl? congestionControl,
  Priority? priority,
  bool? isExpress,
  Locality? allowedDestination,
  ReplyKeyExpr? acceptReplies,
  bool enableMatchingListener = false,
}) {
  // FIRST STATEMENT, ahead of the timeout guard. Where an entry point
  // carries more than one refuse-first domain check the congestion one runs
  // first, and the order is stated rather than incidental: of the faults a
  // caller can trip at once, this is the only one no change to the call's
  // other arguments can fix. A zero timeout is expressible correctly by
  // choosing another number; blockFirst on a stable native is a property of
  // the build.
  requireCongestionControlSupported(congestionControl);
  // BEFORE any native call, including key-expression validation.
  _rejectSentinelTimeout(timeout);
  return _withKeyExprArg(keyExpr, 'keyExpr', (loanedSession, loanedKe) {
    return Querier.declare(
      loanedSession,
      loanedKe,
      keyExprString(keyExpr, 'keyExpr'),
      target: target,
      consolidation: consolidation,
      timeout: timeout,
      congestionControl: congestionControl,
      priority: priority,
      isExpress: isExpress,
      allowedDestination: allowedDestination,
      acceptReplies: acceptReplies,
      enableMatchingListener: enableMatchingListener,
    );
  });
}