FIXUP: Race condition in TarantoolClientImpl

Added comments and XXX notes.

Author: Totktonada

src/main/java/org/tarantool/TarantoolClientImpl.java

@@ -65,6 +65,21 @@ public class TarantoolClientImpl extends TarantoolBase<Future<?>> implements Tar
     protected Thread reader;
     protected Thread writer;
 
+    /**
+     * The condition variable to signal a reconnection is needed from reader /
+     * writer threads and waiting for that signal from the reconnection thread.
+     *
+     * The lock variable to access this condition.
+     *
+     * XXX: Maybe it is better to move signalling / waiting support to the
+     * state helper (or fsm when we'll reimplement it in that way). Maybe
+     * additional RECONNECTION_NEEDED state is required to distinguish whether
+     * we're in the reconnection state already or just want to reconnect (don't
+     * sure).
+     *
+     * @see #awaitReconnection()
+     * @see #trySignalForReconnection()
+     */
     protected final ReentrantLock connectorLock = new ReentrantLock();
     protected final Condition reconnectRequired = connectorLock.newCondition();
 
@@ -478,7 +493,7 @@ protected void stopIO() {
     }
 
     /**
-     * Blocks until a reconnection process can be carried on
+     * Blocks until a reconnection signal will be received.
      *
      * @see #trySignalForReconnection()
      */
@@ -496,7 +511,7 @@ private void awaitReconnection() {
     }
 
     /**
-     * Signals to the connector that reconnection process can be performed
+     * Signals to the connector that reconnection process can be performed.
      *
      * @see #awaitReconnection()
      */
@@ -675,28 +690,52 @@ protected int getState() {
             return state.get();
         }
 
+        /**
+         * Set CLOSED state, drop RECONNECT state.
+         */
         protected boolean close() {
             for (; ; ) {
                 int st = getState();
+
+                /* CLOSED is the terminal state. */
                 if ((st & CLOSED) == CLOSED)
                     return false;
+
+                /* Drop RECONNECT, set CLOSED.
+                 *
+                 * XXX: Should not we also drop other states? Or reimplement
+                 * this class as a finite state machine?
+                 */
                 if (compareAndSet(st, (st & ~RECONNECT) | CLOSED))
                     return true;
             }
         }
 
+        /**
+         * Move from a current state to a give one.
+         *
+         * Some moves are forbidden.
+         */
         protected boolean acquire(int mask) {
             for (; ; ) {
                 int currentState = getState();
+
+                /* CLOSED is the terminal state. */
                 if ((currentState & CLOSED) == CLOSED) {
                     return false;
                 }
+
+                /* Don't move to READING, WRITING or ALIVE from RECONNECT. */
                 if ((currentState & RECONNECT) > mask) {
                     return false;
                 }
+
+                /* Cannot move from a state to the same state. */
                 if ((currentState & mask) != 0) {
                     throw new IllegalStateException("State is already " + mask);
                 }
+
+                /* Set acquired state. */
                 if (compareAndSet(currentState, currentState | mask)) {
                     return true;
                 }