This is an automated email from the ASF dual-hosted git repository.
eolivelli pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/bookkeeper.git
The following commit(s) were added to refs/heads/master by this push:
new 1942cac687 Add javadocs in ConcurrentLongHashMap and similar classes.
(#4068)
1942cac687 is described below
commit 1942cac687cfa0fbf1ededd9a2551108dd03a38b
Author: thetumbled <[email protected]>
AuthorDate: Tue Sep 12 14:05:54 2023 +0800
Add javadocs in ConcurrentLongHashMap and similar classes. (#4068)
---
.../util/collections/ConcurrentLongHashMap.java | 19 +++++++++++++++++++
.../util/collections/ConcurrentLongHashSet.java | 13 +++++++++++++
.../util/collections/ConcurrentLongLongHashMap.java | 15 +++++++++++++++
.../collections/ConcurrentLongLongPairHashMap.java | 20 ++++++++++++++++++++
.../util/collections/ConcurrentOpenHashMap.java | 20 ++++++++++++++++++++
.../util/collections/ConcurrentOpenHashSet.java | 18 ++++++++++++++++++
6 files changed, 105 insertions(+)
diff --git
a/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentLongHashMap.java
b/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentLongHashMap.java
index 7ff465f079..c95497a861 100644
---
a/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentLongHashMap.java
+++
b/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentLongHashMap.java
@@ -37,6 +37,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")
@@ -260,6 +273,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 (Section<V> s : sections) {
s.forEach(processor);
diff --git
a/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentLongHashSet.java
b/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentLongHashSet.java
index a66de9ed8b..78f99cef73 100644
---
a/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentLongHashSet.java
+++
b/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentLongHashSet.java
@@ -34,6 +34,19 @@ import java.util.concurrent.locks.StampedLock;
* no node allocations are required to store the values.
*
* <p>Items <strong>MUST</strong> 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 ConcurrentLongHashSet {
diff --git
a/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentLongLongHashMap.java
b/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentLongLongHashMap.java
index 25bcb4061a..1ad3b781f1 100644
---
a/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentLongLongHashMap.java
+++
b/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentLongLongHashMap.java
@@ -38,6 +38,21 @@ import java.util.function.LongPredicate;
* no node allocations are required to store the values.
*
* <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 ConcurrentLongLongHashMap {
diff --git
a/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentLongLongPairHashMap.java
b/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentLongLongPairHashMap.java
index 536eeb7448..c254393cdf 100644
---
a/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentLongLongPairHashMap.java
+++
b/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentLongLongPairHashMap.java
@@ -38,6 +38,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 {
@@ -279,6 +293,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/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentOpenHashMap.java
b/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentOpenHashMap.java
index cab3ce8ea3..cf258e0c14 100644
---
a/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentOpenHashMap.java
+++
b/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentOpenHashMap.java
@@ -36,6 +36,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")
@@ -243,6 +257,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 (Section<K, V> s : sections) {
s.forEach(processor);
diff --git
a/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentOpenHashSet.java
b/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentOpenHashSet.java
index a7f39173d3..ae50ab67b9 100644
---
a/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentOpenHashSet.java
+++
b/bookkeeper-server/src/main/java/org/apache/bookkeeper/util/collections/ConcurrentOpenHashSet.java
@@ -35,6 +35,18 @@ import java.util.function.Consumer;
* <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 (Section<V> s : sections) {
s.forEach(processor);
