declarePublisher method

Publisher declarePublisher(Object keyExpr, { Encoding? encoding, CongestionControl? congestionControl, Priority? priority, bool? isExpress, Locality? allowedDestination, bool enableMatchingListener = false, })

Declares a publisher on the given keyExpr.

Returns a Publisher that can efficiently publish multiple messages to the same key expression. Call Publisher.close when done.

Send options

congestionControl, priority, isExpress and allowedDestination 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.drop (a push operation; get and declareQuerier default to CongestionControl.block instead), Priority.data, isExpress: false, and Locality.any.

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

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

Publisher declarePublisher(
  Object keyExpr, {
  Encoding? encoding,
  CongestionControl? congestionControl,
  Priority? priority,
  bool? isExpress,
  Locality? allowedDestination,
  bool enableMatchingListener = false,
}) {
  // FIRST STATEMENT, and it is what keeps `publisher.dart:57` out of reach:
  // `Publisher.declare` callocs its entity handle BEFORE the marshal and
  // releases it only on the `rc != 0` branch, so a guard sited at the
  // marshal would strand that block on every refusal.
  requireCongestionControlSupported(congestionControl);
  return _withKeyExprArg(keyExpr, 'keyExpr', (loanedSession, loanedKe) {
    return Publisher.declare(
      loanedSession,
      loanedKe,
      encoding: encoding,
      congestionControl: congestionControl,
      priority: priority,
      isExpress: isExpress,
      allowedDestination: allowedDestination,
      enableMatchingListener: enableMatchingListener,
    );
  });
}