Skip to main content

confluent_kafka/producer/
round_robin_partitioner.rs

1// Copyright 2025 Confluent Inc.
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
15//! Round-robin partitioner.
16//!
17//! Translated from `org.apache.kafka.clients.producer.RoundRobinPartitioner`.
18
19use std::sync::atomic::{AtomicI32, Ordering};
20
21use dashmap::DashMap;
22
23use crate::common::Cluster;
24use crate::common::utils::Utils;
25use crate::producer::Partitioner;
26
27/// The "Round-Robin" partitioner.
28///
29/// This partitioning strategy can be used when user wants to distribute the
30/// writes to all partitions equally. This is the behaviour regardless of record
31/// key hash.
32///
33//
34// The record key (if present) is ignored: the partitioner cycles through the
35// topic's partitions in order, choosing only from partitions that currently
36// have a leader (available partitions), so a leaderless partition is skipped.
37//
38// A single instance is shared by the producer across tasks, so the per-topic
39// counter is an `AtomicI32` inside a concurrent map, the direct translation of
40// Java's `ConcurrentMap<String, AtomicInteger>`.
41#[derive(Debug, Default)]
42#[doc(alias = "org.apache.kafka.clients.producer.RoundRobinPartitioner")]
43pub struct RoundRobinPartitioner {
44    /// Per-topic round-robin counter. Java: `topicCounterMap`.
45    topic_counter_map: DashMap<String, AtomicI32>,
46}
47
48impl RoundRobinPartitioner {
49    /// Creates a new `RoundRobinPartitioner`.
50    #[doc(alias = "org.apache.kafka.clients.producer.RoundRobinPartitioner#RoundRobinPartitioner")]
51    pub fn new() -> Self {
52        Self::default()
53    }
54
55    /// Returns the next counter value for `topic`, incrementing it.
56    ///
57    /// Java's `nextValue` uses `computeIfAbsent` + `AtomicInteger.getAndIncrement()`.
58    /// Here a `get` fast path avoids taking a shard write-lock once the topic's
59    /// counter exists (the steady state, every record after the first); only the
60    /// first record for a topic takes the `entry` slow path that allocates the
61    /// key. Like Java's `getAndIncrement`, `fetch_add` wraps on overflow, and the
62    /// negative wrap is folded back by [`to_positive`] at the call site.
63    #[doc(alias = "org.apache.kafka.clients.producer.RoundRobinPartitioner#nextValue")]
64    fn next_value(&self, topic: &str) -> i32 {
65        if let Some(counter) = self.topic_counter_map.get(topic) {
66            return counter.fetch_add(1, Ordering::Relaxed);
67        }
68        self.topic_counter_map
69            .entry(topic.to_string())
70            .or_insert_with(|| AtomicI32::new(0))
71            .fetch_add(1, Ordering::Relaxed)
72    }
73}
74
75impl<K, V> Partitioner<K, V> for RoundRobinPartitioner {
76    // Compute the partition for the given record.
77    //
78    // If there are available (leader-having) partitions for the topic, the next
79    // counter value picks one of them round-robin; otherwise it falls back to
80    // the full partition count. The key/value are ignored.
81    //
82    // Panics: when the topic has no partitions at all in `cluster`, the
83    // fallback `Utils::to_positive(next) % 0` divides by zero; Java's identical
84    // code throws `ArithmeticException` there. This is unreachable from
85    // `KafkaProducer`: `wait_on_metadata` guarantees the topic has partitions
86    // before `partition` is called. Per CLAUDE.md ยง12.1 a division by zero may
87    // panic, so the `i32` return type is preserved rather than made fallible.
88    fn partition(
89        &self,
90        topic: &str,
91        _key: Option<&K>,
92        _key_bytes: Option<&[u8]>,
93        _value: Option<&V>,
94        _value_bytes: Option<&[u8]>,
95        cluster: &Cluster,
96    ) -> i32 {
97        let next_value = self.next_value(topic);
98        let available_partitions = cluster.available_partitions_for_topic(topic);
99        if !available_partitions.is_empty() {
100            let part = Utils::to_positive(next_value) as usize % available_partitions.len();
101            available_partitions[part].partition()
102        } else {
103            let num_partitions = cluster.partitions_for_topic(topic).len();
104            Utils::to_positive(next_value) % num_partitions as i32
105        }
106    }
107}
108
109#[cfg(test)]
110mod tests {
111    use super::*;
112    use crate::common::{Node, PartitionInfo};
113    use std::collections::{HashMap, HashSet};
114
115    /// The three nodes used by the Java test's static `NODES` array.
116    fn nodes() -> [Node; 3] {
117        [
118            Node::new(0, "localhost".to_string(), 99),
119            Node::new(1, "localhost".to_string(), 100),
120            Node::new(2, "localhost".to_string(), 101),
121        ]
122    }
123
124    /// Translated from `RoundRobinPartitionerTest.testRoundRobinWithUnavailablePartitions`.
125    #[test]
126    #[doc(
127        alias = "org.apache.kafka.clients.producer.RoundRobinPartitionerTest#testRoundRobinWithUnavailablePartitions"
128    )]
129    fn test_round_robin_with_unavailable_partitions() {
130        let n = nodes();
131        // Intentionally make the partition list not in partition order to test the
132        // edge cases.
133        let partitions = vec![
134            PartitionInfo::new("test".to_string(), 1, None, n.to_vec(), n.to_vec()),
135            PartitionInfo::new("test".to_string(), 2, Some(n[1].clone()), n.to_vec(), n.to_vec()),
136            PartitionInfo::new("test".to_string(), 0, Some(n[0].clone()), n.to_vec(), n.to_vec()),
137        ];
138        // When there are some unavailable partitions, we want to make sure that (1)
139        // we always pick an available partition, and (2) the available partitions
140        // are selected in a round robin way.
141        let mut count_for_part0 = 0;
142        let mut count_for_part2 = 0;
143        let concrete = RoundRobinPartitioner::new();
144        let partitioner: &dyn Partitioner<String, String> = &concrete;
145        let cluster = Cluster::with_invalid_topics_controller_topic_ids(
146            Some("clusterId".to_string()),
147            vec![n[0].clone(), n[1].clone(), n[2].clone()],
148            partitions,
149            HashSet::new(),
150            HashSet::new(),
151            HashSet::new(),
152            None,
153            HashMap::new(),
154        );
155        for _ in 1..=100 {
156            let part = partitioner.partition("test", None, None, None, None, &cluster);
157            assert!(
158                part == 0 || part == 2,
159                "We should never choose a leader-less node in round robin"
160            );
161            if part == 0 {
162                count_for_part0 += 1;
163            } else {
164                count_for_part2 += 1;
165            }
166        }
167        assert_eq!(
168            count_for_part0, count_for_part2,
169            "The distribution between two available partitions should be even"
170        );
171    }
172
173    /// Translated from `RoundRobinPartitionerTest.testRoundRobinWithKeyBytes`.
174    #[test]
175    #[doc(alias = "org.apache.kafka.clients.producer.RoundRobinPartitionerTest#testRoundRobinWithKeyBytes")]
176    fn test_round_robin_with_key_bytes() {
177        let topic_a = "topicA";
178        let topic_b = "topicB";
179        let n = nodes();
180
181        let all_partitions = vec![
182            PartitionInfo::new(topic_a.to_string(), 0, Some(n[0].clone()), n.to_vec(), n.to_vec()),
183            PartitionInfo::new(topic_a.to_string(), 1, Some(n[1].clone()), n.to_vec(), n.to_vec()),
184            PartitionInfo::new(topic_a.to_string(), 2, Some(n[2].clone()), n.to_vec(), n.to_vec()),
185            PartitionInfo::new(topic_b.to_string(), 0, Some(n[0].clone()), n.to_vec(), n.to_vec()),
186        ];
187        let test_cluster = Cluster::with_invalid_topics_controller_topic_ids(
188            Some("clusterId".to_string()),
189            vec![n[0].clone(), n[1].clone(), n[2].clone()],
190            all_partitions,
191            HashSet::new(),
192            HashSet::new(),
193            HashSet::new(),
194            None,
195            HashMap::new(),
196        );
197
198        let mut partition_count: HashMap<i32, i32> = HashMap::new();
199
200        let key_bytes: &[u8] = b"key";
201        let concrete = RoundRobinPartitioner::new();
202        let partitioner: &dyn Partitioner<String, String> = &concrete;
203        for i in 0..30 {
204            let partition = partitioner.partition(topic_a, None, Some(key_bytes), None, None, &test_cluster);
205            *partition_count.entry(partition).or_insert(0) += 1;
206
207            if i % 5 == 0 {
208                partitioner.partition(topic_b, None, Some(key_bytes), None, None, &test_cluster);
209            }
210        }
211
212        assert_eq!(10, partition_count[&0]);
213        assert_eq!(10, partition_count[&1]);
214        assert_eq!(10, partition_count[&2]);
215    }
216}