1 /*
  2  * Copyright (c) 1998, 2023, 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/atomic.hpp"
 30 
 31 #if defined(LINUX) || defined(AIX) || defined(BSD)
 32 # include "mutex_posix.hpp"
 33 #else
 34 # include OS_HEADER(mutex)
 35 #endif
 36 
 37 
 38 // A Mutex/Monitor is a simple wrapper around a native lock plus condition
 39 // variable that supports lock ownership tracking, lock ranking for deadlock
 40 // detection and coordinates with the safepoint protocol.
 41 
 42 // Locking is non-recursive: if you try to lock a mutex you already own then you
 43 // will get an assertion failure in a debug build (which should suffice to expose
 44 // usage bugs). If you call try_lock on a mutex you already own it will return false.
 45 // The underlying PlatformMutex may support recursive locking but this is not exposed
 46 // and we account for that possibility in try_lock.
 47 
 48 // A thread is not allowed to safepoint while holding a mutex whose rank
 49 // is nosafepoint or lower.
 50 
 51 class Mutex : public CHeapObj<mtSynchronizer> {
 52 
 53  public:
 54   // Special low level locks are given names and ranges avoid overlap.
 55   enum class Rank {
 56        event,
 57        service        = event          +   6,
 58        stackwatermark = service        +   3,
 59        tty            = stackwatermark +   3,
 60        oopstorage     = tty            +   3,
 61        nosafepoint    = oopstorage     +   6,
 62        safepoint      = nosafepoint    +  20
 63   };
 64 
 65   // want C++later "using enum" directives.
 66   static const Rank event          = Rank::event;
 67   static const Rank service        = Rank::service;
 68   static const Rank stackwatermark = Rank::stackwatermark;
 69   static const Rank tty            = Rank::tty;
 70   static const Rank oopstorage     = Rank::oopstorage;
 71   static const Rank nosafepoint    = Rank::nosafepoint;
 72   static const Rank safepoint      = Rank::safepoint;
 73 
 74   static void assert_no_overlap(Rank orig, Rank adjusted, int adjust);
 75 
 76   friend Rank operator-(Rank base, int adjust) {
 77     Rank result = static_cast<Rank>(static_cast<int>(base) - adjust);
 78     DEBUG_ONLY(assert_no_overlap(base, result, adjust));
 79     return result;
 80   }
 81 
 82   friend constexpr bool operator<(Rank lhs, Rank rhs) {
 83     return static_cast<int>(lhs) < static_cast<int>(rhs);
 84   }
 85 
 86   friend constexpr bool operator>(Rank lhs, Rank rhs)  { return rhs < lhs; }
 87   friend constexpr bool operator<=(Rank lhs, Rank rhs) { return !(lhs > rhs); }
 88   friend constexpr bool operator>=(Rank lhs, Rank rhs) { return !(lhs < rhs); }
 89 
 90  private:
 91   // The _owner field is only set by the current thread, either to itself after it has acquired
 92   // the low-level _lock, or to null before it has released the _lock. Accesses by any thread other
 93   // than the lock owner are inherently racy.
 94   Thread* volatile _owner;
 95   void raw_set_owner(Thread* new_owner) { Atomic::store(&_owner, new_owner); }
 96 
 97  protected:                              // Monitor-Mutex metadata
 98   PlatformMonitor _lock;                 // Native monitor implementation
 99   const char* _name;                     // Name of mutex/monitor
100   int _id;                               // ID for named mutexes
101 
102   // Debugging fields for naming, deadlock detection, etc. (some only used in debug mode)
103 #ifndef PRODUCT
104   bool    _allow_vm_block;
105 #endif
106 #ifdef ASSERT
107   Rank    _rank;                 // rank (to avoid/detect potential deadlocks)
108   Mutex*  _next;                 // Used by a Thread to link up owned locks
109   Thread* _last_owner;           // the last thread to own the lock
110   bool _skip_rank_check;         // read only by owner when doing rank checks
111 
112   static Mutex* get_least_ranked_lock(Mutex* locks);
113   Mutex* get_least_ranked_lock_besides_this(Mutex* locks);
114   bool skip_rank_check() {
115     assert(owned_by_self(), "only the owner should call this");
116     return _skip_rank_check;
117   }
118 
119  public:
120   Rank   rank() const          { return _rank; }
121   const char*  rank_name() const;
122   Mutex* next()  const         { return _next; }
123 #endif // ASSERT
124 
125  protected:
126   void set_owner_implementation(Thread* owner)                        NOT_DEBUG({ raw_set_owner(owner);});
127   void check_block_state       (Thread* thread)                       NOT_DEBUG_RETURN;
128   void check_safepoint_state   (Thread* thread)                       NOT_DEBUG_RETURN;
129   void check_no_safepoint_state(Thread* thread)                       NOT_DEBUG_RETURN;
130   void check_rank              (Thread* thread)                       NOT_DEBUG_RETURN;
131   void assert_owner            (Thread* expected)                     NOT_DEBUG_RETURN;
132 
133  public:
134   static const bool _allow_vm_block_flag        = true;
135 
136   // Locks can be acquired with or without a safepoint check. NonJavaThreads do not follow
137   // the safepoint protocol when acquiring locks.
138 
139   // Each lock can be acquired by only JavaThreads, only NonJavaThreads, or shared between
140   // Java and NonJavaThreads. When the lock is initialized with rank > nosafepoint,
141   // that means that whenever the lock is acquired by a JavaThread, it will verify that
142   // it is done with a safepoint check. In corollary, when the lock is initialized with
143   // rank <= nosafepoint, that means that whenever the lock is acquired by a JavaThread
144   // it will verify that it is done without a safepoint check.
145 
146   // TODO: Locks that are shared between JavaThreads and NonJavaThreads
147   // should never encounter a safepoint check while they are held, or else a
148   // deadlock can occur. We should check this by noting which
149   // locks are shared, and walk held locks during safepoint checking.
150 
151   enum class SafepointCheckFlag {
152     _safepoint_check_flag,
153     _no_safepoint_check_flag
154   };
155   // Bring the enumerator names into class scope.
156   static const SafepointCheckFlag _safepoint_check_flag =
157     SafepointCheckFlag::_safepoint_check_flag;
158   static const SafepointCheckFlag _no_safepoint_check_flag =
159     SafepointCheckFlag::_no_safepoint_check_flag;
160 
161  public:
162   Mutex(Rank rank, const char *name, bool allow_vm_block);
163 
164   Mutex(Rank rank, const char *name) :
165     Mutex(rank, name, rank > nosafepoint ? false : true) {}
166 
167   ~Mutex();
168 
169   void lock(); // prints out warning if VM thread blocks
170   void lock(Thread *thread); // overloaded with current thread
171   void unlock();
172   bool is_locked() const                     { return owner() != nullptr; }
173 
174   bool try_lock(); // Like lock(), but unblocking. It returns false instead
175  private:
176   void lock_contended(Thread *thread); // contended slow-path
177   bool try_lock_inner(bool do_rank_checks);
178  public:
179 
180   void release_for_safepoint();
181 
182   // Lock without safepoint check. Should ONLY be used by safepoint code and other code
183   // that is guaranteed not to block while running inside the VM.
184   void lock_without_safepoint_check();
185   void lock_without_safepoint_check(Thread* self);
186   // A thread should not call this if failure to acquire ownership will blocks its progress
187   bool try_lock_without_rank_check();
188 
189   // Current owner - note not MT-safe. Can only be used to guarantee that
190   // the current running thread owns the lock
191   Thread* owner() const         { return Atomic::load(&_owner); }
192   void set_owner(Thread* owner) { set_owner_implementation(owner); }
193   bool owned_by_self() const;
194 
195   const char *name() const                  { return _name; }
196 
197   int      id() const { return _id; }
198 //  void set_id(int id) { _id = id; }
199 
200   static const char* id2name(int id);
201 
202   void print_on_error(outputStream* st) const;
203   #ifndef PRODUCT
204     void print_on(outputStream* st) const;
205     void print() const;
206   #endif
207 };
208 
209 class Monitor : public Mutex {
210  public:
211   Monitor(Rank rank, const char *name, bool allow_vm_block)  :
212     Mutex(rank, name, allow_vm_block) {}
213 
214   Monitor(Rank rank, const char *name) :
215     Mutex(rank, name) {}
216   // default destructor
217 
218   // Wait until monitor is notified (or times out).
219   // Defaults are to make safepoint checks, wait time is forever (i.e.,
220   // zero). Returns true if wait times out; otherwise returns false.
221   bool wait(uint64_t timeout = 0);
222   bool wait_without_safepoint_check(uint64_t timeout = 0);
223   void notify();
224   void notify_all();
225 };
226 
227 
228 class PaddedMutex : public Mutex {
229   enum {
230     CACHE_LINE_PADDING = (int)DEFAULT_PADDING_SIZE - (int)sizeof(Mutex),
231     PADDING_LEN = CACHE_LINE_PADDING > 0 ? CACHE_LINE_PADDING : 1
232   };
233   char _padding[PADDING_LEN];
234 public:
235   PaddedMutex(Rank rank, const char *name, bool allow_vm_block) : Mutex(rank, name, allow_vm_block) {};
236   PaddedMutex(Rank rank, const char *name) : Mutex(rank, name) {};
237 };
238 
239 class PaddedMonitor : public Monitor {
240   enum {
241     CACHE_LINE_PADDING = (int)DEFAULT_PADDING_SIZE - (int)sizeof(Monitor),
242     PADDING_LEN = CACHE_LINE_PADDING > 0 ? CACHE_LINE_PADDING : 1
243   };
244   char _padding[PADDING_LEN];
245  public:
246   PaddedMonitor(Rank rank, const char *name, bool allow_vm_block) : Monitor(rank, name, allow_vm_block) {};
247   PaddedMonitor(Rank rank, const char *name) : Monitor(rank, name) {};
248 };
249 
250 #endif // SHARE_RUNTIME_MUTEX_HPP