/*

 * Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 *

 */

#ifndef SHARE_UTILITIES_SINGLEWRITERSYNCHRONIZER_HPP

#define SHARE_UTILITIES_SINGLEWRITERSYNCHRONIZER_HPP

#include "memory/allocation.hpp"

#include "runtime/atomic.hpp"

#include "runtime/semaphore.hpp"

#include "utilities/globalDefinitions.hpp"

#include "utilities/macros.hpp"

// Synchronization primitive inspired by RCU.

//

// Any number of threads may enter critical sections associated with a

// synchronizer object.  One (at a time) other thread may wait for the

// completion of all critical sections for the synchronizer object

// that were extent when the wait was initiated.  Usage is that there

// is some state that can be accessed either before or after some

// change.  An accessing thread performs the access within a critical

// section.  A writer thread performs the state change, and then waits

// for critical sections to complete, thereby ensuring there are no

// threads in a critical section that might have seen the old state.

//

// Generally, GlobalCounter should be used instead of this class, as

// GlobalCounter has measurably better performance and doesn't have

// the single writer at a time restriction.  Use this only in

// situations where GlobalCounter won't work for some reason, such as

// nesting.  But note that nesting often indicates other problems, and

// may risk deadlock.

class SingleWriterSynchronizer {

  volatile uint _enter;

  volatile uint _exit[2];

  volatile uint _waiting_for;

  Semaphore _wakeup;

  DEBUG_ONLY(volatile uint _writers;)

  // Noncopyable.

  SingleWriterSynchronizer(const SingleWriterSynchronizer&);

  SingleWriterSynchronizer& operator=(const SingleWriterSynchronizer&);

public:

  SingleWriterSynchronizer();

  // Enter a critical section for this synchronizer.  Entering a

  // critical section never blocks.  While in a critical section, a

  // thread should avoid blocking, or even take a long time.  In

  // particular, a thread must never safepoint while in a critical

  // section.

  // Precondition: The current thread must not already be in a

  // critical section for this synchronizer.

  inline uint enter();

  // Exit a critical section for this synchronizer.

  // Precondition: enter_value must be the result of the corresponding

  // enter() for the critical section.

  inline void exit(uint enter_value);

  // Wait until all threads currently in a critical section for this

  // synchronizer have exited their critical section.  Threads that

  // enter a critical section after the synchronization has started

  // are not considered in the wait.

  // Precondition: No other thread may be synchronizing on this

  // synchronizer.

  void synchronize();

  // RAII class for managing enter/exit pairs.

  class CriticalSection;

};

inline uint SingleWriterSynchronizer::enter() {

  return Atomic::add(2u, &_enter);

}

inline void SingleWriterSynchronizer::exit(uint enter_value) {

  uint exit_value = Atomic::add(2u, &_exit[enter_value & 1]);

  // If this exit completes a synchronize request, wakeup possibly

  // waiting synchronizer.  Read of _waiting_for must follow the _exit

  // update.

  if (exit_value == _waiting_for) {

    _wakeup.signal();

  }

}

class SingleWriterSynchronizer::CriticalSection : public StackObj {

  SingleWriterSynchronizer* _synchronizer;

  uint _enter_value;

public:

  // Enter synchronizer's critical section.

  explicit CriticalSection(SingleWriterSynchronizer* synchronizer) :

    _synchronizer(synchronizer),

    _enter_value(synchronizer->enter())

  {}

  // Exit synchronizer's critical section.

  ~CriticalSection() {

    _synchronizer->exit(_enter_value);

  }

};

#endif // SHARE_UTILITIES_SINGLEWRITERSYNCHRONIZER_HPP