acorn@2233: /*
acorn@2233:  * Copyright (c) 1997, 2010, Oracle and/or its affiliates. All rights reserved.
acorn@2233:  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
acorn@2233:  *
acorn@2233:  * This code is free software; you can redistribute it and/or modify it
acorn@2233:  * under the terms of the GNU General Public License version 2 only, as
acorn@2233:  * published by the Free Software Foundation.
acorn@2233:  *
acorn@2233:  * This code is distributed in the hope that it will be useful, but WITHOUT
acorn@2233:  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
acorn@2233:  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
acorn@2233:  * version 2 for more details (a copy is included in the LICENSE file that
acorn@2233:  * accompanied this code).
acorn@2233:  *
acorn@2233:  * You should have received a copy of the GNU General Public License version
acorn@2233:  * 2 along with this work; if not, write to the Free Software Foundation,
acorn@2233:  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
acorn@2233:  *
acorn@2233:  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
acorn@2233:  * or visit www.oracle.com if you need additional information or have any
acorn@2233:  * questions.
acorn@2233:  *
acorn@2233:  */
stefank@2314: 
stefank@2314: #ifndef SHARE_VM_RUNTIME_PARK_HPP
stefank@2314: #define SHARE_VM_RUNTIME_PARK_HPP
stefank@2314: 
stefank@2314: #include "utilities/debug.hpp"
stefank@2314: #include "utilities/globalDefinitions.hpp"
acorn@2233: /*
acorn@2233:  * Per-thread blocking support for JSR166. See the Java-level
acorn@2233:  * Documentation for rationale. Basically, park acts like wait, unpark
acorn@2233:  * like notify.
acorn@2233:  *
acorn@2233:  * 6271289 --
acorn@2233:  * To avoid errors where an os thread expires but the JavaThread still
acorn@2233:  * exists, Parkers are immortal (type-stable) and are recycled across
acorn@2233:  * new threads.  This parallels the ParkEvent implementation.
acorn@2233:  * Because park-unpark allow spurious wakeups it is harmless if an
acorn@2233:  * unpark call unparks a new thread using the old Parker reference.
acorn@2233:  *
acorn@2233:  * In the future we'll want to think about eliminating Parker and using
acorn@2233:  * ParkEvent instead.  There's considerable duplication between the two
acorn@2233:  * services.
acorn@2233:  *
acorn@2233:  */
acorn@2233: 
acorn@2233: class Parker : public os::PlatformParker {
acorn@2233: private:
acorn@2233:   volatile int _counter ;
acorn@2233:   Parker * FreeNext ;
acorn@2233:   JavaThread * AssociatedWith ; // Current association
acorn@2233: 
acorn@2233: public:
acorn@2233:   Parker() : PlatformParker() {
acorn@2233:     _counter       = 0 ;
acorn@2233:     FreeNext       = NULL ;
acorn@2233:     AssociatedWith = NULL ;
acorn@2233:   }
acorn@2233: protected:
acorn@2233:   ~Parker() { ShouldNotReachHere(); }
acorn@2233: public:
acorn@2233:   // For simplicity of interface with Java, all forms of park (indefinite,
acorn@2233:   // relative, and absolute) are multiplexed into one call.
acorn@2233:   void park(bool isAbsolute, jlong time);
acorn@2233:   void unpark();
acorn@2233: 
acorn@2233:   // Lifecycle operators
acorn@2233:   static Parker * Allocate (JavaThread * t) ;
acorn@2233:   static void Release (Parker * e) ;
acorn@2233: private:
acorn@2233:   static Parker * volatile FreeList ;
acorn@2233:   static volatile int ListLock ;
acorn@2233: 
acorn@2233: };
acorn@2233: 
acorn@2233: /////////////////////////////////////////////////////////////
acorn@2233: //
acorn@2233: // ParkEvents are type-stable and immortal.
acorn@2233: //
acorn@2233: // Lifecycle: Once a ParkEvent is associated with a thread that ParkEvent remains
acorn@2233: // associated with the thread for the thread's entire lifetime - the relationship is
acorn@2233: // stable. A thread will be associated at most one ParkEvent.  When the thread
acorn@2233: // expires, the ParkEvent moves to the EventFreeList.  New threads attempt to allocate from
acorn@2233: // the EventFreeList before creating a new Event.  Type-stability frees us from
acorn@2233: // worrying about stale Event or Thread references in the objectMonitor subsystem.
acorn@2233: // (A reference to ParkEvent is always valid, even though the event may no longer be associated
acorn@2233: // with the desired or expected thread.  A key aspect of this design is that the callers of
acorn@2233: // park, unpark, etc must tolerate stale references and spurious wakeups).
acorn@2233: //
acorn@2233: // Only the "associated" thread can block (park) on the ParkEvent, although
acorn@2233: // any other thread can unpark a reachable parkevent.  Park() is allowed to
acorn@2233: // return spuriously.  In fact park-unpark a really just an optimization to
acorn@2233: // avoid unbounded spinning and surrender the CPU to be a polite system citizen.
acorn@2233: // A degenerate albeit "impolite" park-unpark implementation could simply return.
acorn@2233: // See http://blogs.sun.com/dave for more details.
acorn@2233: //
acorn@2233: // Eventually I'd like to eliminate Events and ObjectWaiters, both of which serve as
acorn@2233: // thread proxies, and simply make the THREAD structure type-stable and persistent.
acorn@2233: // Currently, we unpark events associated with threads, but ideally we'd just
acorn@2233: // unpark threads.
acorn@2233: //
acorn@2233: // The base-class, PlatformEvent, is platform-specific while the ParkEvent is
acorn@2233: // platform-independent.  PlatformEvent provides park(), unpark(), etc., and
acorn@2233: // is abstract -- that is, a PlatformEvent should never be instantiated except
acorn@2233: // as part of a ParkEvent.
acorn@2233: // Equivalently we could have defined a platform-independent base-class that
acorn@2233: // exported Allocate(), Release(), etc.  The platform-specific class would extend
acorn@2233: // that base-class, adding park(), unpark(), etc.
acorn@2233: //
acorn@2233: // A word of caution: The JVM uses 2 very similar constructs:
acorn@2233: // 1. ParkEvent are used for Java-level "monitor" synchronization.
acorn@2233: // 2. Parkers are used by JSR166-JUC park-unpark.
acorn@2233: //
acorn@2233: // We'll want to eventually merge these redundant facilities and use ParkEvent.
acorn@2233: 
acorn@2233: 
acorn@2233: class ParkEvent : public os::PlatformEvent {
acorn@2233:   private:
acorn@2233:     ParkEvent * FreeNext ;
acorn@2233: 
acorn@2233:     // Current association
acorn@2233:     Thread * AssociatedWith ;
acorn@2233:     intptr_t RawThreadIdentity ;        // LWPID etc
acorn@2233:     volatile int Incarnation ;
acorn@2233: 
acorn@2233:     // diagnostic : keep track of last thread to wake this thread.
acorn@2233:     // this is useful for construction of dependency graphs.
acorn@2233:     void * LastWaker ;
acorn@2233: 
acorn@2233:   public:
acorn@2233:     // MCS-CLH list linkage and Native Mutex/Monitor
acorn@2233:     ParkEvent * volatile ListNext ;
acorn@2233:     ParkEvent * volatile ListPrev ;
acorn@2233:     volatile intptr_t OnList ;
acorn@2233:     volatile int TState ;
acorn@2233:     volatile int Notified ;             // for native monitor construct
acorn@2233:     volatile int IsWaiting ;            // Enqueued on WaitSet
acorn@2233: 
acorn@2233: 
acorn@2233:   private:
acorn@2233:     static ParkEvent * volatile FreeList ;
acorn@2233:     static volatile int ListLock ;
acorn@2233: 
acorn@2233:     // It's prudent to mark the dtor as "private"
acorn@2233:     // ensuring that it's not visible outside the package.
acorn@2233:     // Unfortunately gcc warns about such usage, so
acorn@2233:     // we revert to the less desirable "protected" visibility.
acorn@2233:     // The other compilers accept private dtors.
acorn@2233: 
acorn@2233:   protected:        // Ensure dtor is never invoked
acorn@2233:     ~ParkEvent() { guarantee (0, "invariant") ; }
acorn@2233: 
acorn@2233:     ParkEvent() : PlatformEvent() {
acorn@2233:        AssociatedWith = NULL ;
acorn@2233:        FreeNext       = NULL ;
acorn@2233:        ListNext       = NULL ;
acorn@2233:        ListPrev       = NULL ;
acorn@2233:        OnList         = 0 ;
acorn@2233:        TState         = 0 ;
acorn@2233:        Notified       = 0 ;
acorn@2233:        IsWaiting      = 0 ;
acorn@2233:     }
acorn@2233: 
acorn@2233:     // We use placement-new to force ParkEvent instances to be
acorn@2233:     // aligned on 256-byte address boundaries.  This ensures that the least
acorn@2233:     // significant byte of a ParkEvent address is always 0.
acorn@2233: 
acorn@2233:     void * operator new (size_t sz) ;
acorn@2233:     void operator delete (void * a) ;
acorn@2233: 
acorn@2233:   public:
acorn@2233:     static ParkEvent * Allocate (Thread * t) ;
acorn@2233:     static void Release (ParkEvent * e) ;
acorn@2233: } ;
stefank@2314: 
stefank@2314: #endif // SHARE_VM_RUNTIME_PARK_HPP