Trait SubscriptionControl 

pub trait SubscriptionControl: Send + Sync {
    // Required methods
    async fn subscribe(&self, topic: &str) -> ClientResult<()>;
    async fn subscribe_with_expression(
        &self,
        topic: &str,
        sub_expression: &str,
    ) -> ClientResult<()>;
    async fn subscribe_with_listener<MQL>(
        &self,
        topic: &str,
        sub_expression: &str,
        listener: MQL,
    ) -> ClientResult<()>
       where MQL: MessageQueueListener + 'static;
    async fn subscribe_with_selector(
        &self,
        topic: &str,
        selector: Option<MessageSelector>,
    ) -> ClientResult<()>;
    async fn unsubscribe(&self, topic: &str);
    async fn build_subscriptions_for_heartbeat(
        &self,
        sub_expression_map: &mut HashMap<String, MessageSelector>,
    ) -> ClientResult<()>;
    async fn subscriptions_for_heartbeat(&self) -> HashSet<SubscriptionData>;
    async fn message_model(&self) -> MessageModel;
    async fn set_message_model(&self, message_model: MessageModel);
    async fn consume_from_where(&self) -> ConsumeFromWhere;
    async fn set_consume_from_where(
        &self,
        consume_from_where: ConsumeFromWhere,
    ) -> ClientResult<()>;
    async fn consume_timestamp(&self) -> Option<CheetahString>;
    async fn set_consume_timestamp(
        &self,
        consume_timestamp: Option<CheetahString>,
    );
    async fn allocate_message_queue_strategy(
        &self,
    ) -> Arc<dyn AllocateMessageQueueStrategy + Send + Sync> ;
    async fn set_allocate_message_queue_strategy(
        &self,
        allocate_message_queue_strategy: Arc<dyn AllocateMessageQueueStrategy + Send + Sync>,
    );
    async fn message_queue_listener(&self) -> Option<ArcMessageQueueListener>;
    async fn set_message_queue_listener(
        &self,
        message_queue_listener: Option<ArcMessageQueueListener>,
    );
    async fn topic_metadata_check_interval_millis(&self) -> u64;
    async fn set_topic_metadata_check_interval_millis(
        &self,
        interval_millis: u64,
    );
    async fn is_connect_broker_by_user(&self) -> bool;
    async fn set_connect_broker_by_user(&self, connect_broker_by_user: bool);
    async fn default_broker_id(&self) -> u64;
    async fn set_default_broker_id(&self, broker_id: u64);
    async fn is_unit_mode(&self) -> bool;
    async fn set_unit_mode(&self, unit_mode: bool);
    async fn register_topic_message_queue_change_listener<TL>(
        &self,
        topic: &str,
        listener: TL,
    ) -> ClientResult<()>
       where TL: TopicMessageQueueChangeListener + 'static;
    async fn update_name_server_address(&self, name_server_address: &str);
}

A consumer that pulls messages from brokers on demand, providing explicit control over fetch timing, offset management, and queue assignment.

Unlike the push consumer, the caller drives message retrieval through poll or poll_with_timeout, and may manage offsets manually when auto-commit is disabled. Queue assignment can be controlled either by subscribing to topics (broker-side rebalance) or by calling assign directly (client-controlled assignment).

All methods are asynchronous and do not block the calling thread.

Required Methods

async fn subscribe(&self, topic: &str) -> ClientResult<()>

Subscribes to the specified topic using the default subscription expression.

This function does not block the calling thread.

Arguments

• topic - The name of the topic to subscribe to.

Errors

Returns an error if the topic name is invalid or if the subscription cannot be registered with the broker.

async fn subscribe_with_expression( &self, topic: &str, sub_expression: &str, ) -> ClientResult<()>

Subscribes to the specified topic with a tag-based or SQL-based filter expression.

This function does not block the calling thread.

Arguments

• topic - The name of the topic to subscribe to.
• sub_expression - A tag expression (e.g. "TagA || TagB") or SQL-92 predicate. Pass "*" to receive all messages.

Errors

Returns an error if the topic name is invalid, the expression cannot be parsed, or the subscription cannot be registered with the broker.

async fn subscribe_with_listener<MQL>( &self, topic: &str, sub_expression: &str, listener: MQL, ) -> ClientResult<()>

where MQL: MessageQueueListener + 'static,

Subscribes to the specified topic with a filter expression and a queue-change listener.

The listener is invoked whenever the set of assigned MessageQueues changes for this topic due to rebalance.

This function does not block the calling thread.

Arguments

• topic - The name of the topic to subscribe to.
• sub_expression - A tag expression or SQL-92 predicate. Pass "*" for all messages.
• listener - A MessageQueueListener notified on queue assignment changes.

Errors

Returns an error if the topic name is invalid, the expression cannot be parsed, or the subscription cannot be registered with the broker.

async fn subscribe_with_selector( &self, topic: &str, selector: Option<MessageSelector>, ) -> ClientResult<()>

Subscribes to the specified topic using a MessageSelector for server-side filtering.

This function does not block the calling thread.

Arguments

• topic - The name of the topic to subscribe to.
• selector - The filter selector. Pass None to receive all messages.

Errors

Returns an error if the topic name is invalid, the selector expression is rejected by the broker, or the subscription cannot be registered.

async fn unsubscribe(&self, topic: &str)

Removes the subscription for the specified topic.

Messages for this topic will no longer be fetched after the next rebalance cycle. This function does not block the calling thread.

Arguments

• topic - The name of the topic to unsubscribe from.

async fn build_subscriptions_for_heartbeat( &self, sub_expression_map: &mut HashMap<String, MessageSelector>, ) -> ClientResult<()>

Populates sub_expression_map with the filter selector for each subscribed topic, providing the subscription metadata required for heartbeat payloads.

This function does not block the calling thread.

Arguments

• sub_expression_map - Output map from topic name to its MessageSelector. Entries are inserted for every topic that has an active subscription with a selector.

Errors

Returns an error if the subscription metadata cannot be retrieved.

async fn subscriptions_for_heartbeat(&self) -> HashSet<SubscriptionData>

Returns the subscriptions currently advertised in heartbeat payloads.

async fn message_model(&self) -> MessageModel

Returns the configured message model.

async fn set_message_model(&self, message_model: MessageModel)

Sets the message model.

This mirrors Java DefaultLitePullConsumer.setMessageModel.

async fn consume_from_where(&self) -> ConsumeFromWhere

Returns where consumption starts when no offset exists.

async fn set_consume_from_where( &self, consume_from_where: ConsumeFromWhere, ) -> ClientResult<()>

Sets where consumption starts when no offset exists.

Errors

Returns an error for legacy ConsumeFromWhere values that Java LitePull rejects.

async fn consume_timestamp(&self) -> Option<CheetahString>

Returns the timestamp used by ConsumeFromWhere::ConsumeFromTimestamp.

async fn set_consume_timestamp(&self, consume_timestamp: Option<CheetahString>)

Sets the timestamp used by ConsumeFromWhere::ConsumeFromTimestamp.

async fn allocate_message_queue_strategy( &self, ) -> Arc<dyn AllocateMessageQueueStrategy + Send + Sync>

Returns the message queue allocation strategy used during rebalance.

async fn set_allocate_message_queue_strategy( &self, allocate_message_queue_strategy: Arc<dyn AllocateMessageQueueStrategy + Send + Sync>, )

Sets the message queue allocation strategy used during rebalance.

This mirrors Java DefaultLitePullConsumer.setAllocateMessageQueueStrategy.

async fn message_queue_listener(&self) -> Option<ArcMessageQueueListener>

Returns the listener notified when rebalance changes assigned message queues.

async fn set_message_queue_listener( &self, message_queue_listener: Option<ArcMessageQueueListener>, )

Sets the listener notified when rebalance changes assigned message queues.

Passing None clears the listener, matching Java’s nullable DefaultLitePullConsumer.setMessageQueueListener.

async fn topic_metadata_check_interval_millis(&self) -> u64

Returns the topic metadata check interval in milliseconds.

async fn set_topic_metadata_check_interval_millis(&self, interval_millis: u64)

Sets the topic metadata check interval in milliseconds.

Like Java, this applies directly to the stored configuration. If the metadata task is already scheduled, the existing task keeps its start-time interval.

async fn is_connect_broker_by_user(&self) -> bool

Returns whether pulls always use the configured default broker ID.

async fn set_connect_broker_by_user(&self, connect_broker_by_user: bool)

Sets whether pulls always use the configured default broker ID.

This mirrors Java DefaultLitePullConsumer.setConnectBrokerByUser.

async fn default_broker_id(&self) -> u64

Returns the broker ID used when user-controlled broker selection is enabled.

async fn set_default_broker_id(&self, broker_id: u64)

Sets the broker ID used when user-controlled broker selection is enabled.

This mirrors Java DefaultLitePullConsumer.setDefaultBrokerId.

async fn is_unit_mode(&self) -> bool

Returns whether the subscription group runs in unit mode.

async fn set_unit_mode(&self, unit_mode: bool)

Sets whether the subscription group runs in unit mode.

This mirrors Java DefaultLitePullConsumer.setUnitMode.

async fn register_topic_message_queue_change_listener<TL>( &self, topic: &str, listener: TL, ) -> ClientResult<()>

where TL: TopicMessageQueueChangeListener + 'static,

Registers a listener that is notified when the set of MessageQueues for a topic changes.

This function does not block the calling thread.

Arguments

• topic - The topic to monitor for queue changes.
• listener - A TopicMessageQueueChangeListener invoked when the queue set changes.

Errors

Returns an error if a listener is already registered for the given topic, or if the registration fails due to an internal error.

async fn update_name_server_address(&self, name_server_address: &str)

Updates the name server address used for topic route discovery.

This function does not block the calling thread.

Arguments

• name_server_address - The new semicolon-separated name server address list.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl SubscriptionControl for DefaultLitePullConsumer