Struct SubscriptionBuilder

pub struct SubscriptionBuilder<MessageType, F>
where
    F: Clone,
{ /* private fields */ }

Immutable builder for configuring MQTT subscriptions

Implementations

impl<MessageType, F> SubscriptionBuilder<MessageType, F>

where F: Clone,

pub fn new( client: MqttClient<F>, default_pattern: TopicPatternPath, ) -> SubscriptionBuilder<MessageType, F>

Create new builder with default pattern

pub fn with_cache(self, capacity: usize) -> SubscriptionBuilder<MessageType, F>

Enable LRU cache for topic parsing optimization.

When the same MQTT topic paths are received repeatedly, caching the parsing results can significantly improve performance by avoiding redundant topic pattern matching.

Parameters

• capacity - Maximum number of topic parsing results to cache (LRU eviction) Set to 0 to disable caching entirely

Performance Impact

• Memory: ~50-200 bytes per cached topic (depending on topic complexity)
• CPU: Reduces topic parsing overhead for repeated patterns
• Use case: Most beneficial when same topics repeat frequently

Examples

// Cache last 100 topic parsing results
let subscriber = client.my_topic()
    .subscription()
    .with_cache(100)
    .subscribe().await?;

// Disable caching for memory-constrained environments
let subscriber = client.my_topic()
    .subscription()
    .with_cache(0)
    .subscribe().await?;

pub fn with_qos(self, qos: QoS) -> SubscriptionBuilder<MessageType, F>

Set QoS level

pub fn with_pattern( self, custom_pattern: impl TryInto>, ) -> Result<SubscriptionBuilder<MessageType, F>, MqttClientError>

where <impl TryInto<TopicPatternPath> as TryInto<TopicPatternPath>>::Error: Into<MqttClientError>,

Override the default topic pattern with a custom one.

This allows using a different MQTT topic pattern than the one defined in the #[mqtt_topic] macro, while ensuring the parameter structure remains compatible. The new pattern must have the same parameter names and types as the original.

Parameters

• custom_pattern - New topic pattern string (e.g., “sensors/{location}/data/{sensor_id}”)

Compatibility Requirements

• Same parameter names: {location}, {sensor_id}, etc.
• Same parameter order and count
• Parameter types must match the struct fields

Use Cases

• Environment-specific patterns: Different topic structures for dev/prod
• Multi-tenant systems: Adding tenant prefixes to topics
• Legacy compatibility: Supporting old topic formats
• A/B testing: Different topic patterns for the same data structure

Examples

// Original pattern from macro: "sensors/{location}/{sensor_id}"
// Override with environment-specific pattern:
let subscriber = client.sensor_topic()
    .subscription()
    .with_pattern("prod/sensors/{location}/device/{sensor_id}")?  // ✅ Compatible
    .subscribe().await?;

// Multi-tenant pattern:
let subscriber = client.sensor_topic()
    .subscription()
    .with_pattern("tenant_123/sensors/{location}/{sensor_id}")?  // ✅ Compatible
    .subscribe().await?;

// ❌ This would fail - different parameter names:
// .with_pattern("sensors/{room}/{device_id}")  // Error: parameter mismatch

Errors

Returns MqttClientError if:

• Pattern syntax is invalid
• Parameter names don’t match the original pattern
• Parameter count differs from the original pattern

pub async fn subscribe<PayloadType>( self, ) -> Result<MqttTopicSubscriber<MessageType, PayloadType, F>, MqttClientError>

where MessageType: FromMqttMessage<PayloadType, <F as MessageSerializer<PayloadType>>::DeserializeError>, PayloadType: Send + Sync + 'static, F: Default + Clone + Send + Sync + MessageSerializer<PayloadType>,

Subscribe using configured parameters

Trait Implementations

impl<MessageType, F> Clone for SubscriptionBuilder<MessageType, F>

where F: Clone,

fn clone(&self) -> SubscriptionBuilder<MessageType, F>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<MessageType, F> Debug for SubscriptionBuilder<MessageType, F>

where MessageType: Debug, F: Debug + Clone,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.