1/*
2 * Copyright (c) 1997, 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_PARK_HPP
26#define SHARE_RUNTIME_PARK_HPP
27
28#include "utilities/debug.hpp"
29#include "utilities/globalDefinitions.hpp"
30/*
31 * Per-thread blocking support for JSR166. See the Java-level
32 * Documentation for rationale. Basically, park acts like wait, unpark
33 * like notify.
34 *
35 * 6271289 --
36 * To avoid errors where an os thread expires but the JavaThread still
37 * exists, Parkers are immortal (type-stable) and are recycled across
38 * new threads. This parallels the ParkEvent implementation.
39 * Because park-unpark allow spurious wakeups it is harmless if an
40 * unpark call unparks a new thread using the old Parker reference.
41 *
42 * In the future we'll want to think about eliminating Parker and using
43 * ParkEvent instead. There's considerable duplication between the two
44 * services.
45 *
46 */
47
48class Parker : public os::PlatformParker {
49private:
50 volatile int _counter ;
51 Parker * FreeNext ;
52 JavaThread * AssociatedWith ; // Current association
53
54public:
55 Parker() : PlatformParker() {
56 _counter = 0 ;
57 FreeNext = NULL ;
58 AssociatedWith = NULL ;
59 }
60protected:
61 ~Parker() { ShouldNotReachHere(); }
62public:
63 // For simplicity of interface with Java, all forms of park (indefinite,
64 // relative, and absolute) are multiplexed into one call.
65 void park(bool isAbsolute, jlong time);
66 void unpark();
67
68 // Lifecycle operators
69 static Parker * Allocate (JavaThread * t) ;
70 static void Release (Parker * e) ;
71private:
72 static Parker * volatile FreeList ;
73 static volatile int ListLock ;
74
75};
76
77/////////////////////////////////////////////////////////////
78//
79// ParkEvents are type-stable and immortal.
80//
81// Lifecycle: Once a ParkEvent is associated with a thread that ParkEvent remains
82// associated with the thread for the thread's entire lifetime - the relationship is
83// stable. A thread will be associated at most one ParkEvent. When the thread
84// expires, the ParkEvent moves to the EventFreeList. New threads attempt to allocate from
85// the EventFreeList before creating a new Event. Type-stability frees us from
86// worrying about stale Event or Thread references in the objectMonitor subsystem.
87// (A reference to ParkEvent is always valid, even though the event may no longer be associated
88// with the desired or expected thread. A key aspect of this design is that the callers of
89// park, unpark, etc must tolerate stale references and spurious wakeups).
90//
91// Only the "associated" thread can block (park) on the ParkEvent, although
92// any other thread can unpark a reachable parkevent. Park() is allowed to
93// return spuriously. In fact park-unpark a really just an optimization to
94// avoid unbounded spinning and surrender the CPU to be a polite system citizen.
95// A degenerate albeit "impolite" park-unpark implementation could simply return.
96// See http://blogs.sun.com/dave for more details.
97//
98// Eventually I'd like to eliminate Events and ObjectWaiters, both of which serve as
99// thread proxies, and simply make the THREAD structure type-stable and persistent.
100// Currently, we unpark events associated with threads, but ideally we'd just
101// unpark threads.
102//
103// The base-class, PlatformEvent, is platform-specific while the ParkEvent is
104// platform-independent. PlatformEvent provides park(), unpark(), etc., and
105// is abstract -- that is, a PlatformEvent should never be instantiated except
106// as part of a ParkEvent.
107// Equivalently we could have defined a platform-independent base-class that
108// exported Allocate(), Release(), etc. The platform-specific class would extend
109// that base-class, adding park(), unpark(), etc.
110//
111// A word of caution: The JVM uses 2 very similar constructs:
112// 1. ParkEvent are used for Java-level "monitor" synchronization.
113// 2. Parkers are used by JSR166-JUC park-unpark.
114//
115// We'll want to eventually merge these redundant facilities and use ParkEvent.
116
117
118class ParkEvent : public os::PlatformEvent {
119 private:
120 ParkEvent * FreeNext ;
121
122 // Current association
123 Thread * AssociatedWith ;
124
125 public:
126 // MCS-CLH list linkage and Native Mutex/Monitor
127 ParkEvent * volatile ListNext ;
128 volatile intptr_t OnList ;
129 volatile int TState ;
130 volatile int Notified ; // for native monitor construct
131
132 private:
133 static ParkEvent * volatile FreeList ;
134 static volatile int ListLock ;
135
136 // It's prudent to mark the dtor as "private"
137 // ensuring that it's not visible outside the package.
138 // Unfortunately gcc warns about such usage, so
139 // we revert to the less desirable "protected" visibility.
140 // The other compilers accept private dtors.
141
142 protected: // Ensure dtor is never invoked
143 ~ParkEvent() { guarantee (0, "invariant") ; }
144
145 ParkEvent() : PlatformEvent() {
146 AssociatedWith = NULL ;
147 FreeNext = NULL ;
148 ListNext = NULL ;
149 OnList = 0 ;
150 TState = 0 ;
151 Notified = 0 ;
152 }
153
154 // We use placement-new to force ParkEvent instances to be
155 // aligned on 256-byte address boundaries. This ensures that the least
156 // significant byte of a ParkEvent address is always 0.
157
158 void * operator new (size_t sz) throw();
159 void operator delete (void * a) ;
160
161 public:
162 static ParkEvent * Allocate (Thread * t) ;
163 static void Release (ParkEvent * e) ;
164} ;
165
166#endif // SHARE_RUNTIME_PARK_HPP
167