This is an automated email from the ASF dual-hosted git repository.
xyz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new e9d1d99354b [improve] [doc] Add doc for customized util class (#21110)
e9d1d99354b is described below
commit e9d1d99354bf6bee19e6d962dadb61f65dc81d5c
Author: thetumbled <[email protected]>
AuthorDate: Sat Sep 9 17:52:56 2023 +0800
[improve] [doc] Add doc for customized util class (#21110)
---
.../util/collections/ConcurrentLongHashMap.java | 19 +++++++++++++++++++
.../collections/ConcurrentLongLongPairHashMap.java | 20 ++++++++++++++++++++
.../util/collections/ConcurrentLongPairSet.java | 20 +++++++++++++++++++-
.../util/collections/ConcurrentOpenHashMap.java | 20 ++++++++++++++++++++
.../util/collections/ConcurrentOpenHashSet.java | 18 ++++++++++++++++++
5 files changed, 96 insertions(+), 1 deletion(-)
diff --git
a/pulsar-common/src/main/java/org/apache/pulsar/common/util/collections/ConcurrentLongHashMap.java
b/pulsar-common/src/main/java/org/apache/pulsar/common/util/collections/ConcurrentLongHashMap.java
index 31b4cb7cbf1..26948a2f4bf 100644
---
a/pulsar-common/src/main/java/org/apache/pulsar/common/util/collections/ConcurrentLongHashMap.java
+++
b/pulsar-common/src/main/java/org/apache/pulsar/common/util/collections/ConcurrentLongHashMap.java
@@ -36,6 +36,19 @@ import java.util.function.LongFunction;
* <li>Open hash map with linear probing, no node allocations to store the
values
* </ol>
*
+ * <b>WARN: method forEach do not guarantee thread safety, nor do the keys and
values method.</b>
+ * <br>
+ * The forEach method is specifically designed for single-threaded usage. When
iterating over a map
+ * with concurrent writes, it becomes possible for new values to be either
observed or not observed.
+ * There is no guarantee that if we write value1 and value2, and are able to
see value2, then we will also see value1.
+ * In some cases, it is even possible to encounter two mappings with the same
key,
+ * leading the keys method to return a List containing two identical keys.
+ *
+ * <br>
+ * It is crucial to understand that the results obtained from aggregate status
methods such as keys and values
+ * are typically reliable only when the map is not undergoing concurrent
updates from other threads.
+ * When concurrent updates are involved, the results of these methods reflect
transient states
+ * that may be suitable for monitoring or estimation purposes, but not for
program control.
* @param <V>
*/
@SuppressWarnings("unchecked")
@@ -237,6 +250,12 @@ public class ConcurrentLongHashMap<V> {
}
}
+ /**
+ * Iterate over all the entries in the map and apply the processor
function to each of them.
+ * <p>
+ * <b>Warning: Do Not Guarantee Thread-Safety.</b>
+ * @param processor the processor to apply to each entry
+ */
public void forEach(EntryProcessor<V> processor) {
for (int i = 0; i < sections.length; i++) {
sections[i].forEach(processor);
diff --git
a/pulsar-common/src/main/java/org/apache/pulsar/common/util/collections/ConcurrentLongLongPairHashMap.java
b/pulsar-common/src/main/java/org/apache/pulsar/common/util/collections/ConcurrentLongLongPairHashMap.java
index c0ccad9b73d..57a024185e0 100644
---
a/pulsar-common/src/main/java/org/apache/pulsar/common/util/collections/ConcurrentLongLongPairHashMap.java
+++
b/pulsar-common/src/main/java/org/apache/pulsar/common/util/collections/ConcurrentLongLongPairHashMap.java
@@ -36,6 +36,20 @@ import java.util.concurrent.locks.StampedLock;
* no node allocations are required to store the keys and values, and no
boxing is required.
*
* <p>Keys <strong>MUST</strong> be >= 0.
+ * <br>
+ * <b>WARN: method forEach do not guarantee thread safety, nor do the keys,
values and asMap method.</b>
+ * <br>
+ * The forEach method is specifically designed for single-threaded usage. When
iterating over a map
+ * with concurrent writes, it becomes possible for new values to be either
observed or not observed.
+ * There is no guarantee that if we write value1 and value2, and are able to
see value2, then we will also see value1.
+ * In some cases, it is even possible to encounter two mappings with the same
key,
+ * leading the keys method to return a List containing two identical keys.
+ *
+ * <br>
+ * It is crucial to understand that the results obtained from aggregate status
methods such as keys, values, and asMap
+ * are typically reliable only when the map is not undergoing concurrent
updates from other threads.
+ * When concurrent updates are involved, the results of these methods reflect
transient states
+ * that may be suitable for monitoring or estimation purposes, but not for
program control.
*/
public class ConcurrentLongLongPairHashMap {
@@ -254,6 +268,12 @@ public class ConcurrentLongLongPairHashMap {
}
}
+ /**
+ * Iterate over all the entries in the map and apply the processor
function to each of them.
+ * <p>
+ * <b>Warning: Do Not Guarantee Thread-Safety.</b>
+ * @param processor the processor to process the elements.
+ */
public void forEach(BiConsumerLongPair processor) {
for (Section s : sections) {
s.forEach(processor);
diff --git
a/pulsar-common/src/main/java/org/apache/pulsar/common/util/collections/ConcurrentLongPairSet.java
b/pulsar-common/src/main/java/org/apache/pulsar/common/util/collections/ConcurrentLongPairSet.java
index 2a109050385..02e53da19bb 100644
---
a/pulsar-common/src/main/java/org/apache/pulsar/common/util/collections/ConcurrentLongPairSet.java
+++
b/pulsar-common/src/main/java/org/apache/pulsar/common/util/collections/ConcurrentLongPairSet.java
@@ -34,6 +34,18 @@ import java.util.concurrent.locks.StampedLock;
* no node allocations are required to store the keys and values, and no
boxing is required.
*
* <p>Values <b>MUST</b> be >= 0.
+ * <br>
+ * <b>WARN: method forEach do not guarantee thread safety, nor does the items
method.</b>
+ * <br>
+ * The forEach method is specifically designed for single-threaded usage. When
iterating over a set
+ * with concurrent writes, it becomes possible for new values to be either
observed or not observed.
+ * There is no guarantee that if we write value1 and value2, and are able to
see value2, then we will also see value1.
+ *
+ * <br>
+ * It is crucial to understand that the results obtained from aggregate status
methods such as items
+ * are typically reliable only when the map is not undergoing concurrent
updates from other threads.
+ * When concurrent updates are involved, the results of these methods reflect
transient states
+ * that may be suitable for monitoring or estimation purposes, but not for
program control.
*/
public class ConcurrentLongPairSet implements LongPairSet {
@@ -237,6 +249,12 @@ public class ConcurrentLongPairSet implements LongPairSet {
}
}
+ /**
+ * Iterate over all the elements in the set and apply the provided
function.
+ * <p>
+ * <b>Warning: Do Not Guarantee Thread-Safety.</b>
+ * @param processor the processor to process the elements
+ */
public void forEach(LongPairConsumer processor) {
for (int i = 0; i < sections.length; i++) {
sections[i].forEach(processor);
@@ -260,7 +278,7 @@ public class ConcurrentLongPairSet implements LongPairSet {
}
/**
- * @return a new list of all keys (makes a copy)
+ * @return a new set of all keys (makes a copy)
*/
public Set<LongPair> items() {
Set<LongPair> items = new HashSet<>();
diff --git
a/pulsar-common/src/main/java/org/apache/pulsar/common/util/collections/ConcurrentOpenHashMap.java
b/pulsar-common/src/main/java/org/apache/pulsar/common/util/collections/ConcurrentOpenHashMap.java
index ea2e01768ac..ec4721a8153 100644
---
a/pulsar-common/src/main/java/org/apache/pulsar/common/util/collections/ConcurrentOpenHashMap.java
+++
b/pulsar-common/src/main/java/org/apache/pulsar/common/util/collections/ConcurrentOpenHashMap.java
@@ -35,6 +35,20 @@ import java.util.function.Function;
* <p>Provides similar methods as a {@code ConcurrentMap<K,V>} but since it's
an open hash map with linear probing,
* no node allocations are required to store the values.
*
+ * <br>
+ * <b>WARN: method forEach do not guarantee thread safety, nor do the keys and
values method.</b>
+ * <br>
+ * The forEach method is specifically designed for single-threaded usage. When
iterating over a map
+ * with concurrent writes, it becomes possible for new values to be either
observed or not observed.
+ * There is no guarantee that if we write value1 and value2, and are able to
see value2, then we will also see value1.
+ * In some cases, it is even possible to encounter two mappings with the same
key,
+ * leading the keys method to return a List containing two identical keys.
+ *
+ * <br>
+ * It is crucial to understand that the results obtained from aggregate status
methods such as keys and values
+ * are typically reliable only when the map is not undergoing concurrent
updates from other threads.
+ * When concurrent updates are involved, the results of these methods reflect
transient states
+ * that may be suitable for monitoring or estimation purposes, but not for
program control.
* @param <V>
*/
@SuppressWarnings("unchecked")
@@ -272,6 +286,12 @@ public class ConcurrentOpenHashMap<K, V> {
}
}
+ /**
+ * Iterate over all the entries in the map and apply the processor
function to each of them.
+ * <p>
+ * <b>Warning: Do Not Guarantee Thread-Safety.</b>
+ * @param processor the function to apply to each entry
+ */
public void forEach(BiConsumer<? super K, ? super V> processor) {
for (int i = 0; i < sections.length; i++) {
sections[i].forEach(processor);
diff --git
a/pulsar-common/src/main/java/org/apache/pulsar/common/util/collections/ConcurrentOpenHashSet.java
b/pulsar-common/src/main/java/org/apache/pulsar/common/util/collections/ConcurrentOpenHashSet.java
index cc8bc07b430..5ba5e78a3df 100644
---
a/pulsar-common/src/main/java/org/apache/pulsar/common/util/collections/ConcurrentOpenHashSet.java
+++
b/pulsar-common/src/main/java/org/apache/pulsar/common/util/collections/ConcurrentOpenHashSet.java
@@ -35,6 +35,18 @@ import java.util.function.Predicate;
* <p>Provides similar methods as a {@code ConcurrentMap<K,V>} but since it's
an open hash map with linear probing,
* no node allocations are required to store the values.
*
+ * <br>
+ * <b>WARN: method forEach do not guarantee thread safety, nor does the values
method.</b>
+ * <br>
+ * The forEach method is specifically designed for single-threaded usage. When
iterating over a set
+ * with concurrent writes, it becomes possible for new values to be either
observed or not observed.
+ * There is no guarantee that if we write value1 and value2, and are able to
see value2, then we will also see value1.
+ *
+ * <br>
+ * It is crucial to understand that the results obtained from aggregate status
methods such as values
+ * are typically reliable only when the map is not undergoing concurrent
updates from other threads.
+ * When concurrent updates are involved, the results of these methods reflect
transient states
+ * that may be suitable for monitoring or estimation purposes, but not for
program control.
* @param <V>
*/
@SuppressWarnings("unchecked")
@@ -216,6 +228,12 @@ public class ConcurrentOpenHashSet<V> {
}
}
+ /**
+ * Iterate over all the elements in the set and apply the provided
function.
+ * <p>
+ * <b>Warning: Do Not Guarantee Thread-Safety.</b>
+ * @param processor the function to apply to each element
+ */
public void forEach(Consumer<? super V> processor) {
for (int i = 0; i < sections.length; i++) {
sections[i].forEach(processor);
