src/hotspot/share/utilities/waitBarrier.hpp

rev 53078 : 8214271: Fast primitive to wake many threads
Reviewed-by:
rev 53079 : [mq]: fix-sema

@@ -36,46 +36,43 @@
 #else
 typedef GenericWaitBarrier WaitBarrierDefault;
 #endif
 
 // Platform independent WaitBarrier API.
-// An armed WaitBarrier prevents threads from advancing until the
-// barrier is disarmed and the waiting threads woken. The barrier is
-// armed by setting a non-zero value - the tag.
-// When the WaitBarrier is created, a thread is designated the owner
-// and is the thread that should arm/disarm/wake the WaitBarrier. In
-// debug builds this is enforced.
+// An armed WaitBarrier prevents threads from advancing until the threads are
+// woken by calling wake(). The barrier is armed by setting a non-zero value
+// - the tag. When the WaitBarrier is created, a thread is designated the owner
+// and is the thread that should arm and wake the WaitBarrier. In debug builds
+// this is enforced.
 //
 // Expected Usage:
 //  - Arming thread:
 //     tag = ...;  // non-zero value
 //     barrier.arm(tag);
 //     <publish tag>
 //     <work>
-//     barrier.disarm();
 //     barrier.wake();
 //
 //    - After arm(tag) returns any thread calling wait(tag) will block.
-//    - After disarm() returns any subsequent calls to wait(tag) will not block.
-//    - After wake() returns all blocked threads are unblocked and eligible to
-//      execute again.
-//    - After calling disarm() and wake() the barrier is ready to be re-armed
-//      with a new tag. (may not be re-armed with last used tag)
+//    - Calling wake() guarantees any thread calling or called wait(tag) will
+//      return. Either they will see the WaitBarrier as disarmed or they will be
+//      unblocked and eligible to execute again when wake() returns.
+//    - After calling wake() the barrier is ready to be re-armed with a new tag.
+//      (may not be re-armed with last used tag)
 //
 //  - Waiting threads
 //     wait(tag); // don't execute following code unless 'safe'
 //     <work>
 //
 //    - A call to wait(tag) will block if the barrier is armed with the value
 //      'tag'; else it will return immediately.
 //    - A blocked thread is eligible to execute again once the barrier is
-//      disarmed and wake() has been called.
+//      disarmed when wake() has been called.
 //
 // It is a usage error to:
-//  - call wake on a barrier that is still armed
 //  - call arm on a barrier that is already armed
-//  - call disarm on a barrier that is not armed
+//  - call wake on a barrier that is not armed
 //  - arm with the same tag as last used
 // Usage errors are checked in debug builds but may be ignored otherwise.
 //
 // A primary goal of the WaitBarrier implementation is to wake all waiting
 // threads as fast, and as concurrently, as possible.

@@ -114,28 +111,20 @@
   assert(_owner == Thread::current(), "Not owner thread");
 #endif
     _impl.arm(barrier_tag);
   }
 
-  // Guarantees any thread calling wait() with any tag will not be blocked.
-  // Provides a trailing fence.
-  void disarm() {
-    assert(_owner == Thread::current(), "Not owner thread");
-    _impl.disarm();
-  }
-
   // Guarantees any thread called wait() will be awake when it returns.
   // Provides a trailing fence.
   void wake() {
     assert(_owner == Thread::current(), "Not owner thread");
     _impl.wake();
   }
 
-  // Guarantees not to return until disarm() is called,
+  // Guarantees not to return until wake() is called,
   // if called with currently armed tag (otherwise returns immediately).
   // Implementations must guarantee no spurious wakeups.
-  // Guarantees to return if disarm() and wake() is called.
   // Provides a trailing fence.
   void wait(int barrier_tag) {
     assert(_owner != Thread::current(), "Trying to wait with owner thread");
     _impl.wait(barrier_tag);
   }