1 /*
   2  * Copyright (c) 1998, 2019, 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.
   8  *
   9  * This code is distributed in the hope that it will be useful, but WITHOUT
  10  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  11  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  12  * version 2 for more details (a copy is included in the LICENSE file that
  13  * accompanied this code).
  14  *
  15  * You should have received a copy of the GNU General Public License version
  16  * 2 along with this work; if not, write to the Free Software Foundation,
  17  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  18  *
  19  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  20  * or visit www.oracle.com if you need additional information or have any
  21  * questions.
  22  *
  23  */
  24 
  25 #ifndef SHARE_RUNTIME_MUTEX_HPP
  26 #define SHARE_RUNTIME_MUTEX_HPP
  27 
  28 #include "memory/allocation.hpp"
  29 #include "runtime/os.hpp"
  30 
  31 // A Mutex/Monitor is a simple wrapper around a native lock plus condition
  32 // variable that supports lock ownership tracking, lock ranking for deadlock
  33 // detection and coordinates with the safepoint protocol.
  34 
  35 // The default length of monitor name was originally chosen to be 64 to avoid
  36 // false sharing. Now, PaddedMonitor is available for this purpose.
  37 // TODO: Check if _name[MONITOR_NAME_LEN] should better get replaced by const char*.
  38 static const int MONITOR_NAME_LEN = 64;
  39 
  40 class Monitor : public CHeapObj<mtSynchronizer> {
  41 
  42  public:
  43   // A special lock: Is a lock where you are guaranteed not to block while you are
  44   // holding it, i.e., no vm operation can happen, taking other (blocking) locks, etc.
  45   // The rank 'access' is similar to 'special' and has the same restrictions on usage.
  46   // It is reserved for locks that may be required in order to perform memory accesses
  47   // that require special barriers, e.g. SATB GC barriers, that in turn uses locks.
  48   // The rank 'tty' is also similar to 'special' and has the same restrictions.
  49   // It is reserved for the tty_lock.
  50   // Since memory accesses should be able to be performed pretty much anywhere
  51   // in the code, that requires locks required for performing accesses being
  52   // inherently a bit more special than even locks of the 'special' rank.
  53   // NOTE: It is critical that the rank 'special' be the lowest (earliest)
  54   // (except for "event" and "access") for the deadlock detection to work correctly.
  55   // The rank native was only for use in Mutexes created by JVM_RawMonitorCreate,
  56   // which being external to the VM are not subject to deadlock detection,
  57   // however it has now been used by other locks that don't fit into the
  58   // deadlock detection scheme.
  59   // While at a safepoint no mutexes of rank safepoint are held by any thread.
  60   // The rank named "leaf" is probably historical (and should
  61   // be changed) -- mutexes of this rank aren't really leaf mutexes
  62   // at all.
  63   enum lock_types {
  64        event,
  65        access         = event          +   1,
  66        tty            = access         +   2,
  67        special        = tty            +   1,
  68        suspend_resume = special        +   1,
  69        oopstorage     = suspend_resume +   2,
  70        leaf           = oopstorage     +   2,
  71        safepoint      = leaf           +  10,
  72        barrier        = safepoint      +   1,
  73        nonleaf        = barrier        +   1,
  74        max_nonleaf    = nonleaf        + 900,
  75        native         = max_nonleaf    +   1
  76   };
  77 
  78  protected:                              // Monitor-Mutex metadata
  79   Thread * volatile _owner;              // The owner of the lock
  80   os::PlatformMonitor _lock;             // Native monitor implementation
  81   char _name[MONITOR_NAME_LEN];          // Name of mutex/monitor
  82 
  83   // Debugging fields for naming, deadlock detection, etc. (some only used in debug mode)
  84 #ifndef PRODUCT
  85   bool      _allow_vm_block;
  86   DEBUG_ONLY(int _rank;)                 // rank (to avoid/detect potential deadlocks)
  87   DEBUG_ONLY(Monitor * _next;)           // Used by a Thread to link up owned locks
  88   DEBUG_ONLY(Thread* _last_owner;)       // the last thread to own the lock
  89   DEBUG_ONLY(static bool contains(Monitor * locks, Monitor * lock);)
  90   DEBUG_ONLY(static Monitor * get_least_ranked_lock(Monitor * locks);)
  91   DEBUG_ONLY(Monitor * get_least_ranked_lock_besides_this(Monitor * locks);)
  92 #endif
  93 
  94   void set_owner_implementation(Thread* owner)                        PRODUCT_RETURN;
  95   void check_prelock_state     (Thread* thread, bool safepoint_check) PRODUCT_RETURN;
  96   void check_block_state       (Thread* thread)                       PRODUCT_RETURN;
  97   void check_safepoint_state   (Thread* thread, bool safepoint_check) NOT_DEBUG_RETURN;
  98   void assert_owner            (Thread* expected)                     NOT_DEBUG_RETURN;
  99   void assert_wait_lock_state  (Thread* self)                         NOT_DEBUG_RETURN;
 100 
 101  public:
 102   enum {
 103     _allow_vm_block_flag        = true,
 104     _as_suspend_equivalent_flag = true
 105   };
 106 
 107   // Locks can be acquired with or without a safepoint check. NonJavaThreads do not follow
 108   // the safepoint protocol when acquiring locks.
 109 
 110   // Each lock can be acquired by only JavaThreads, only NonJavaThreads, or shared between
 111   // Java and NonJavaThreads. When the lock is initialized with _safepoint_check_always,
 112   // that means that whenever the lock is acquired by a JavaThread, it will verify that
 113   // it is done with a safepoint check. In corollary, when the lock is initialized with
 114   // _safepoint_check_never, that means that whenever the lock is acquired by a JavaThread
 115   // it will verify that it is done without a safepoint check.
 116 
 117 
 118   // There are a couple of existing locks that will sometimes have a safepoint check and
 119   // sometimes not when acquired by a JavaThread, but these locks are set up carefully
 120   // to avoid deadlocks. TODO: Fix these locks and remove _safepoint_check_sometimes.
 121 
 122   // TODO: Locks that are shared between JavaThreads and NonJavaThreads
 123   // should never encounter a safepoint check while they are held, or else a
 124   // deadlock can occur. We should check this by noting which
 125   // locks are shared, and walk held locks during safepoint checking.
 126 
 127   enum SafepointCheckFlag {
 128     _safepoint_check_flag,
 129     _no_safepoint_check_flag
 130   };
 131 
 132   enum SafepointCheckRequired {
 133     _safepoint_check_never,       // Monitors with this value will cause errors
 134                                   // when acquired by a JavaThread with a safepoint check.
 135     _safepoint_check_sometimes,   // A couple of special locks are acquired by JavaThreads sometimes
 136                                   // with and sometimes without safepoint checks. These
 137                                   // locks will not produce errors when locked.
 138     _safepoint_check_always       // Monitors with this value will cause errors
 139                                   // when acquired by a JavaThread without a safepoint check.
 140   };
 141 
 142   NOT_PRODUCT(SafepointCheckRequired _safepoint_check_required;)
 143 
 144  public:
 145   Monitor(int rank, const char *name, bool allow_vm_block = false,
 146           SafepointCheckRequired safepoint_check_required = _safepoint_check_always);
 147   ~Monitor();
 148 
 149   // Wait until monitor is notified (or times out).
 150   // Defaults are to make safepoint checks, wait time is forever (i.e.,
 151   // zero), and not a suspend-equivalent condition. Returns true if wait
 152   // times out; otherwise returns false.
 153   bool wait(long timeout = 0,
 154             bool as_suspend_equivalent = !_as_suspend_equivalent_flag);
 155   bool wait_without_safepoint_check(long timeout = 0);
 156   void notify();
 157   void notify_all();
 158 
 159 
 160   void lock(); // prints out warning if VM thread blocks
 161   void lock(Thread *thread); // overloaded with current thread
 162   void unlock();
 163   bool is_locked() const                     { return _owner != NULL; }
 164 
 165   bool try_lock(); // Like lock(), but unblocking. It returns false instead
 166 
 167   void release_for_safepoint();
 168 
 169   // Lock without safepoint check. Should ONLY be used by safepoint code and other code
 170   // that is guaranteed not to block while running inside the VM.
 171   void lock_without_safepoint_check();
 172   void lock_without_safepoint_check(Thread* self);
 173 
 174   // Current owner - not not MT-safe. Can only be used to guarantee that
 175   // the current running thread owns the lock
 176   Thread* owner() const         { return _owner; }
 177   bool owned_by_self() const;
 178 
 179   const char *name() const                  { return _name; }
 180 
 181   void print_on_error(outputStream* st) const;
 182 
 183   #ifndef PRODUCT
 184     void print_on(outputStream* st) const;
 185     void print() const                      { print_on(::tty); }
 186     DEBUG_ONLY(int    rank() const          { return _rank; })
 187     bool   allow_vm_block()                 { return _allow_vm_block; }
 188 
 189     DEBUG_ONLY(Monitor *next()  const         { return _next; })
 190     DEBUG_ONLY(void   set_next(Monitor *next) { _next = next; })
 191   #endif
 192 
 193   void set_owner(Thread* owner) {
 194   #ifndef PRODUCT
 195     set_owner_implementation(owner);
 196     DEBUG_ONLY(void verify_Monitor(Thread* thr);)
 197   #else
 198     _owner = owner;
 199   #endif
 200   }
 201 
 202 };
 203 
 204 class PaddedMonitor : public Monitor {
 205   enum {
 206     CACHE_LINE_PADDING = (int)DEFAULT_CACHE_LINE_SIZE - (int)sizeof(Monitor),
 207     PADDING_LEN = CACHE_LINE_PADDING > 0 ? CACHE_LINE_PADDING : 1
 208   };
 209   char _padding[PADDING_LEN];
 210  public:
 211   PaddedMonitor(int rank, const char *name, bool allow_vm_block = false,
 212                SafepointCheckRequired safepoint_check_required = _safepoint_check_always) :
 213     Monitor(rank, name, allow_vm_block, safepoint_check_required) {};
 214 };
 215 
 216 // Normally we'd expect Monitor to extend Mutex in the sense that a monitor
 217 // constructed from pthreads primitives might extend a mutex by adding
 218 // a condvar and some extra metadata.  In fact this was the case until J2SE7.
 219 //
 220 // Currently, however, the base object is a monitor.  Monitor contains all the
 221 // logic for wait(), notify(), etc.   Mutex extends monitor and restricts the
 222 // visibility of wait(), notify(), and notify_all().
 223 //
 224 // Another viable alternative would have been to have Monitor extend Mutex and
 225 // implement all the normal mutex and wait()-notify() logic in Mutex base class.
 226 // The wait()-notify() facility would be exposed via special protected member functions
 227 // (e.g., _Wait() and _Notify()) in Mutex.  Monitor would extend Mutex and expose wait()
 228 // as a call to _Wait().  That is, the public wait() would be a wrapper for the protected
 229 // _Wait().
 230 //
 231 // An even better alternative is to simply eliminate Mutex:: and use Monitor:: instead.
 232 // After all, monitors are sufficient for Java-level synchronization.   At one point in time
 233 // there may have been some benefit to having distinct mutexes and monitors, but that time
 234 // has passed.
 235 //
 236 
 237 class Mutex : public Monitor {      // degenerate Monitor

 238  public:
 239    Mutex(int rank, const char *name, bool allow_vm_block = false,
 240          SafepointCheckRequired safepoint_check_required = _safepoint_check_always);
 241    // default destructor
 242  private:







 243    void notify();
 244    void notify_all();
 245    bool wait(long timeout, bool as_suspend_equivalent);
 246    bool wait_without_safepoint_check(long timeout);
 247 };
 248 

 249 class PaddedMutex : public Mutex {
 250   enum {
 251     CACHE_LINE_PADDING = (int)DEFAULT_CACHE_LINE_SIZE - (int)sizeof(Mutex),
 252     PADDING_LEN = CACHE_LINE_PADDING > 0 ? CACHE_LINE_PADDING : 1
 253   };
 254   char _padding[PADDING_LEN];
 255 public:
 256   PaddedMutex(int rank, const char *name, bool allow_vm_block = false,
 257               SafepointCheckRequired safepoint_check_required = _safepoint_check_always) :
 258     Mutex(rank, name, allow_vm_block, safepoint_check_required) {};












 259 };
 260 
 261 #endif // SHARE_RUNTIME_MUTEX_HPP
--- EOF ---