src/hotspot/share/utilities/waitBarrier.hpp

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

*** 36,81 ****
  #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.
  //
  // 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)
  //
  //  - 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.
  //
  // 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
  //  - 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.
--- 36,78 ----
  #else
  typedef GenericWaitBarrier WaitBarrierDefault;
  #endif
  
  // Platform independent WaitBarrier API.
! // 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.wake();
  //
  //    - After arm(tag) returns any thread calling wait(tag) will block.
! //    - 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 when wake() has been called.
  //
  // It is a usage error to:
  //  - call arm on a barrier that is already 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,141 ****
    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,
    // 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);
    }
--- 111,130 ----
    assert(_owner == Thread::current(), "Not owner thread");
  #endif
      _impl.arm(barrier_tag);
    }
  
    // 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 wake() is called,
    // if called with currently armed tag (otherwise returns immediately).
    // Implementations must guarantee no spurious wakeups.
    // Provides a trailing fence.
    void wait(int barrier_tag) {
      assert(_owner != Thread::current(), "Trying to wait with owner thread");
      _impl.wait(barrier_tag);
    }