From 064e12a57b958d74f6a7441e1d07e5ed0cef7c2e Mon Sep 17 00:00:00 2001
From: catbref <misc-github@talk2dom.com>
Date: Wed, 2 Dec 2020 13:16:18 +0000
Subject: [PATCH] Improve documentation regarding deadlock in EventBus

---
 src/main/java/org/qortal/event/EventBus.java | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/src/main/java/org/qortal/event/EventBus.java b/src/main/java/org/qortal/event/EventBus.java
index 63c80143..09496d11 100644
--- a/src/main/java/org/qortal/event/EventBus.java
+++ b/src/main/java/org/qortal/event/EventBus.java
@@ -22,18 +22,25 @@ public enum EventBus {
 
 	/**
 	 * <b>WARNING:</b> before calling this method,
-	 * make sure repository holds no locks, e.g. by calling
+	 * make sure current thread's repository session
+	 * holds no locks, e.g. by calling
+	 * <tt>repository.saveChanges()</tt> or
 	 * <tt>repository.discardChanges()</tt>.
 	 * <p>
 	 * This is because event listeners might open a new
 	 * repository session which will deadlock HSQLDB
 	 * if it tries to CHECKPOINT.
 	 * <p>
-	 * The HSQLDB deadlock occurs because the caller's
-	 * repository session blocks the CHECKPOINT until
-	 * their transaction is closed, yet event listeners
-	 * new sessions are blocked until CHECKPOINT is
-	 * completed, hence deadlock.
+	 * The HSQLDB deadlock path is:
+	 * <ul>
+	 * <li>write-log <tt>blockchain.log</tt> has grown past CHECKPOINT threshold (50MB)</li>
+	 * <li>alternatively, another thread has explicitly requested CHECKPOINT</li>
+	 * <li>HSQLDB won't begin CHECKPOINT until all pending (SQL) transactions are committed or rolled back</li>
+	 * <li>Same thread calls <tt>EventBus.INSTANCE.notify()</tt> <i>before</i> (SQL) transaction closed</li>
+	 * <li>EventBus listener (same thread) requests a new repository session via <tt>RepositoryManager.getRepository()</tt></li>
+	 * <li>New repository sessions are blocked pending completion of CHECKPOINT</li>
+	 * <li>Caller is blocked so never has a chance to close (SQL) transaction - hence deadlock</li>
+	 * </ul>
 	 */
 	public void notify(Event event) {
 		List<Listener> clonedListeners;