From b65d83aacfea8adacebe7d2919c55bdedb475a8c Mon Sep 17 00:00:00 2001
From: George Karpenkov <george@metaworld.me>
Date: Mon, 13 Jun 2016 12:22:32 +0200
Subject: [PATCH] Java API: explain the phantom references mechanics in
 Javadoc.

---
 src/api/java/IDecRefQueue.java | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/src/api/java/IDecRefQueue.java b/src/api/java/IDecRefQueue.java
index 5a80adf5f..2deb9c0f9 100644
--- a/src/api/java/IDecRefQueue.java
+++ b/src/api/java/IDecRefQueue.java
@@ -24,8 +24,17 @@ import java.util.IdentityHashMap;
 import java.util.Map;
 
 /**
+ * A queue to handle management of native memory.
  *
- * @param <T>
+ * <p><b>Mechanics: </b>once an object is created, a metadata is stored for it in
+ * {@code referenceMap}, and a {@link PhantomReference} is created with a
+ * reference  to {@code referenceQueue}.
+ * Once the object becomes strongly unreachable, the phantom reference gets
+ * added by JVM to the {@code referenceQueue}.
+ * After each object creation, we iterate through the available objects in
+ * {@code referenceQueue} and decrement references for them.
+ *
+ * @param <T> Type of object stored in queue.
  */
 public abstract class IDecRefQueue<T extends Z3Object> {
     private final ReferenceQueue<T> referenceQueue = new ReferenceQueue<>();