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 31b4cb7cbf152..26948a2f4bfaa 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 @@ *
  • Open hash map with linear probing, no node allocations to store the values * * + * WARN: method forEach do not guarantee thread safety, nor do the keys and values method. + *
    + * 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. + * + *
    + * 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 */ @SuppressWarnings("unchecked") @@ -237,6 +250,12 @@ public void clear() { } } + /** + * Iterate over all the entries in the map and apply the processor function to each of them. + *

    + * Warning: Do Not Guarantee Thread-Safety. + * @param processor the processor to apply to each entry + */ public void forEach(EntryProcessor 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 c0ccad9b73d5b..57a024185e0d3 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 @@ * no node allocations are required to store the keys and values, and no boxing is required. * *

    Keys MUST be >= 0. + *
    + * WARN: method forEach do not guarantee thread safety, nor do the keys, values and asMap method. + *
    + * 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. + * + *
    + * 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 void clear() { } } + /** + * Iterate over all the entries in the map and apply the processor function to each of them. + *

    + * Warning: Do Not Guarantee Thread-Safety. + * @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 2a1090503857c..02e53da19bb6f 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 @@ * no node allocations are required to store the keys and values, and no boxing is required. * *

    Values MUST be >= 0. + *
    + * WARN: method forEach do not guarantee thread safety, nor does the items method. + *
    + * 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. + * + *
    + * 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 void clear() { } } + /** + * Iterate over all the elements in the set and apply the provided function. + *

    + * Warning: Do Not Guarantee Thread-Safety. + * @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 int removeIf(LongPairPredicate filter) { } /** - * @return a new list of all keys (makes a copy) + * @return a new set of all keys (makes a copy) */ public Set items() { Set 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 ea2e01768ac7e..ec4721a8153ea 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 @@ *

    Provides similar methods as a {@code ConcurrentMap} but since it's an open hash map with linear probing, * no node allocations are required to store the values. * + *
    + * WARN: method forEach do not guarantee thread safety, nor do the keys and values method. + *
    + * 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. + * + *
    + * 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 */ @SuppressWarnings("unchecked") @@ -272,6 +286,12 @@ public void clear() { } } + /** + * Iterate over all the entries in the map and apply the processor function to each of them. + *

    + * Warning: Do Not Guarantee Thread-Safety. + * @param processor the function to apply to each entry + */ public void forEach(BiConsumer 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 cc8bc07b43095..5ba5e78a3dfb5 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 @@ *

    Provides similar methods as a {@code ConcurrentMap} but since it's an open hash map with linear probing, * no node allocations are required to store the values. * + *
    + * WARN: method forEach do not guarantee thread safety, nor does the values method. + *
    + * 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. + * + *
    + * 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 */ @SuppressWarnings("unchecked") @@ -216,6 +228,12 @@ public void clear() { } } + /** + * Iterate over all the elements in the set and apply the provided function. + *

    + * Warning: Do Not Guarantee Thread-Safety. + * @param processor the function to apply to each element + */ public void forEach(Consumer processor) { for (int i = 0; i < sections.length; i++) { sections[i].forEach(processor);