1 /*
   2  * Copyright (c) 2001, 2002, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 /*
  27   File: Mutex.java
  28 
  29   Originally written by Doug Lea and released into the public domain.
  30   This may be used for any purposes whatsoever without acknowledgment.
  31   Thanks for the assistance and support of Sun Microsystems Labs,
  32   and everyone contributing, testing, and using this code.
  33 
  34   History:
  35   Date       Who                What
  36   11Jun1998  dl               Create public version
  37 */
  38 
  39 package com.sun.corba.se.impl.orbutil.concurrent;
  40 
  41 import com.sun.corba.se.impl.orbutil.ORBUtility ;
  42 
  43 /**
  44  * A simple reentrant mutual exclusion lock.
  45  * The lock is free upon construction. Each acquire gets the
  46  * lock, and each release frees it. Releasing a lock that
  47  * is already free has no effect.
  48  * <p>
  49  * This implementation makes no attempt to provide any fairness
  50  * or ordering guarantees. If you need them, consider using one of
  51  * the Semaphore implementations as a locking mechanism.
  52  * <p>
  53  * <b>Sample usage</b><br>
  54  * <p>
  55  * Mutex can be useful in constructions that cannot be
  56  * expressed using java synchronized blocks because the
  57  * acquire/release pairs do not occur in the same method or
  58  * code block. For example, you can use them for hand-over-hand
  59  * locking across the nodes of a linked list. This allows
  60  * extremely fine-grained locking,  and so increases
  61  * potential concurrency, at the cost of additional complexity and
  62  * overhead that would normally make this worthwhile only in cases of
  63  * extreme contention.
  64  * <pre>
  65  * class Node {
  66  *   Object item;
  67  *   Node next;
  68  *   Mutex lock = new Mutex(); // each node keeps its own lock
  69  *
  70  *   Node(Object x, Node n) { item = x; next = n; }
  71  * }
  72  *
  73  * class List {
  74  *    protected Node head; // pointer to first node of list
  75  *
  76  *    // Use plain java synchronization to protect head field.
  77  *    //  (We could instead use a Mutex here too but there is no
  78  *    //  reason to do so.)
  79  *    protected synchronized Node getHead() { return head; }
  80  *
  81  *    boolean search(Object x) throws InterruptedException {
  82  *      Node p = getHead();
  83  *      if (p == null) return false;
  84  *
  85  *      //  (This could be made more compact, but for clarity of illustration,
  86  *      //  all of the cases that can arise are handled separately.)
  87  *
  88  *      p.lock.acquire();              // Prime loop by acquiring first lock.
  89  *                                     //    (If the acquire fails due to
  90  *                                     //    interrupt, the method will throw
  91  *                                     //    InterruptedException now,
  92  *                                     //    so there is no need for any
  93  *                                     //    further cleanup.)
  94  *      for (;;) {
  95  *        if (x.equals(p.item)) {
  96  *          p.lock.release();          // release current before return
  97  *          return true;
  98  *        }
  99  *        else {
 100  *          Node nextp = p.next;
 101  *          if (nextp == null) {
 102  *            p.lock.release();       // release final lock that was held
 103  *            return false;
 104  *          }
 105  *          else {
 106  *            try {
 107  *              nextp.lock.acquire(); // get next lock before releasing current
 108  *            }
 109  *            catch (InterruptedException ex) {
 110  *              p.lock.release();    // also release current if acquire fails
 111  *              throw ex;
 112  *            }
 113  *            p.lock.release();      // release old lock now that new one held
 114  *            p = nextp;
 115  *          }
 116  *        }
 117  *      }
 118  *    }
 119  *
 120  *    synchronized void add(Object x) { // simple prepend
 121  *      // The use of `synchronized'  here protects only head field.
 122  *      // The method does not need to wait out other traversers
 123  *      // who have already made it past head.
 124  *
 125  *      head = new Node(x, head);
 126  *    }
 127  *
 128  *    // ...  other similar traversal and update methods ...
 129  * }
 130  * </pre>
 131  * <p>
 132  * <p>This version adds some debugging capability: it will detect
 133  * an attempt by a thread that does not hold the mutex to release it.
 134  * This version is reentrant: the same thread may acquire a mutex multiple
 135  * times, in which case it must release the mutex the same number of times
 136  * as it was acquired before another thread can acquire the mutex.
 137  * @see Semaphore
 138  * <p>[<a href="http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/intro.html"> Introduction to this package. </a>]
 139 **/
 140 
 141 import org.omg.CORBA.INTERNAL ;
 142 
 143 public class ReentrantMutex implements Sync  {
 144 
 145     /** The thread holding the lock **/
 146     protected Thread holder_ = null;
 147 
 148     /** number of times thread has acquired the lock **/
 149     protected int counter_ = 0 ;
 150 
 151     protected boolean debug = false ;
 152 
 153     public ReentrantMutex()
 154     {
 155         this( false ) ;
 156     }
 157 
 158     public ReentrantMutex( boolean debug )
 159     {
 160         this.debug = debug ;
 161     }
 162 
 163     public void acquire() throws InterruptedException {
 164         if (Thread.interrupted())
 165             throw new InterruptedException();
 166 
 167         synchronized(this) {
 168             try {
 169                 if (debug)
 170                     ORBUtility.dprintTrace( this,
 171                         "acquire enter: holder_=" +
 172                         ORBUtility.getThreadName(holder_) +
 173                         " counter_=" + counter_ ) ;
 174 
 175                 Thread thr = Thread.currentThread();
 176                 if (holder_ != thr) {
 177                     try {
 178                         while (counter_ > 0)
 179                             wait();
 180 
 181                         // This can't happen, but make sure anyway
 182                         if (counter_ != 0)
 183                             throw new INTERNAL(
 184                                 "counter not 0 when first acquiring mutex" ) ;
 185 
 186                         holder_ = thr;
 187                     } catch (InterruptedException ex) {
 188                         notify();
 189                         throw ex;
 190                     }
 191                 }
 192 
 193                 counter_ ++ ;
 194             } finally {
 195                 if (debug)
 196                     ORBUtility.dprintTrace( this, "acquire exit: holder_=" +
 197                     ORBUtility.getThreadName(holder_) + " counter_=" +
 198                     counter_ ) ;
 199             }
 200         }
 201     }
 202 
 203     void acquireAll( int count ) throws InterruptedException
 204     {
 205         if (Thread.interrupted())
 206             throw new InterruptedException();
 207 
 208         synchronized(this) {
 209             try {
 210                 if (debug)
 211                     ORBUtility.dprintTrace( this,
 212                         "acquireAll enter: count=" + count + " holder_=" +
 213                         ORBUtility.getThreadName(holder_) + " counter_=" +
 214                         counter_ ) ;
 215                 Thread thr = Thread.currentThread();
 216                 if (holder_ == thr) {
 217                     throw new INTERNAL(
 218                         "Cannot acquireAll while holding the mutex" ) ;
 219                 } else {
 220                     try {
 221                         while (counter_ > 0)
 222                             wait();
 223 
 224                         // This can't happen, but make sure anyway
 225                         if (counter_ != 0)
 226                             throw new INTERNAL(
 227                                 "counter not 0 when first acquiring mutex" ) ;
 228 
 229                         holder_ = thr;
 230                     } catch (InterruptedException ex) {
 231                         notify();
 232                         throw ex;
 233                     }
 234                 }
 235 
 236                 counter_ = count ;
 237             } finally {
 238                 if (debug)
 239                     ORBUtility.dprintTrace( this, "acquireAll exit: count=" +
 240                     count + " holder_=" + ORBUtility.getThreadName(holder_) +
 241                     " counter_=" + counter_ ) ;
 242             }
 243         }
 244     }
 245 
 246     public synchronized void release()
 247     {
 248         try {
 249             if (debug)
 250                 ORBUtility.dprintTrace( this, "release enter: " +
 251                     " holder_=" + ORBUtility.getThreadName(holder_) +
 252                     " counter_=" + counter_ ) ;
 253 
 254             Thread thr = Thread.currentThread();
 255             if (thr != holder_)
 256                 throw new INTERNAL(
 257                     "Attempt to release Mutex by thread not holding the Mutex" ) ;
 258             else
 259                 counter_ -- ;
 260 
 261             if (counter_ == 0) {
 262                 holder_ = null;
 263                 notify();
 264             }
 265         } finally {
 266             if (debug)
 267                 ORBUtility.dprintTrace( this, "release exit: " +
 268                     " holder_=" + ORBUtility.getThreadName(holder_) +
 269                     " counter_=" + counter_ ) ;
 270         }
 271     }
 272 
 273     synchronized int releaseAll()
 274     {
 275         try {
 276             if (debug)
 277                 ORBUtility.dprintTrace( this, "releaseAll enter: " +
 278                     " holder_=" + ORBUtility.getThreadName(holder_) +
 279                     " counter_=" + counter_ ) ;
 280 
 281             Thread thr = Thread.currentThread();
 282             if (thr != holder_)
 283                 throw new INTERNAL(
 284                     "Attempt to releaseAll Mutex by thread not holding the Mutex" ) ;
 285 
 286             int result = counter_ ;
 287             counter_ = 0 ;
 288             holder_ = null ;
 289             notify() ;
 290             return result ;
 291         } finally {
 292             if (debug)
 293                 ORBUtility.dprintTrace( this, "releaseAll exit: " +
 294                     " holder_=" + ORBUtility.getThreadName(holder_) +
 295                     " counter_=" + counter_ ) ;
 296         }
 297     }
 298 
 299     public boolean attempt(long msecs) throws InterruptedException {
 300         if (Thread.interrupted())
 301             throw new InterruptedException();
 302 
 303         synchronized(this) {
 304             try {
 305                 if (debug)
 306                     ORBUtility.dprintTrace( this, "attempt enter: msecs=" +
 307                         msecs + " holder_=" +
 308                         ORBUtility.getThreadName(holder_) +
 309                         " counter_=" + counter_ ) ;
 310 
 311                 Thread thr = Thread.currentThread() ;
 312 
 313                 if (counter_==0) {
 314                     holder_ = thr;
 315                     counter_ = 1 ;
 316                     return true;
 317                 } else if (msecs <= 0) {
 318                     return false;
 319                 } else {
 320                     long waitTime = msecs;
 321                     long start = System.currentTimeMillis();
 322                     try {
 323                         for (;;) {
 324                             wait(waitTime);
 325                             if (counter_==0) {
 326                                 holder_ = thr;
 327                                 counter_ = 1 ;
 328                                 return true;
 329                             } else {
 330                                 waitTime = msecs -
 331                                     (System.currentTimeMillis() - start);
 332 
 333                                 if (waitTime <= 0)
 334                                     return false;
 335                             }
 336                         }
 337                     } catch (InterruptedException ex) {
 338                         notify();
 339                         throw ex;
 340                     }
 341                 }
 342             } finally {
 343                 if (debug)
 344                     ORBUtility.dprintTrace( this, "attempt exit: " +
 345                         " holder_=" + ORBUtility.getThreadName(holder_) +
 346                         " counter_=" + counter_ ) ;
 347             }
 348         }
 349     }
 350 }