rocketmq_client_rust/consumer/
mq_push_consumer.rs

1// Copyright 2023 The RocketMQ Rust Authors
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15use cheetah_string::CheetahString;
16
17use crate::consumer::listener::message_listener_concurrently::MessageListenerConcurrently;
18use crate::consumer::listener::message_listener_orderly::MessageListenerOrderly;
19use crate::consumer::message_selector::MessageSelector;
20use crate::consumer::mq_consumer::MQConsumer;
21
22/// Defines the push-consumer interface for RocketMQ.
23///
24/// Implementations receive messages from brokers and dispatch them to the
25/// registered concurrent or orderly listener.
26#[allow(async_fn_in_trait)]
27pub trait MQPushConsumer: MQConsumer {
28    /// Asynchronously starts the consumer instance.
29    ///
30    /// This method does not block the calling thread.
31    ///
32    /// # Returns
33    ///
34    /// Returns `Ok(())` when startup succeeds, or an error when initialization
35    /// fails.
36    async fn start(&mut self) -> crate::ClientResult<()>;
37
38    /// Asynchronously shuts down the consumer instance.
39    ///
40    /// This method does not block the calling thread.
41    async fn shutdown(&mut self);
42
43    /// Registers a message listener for concurrent message consumption.
44    ///
45    /// # Parameters
46    ///
47    /// * `message_listener` - A closure that processes a batch of messages and returns a status.
48    ///
49    /// # Type Parameters
50    ///
51    /// * `ML` - The listener type.
52    fn register_message_listener_concurrently<ML>(&mut self, message_listener: ML)
53    where
54        ML: MessageListenerConcurrently + Send + Sync + 'static;
55
56    /// Registers a message listener for orderly message consumption.
57    ///
58    /// # Parameters
59    ///
60    /// * `message_listener` - A closure that processes a batch of messages and returns a status.
61    ///
62    /// # Type Parameters
63    ///
64    /// * `ML` - The listener type.
65    fn register_message_listener_orderly<ML>(&mut self, message_listener: ML)
66    where
67        ML: MessageListenerOrderly + Send + Sync + 'static;
68
69    /// Asynchronously subscribes to a topic with a subscription expression.
70    ///
71    /// This method does not block the calling thread.
72    ///
73    /// # Parameters
74    ///
75    /// * `topic` - The topic to subscribe to. Can be `&str`, `String`, or `CheetahString`.
76    /// * `sub_expression` - The subscription expression. Can be `&str`, `String`, or
77    ///   `CheetahString`.
78    ///
79    /// # Returns
80    ///
81    /// Returns `Ok(())` when the subscription is accepted, or an error when the
82    /// subscription request is invalid or cannot be applied.
83    ///
84    /// # Examples
85    ///
86    /// ```rust,ignore
87    /// // Using &str
88    /// consumer.subscribe("TopicTest", "*").await?;
89    ///
90    /// // Using String
91    /// let topic = String::from("TopicTest");
92    /// consumer.subscribe(topic, "*").await?;
93    ///
94    /// // Using CheetahString
95    /// let topic = CheetahString::from_slice("TopicTest");
96    /// consumer.subscribe(topic, "*").await?;
97    /// ```
98    async fn subscribe(
99        &mut self,
100        topic: impl Into<CheetahString>,
101        sub_expression: impl Into<CheetahString>,
102    ) -> crate::ClientResult<()>;
103
104    /// Asynchronously subscribes to a topic with an optional selector.
105    ///
106    /// This method does not block the calling thread.
107    ///
108    /// # Parameters
109    ///
110    /// * `topic` - The topic to subscribe to.
111    /// * `selector` - An optional message selector.
112    ///
113    /// # Returns
114    ///
115    /// Returns `Ok(())` when the subscription is accepted, or an error when the
116    /// selector is invalid or cannot be applied.
117    async fn subscribe_with_selector(
118        &mut self,
119        topic: &str,
120        selector: Option<MessageSelector>,
121    ) -> crate::ClientResult<()>;
122
123    /// Asynchronously unsubscribes from a topic.
124    ///
125    /// This method does not block the calling thread.
126    ///
127    /// # Parameters
128    ///
129    /// * `topic` - The topic to unsubscribe from.
130    async fn unsubscribe(&mut self, topic: &str);
131
132    /// Asynchronously suspends message consumption.
133    ///
134    /// This method does not block the calling thread.
135    async fn suspend(&self);
136
137    /// Asynchronously resumes message consumption.
138    ///
139    /// This method does not block the calling thread.
140    async fn resume(&self);
141
142    /// Updates the core size used by the concurrent consume worker pool.
143    ///
144    /// Orderly consumers and implementations without a resizable worker pool may
145    /// ignore this request.
146    fn update_core_pool_size(&self, _core_pool_size: usize) -> crate::ClientResult<()> {
147        Err(crate::mq_client_err!(
148            "updateCorePoolSize is not supported by this MQPushConsumer implementation"
149        ))
150    }
151}
rocketmq_client_rust/consumer/mq_push_consumer.rs

rocketmq_client_rust/consumer/
mq_push_consumer.rs
