YugabyteDB (2.13.0.0-b42, bfc6a6643e7399ac8a0e81d06a3ee6d6571b33ab)

// Copyright (c) 2012 The Chromium Authors. All rights reserved.

// Use of this source code is governed by a BSD-style license that can be

// found in the LICENSE file.

//

// The following only applies to changes made to this file as part of YugaByte development.

//

// Portions Copyright (c) YugaByte, Inc.

//

// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except

// in compliance with the License.  You may obtain a copy of the License at

//

// http://www.apache.org/licenses/LICENSE-2.0

//

// Unless required by applicable law or agreed to in writing, software distributed under the License

// is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express

// or implied.  See the License for the specific language governing permissions and limitations

// under the License.

//

#ifndef YB_GUTIL_THREADING_THREAD_COLLISION_WARNER_H

#define YB_GUTIL_THREADING_THREAD_COLLISION_WARNER_H

#include "yb/gutil/atomicops.h"

#include "yb/gutil/macros.h"

#include "yb/gutil/port.h"

#ifndef BASE_EXPORT

#define BASE_EXPORT

#endif

// A helper class alongside macros to be used to verify assumptions about thread

// safety of a class.

//

// Example: Queue implementation non thread-safe but still usable if clients

//          are synchronized somehow.

//

//          In this case the macro DFAKE_SCOPED_LOCK has to be

//          used, it checks that if a thread is inside the push/pop then

//          noone else is still inside the pop/push

//

// class NonThreadSafeQueue {

//  public:

//   ...

//   void push(int) { DFAKE_SCOPED_LOCK(push_pop_); ... }

//   int pop() { DFAKE_SCOPED_LOCK(push_pop_); ... }

//   ...

//  private:

//   DFAKE_MUTEX(push_pop_);

// };

//

//

// Example: Queue implementation non thread-safe but still usable if clients

//          are synchronized somehow, it calls a method to "protect" from

//          a "protected" method

//

//          In this case the macro DFAKE_SCOPED_RECURSIVE_LOCK

//          has to be used, it checks that if a thread is inside the push/pop

//          then noone else is still inside the pop/push

//

// class NonThreadSafeQueue {

//  public:

//   void push(int) {

//     DFAKE_SCOPED_LOCK(push_pop_);

//     ...

//   }

//   int pop() {

//     DFAKE_SCOPED_RECURSIVE_LOCK(push_pop_);

//     bar();

//     ...

//   }

//   void bar() { DFAKE_SCOPED_RECURSIVE_LOCK(push_pop_); ... }

//   ...

//  private:

//   DFAKE_MUTEX(push_pop_);

// };

//

//

// Example: Queue implementation not usable even if clients are synchronized,

//          so only one thread in the class life cycle can use the two members

//          push/pop.

//

//          In this case the macro DFAKE_SCOPED_LOCK_THREAD_LOCKED pins the

//          specified

//          critical section the first time a thread enters push or pop, from

//          that time on only that thread is allowed to execute push or pop.

//

// class NonThreadSafeQueue {

//  public:

//   ...

//   void push(int) { DFAKE_SCOPED_LOCK_THREAD_LOCKED(push_pop_); ... }

//   int pop() { DFAKE_SCOPED_LOCK_THREAD_LOCKED(push_pop_); ... }

//   ...

//  private:

//   DFAKE_MUTEX(push_pop_);

// };

//

//

// Example: Class that has to be contructed/destroyed on same thread, it has

//          a "shareable" method (with external synchronization) and a not

//          shareable method (even with external synchronization).

//

//          In this case 3 Critical sections have to be defined

//

// class ExoticClass {

//  public:

//   ExoticClass() { DFAKE_SCOPED_LOCK_THREAD_LOCKED(ctor_dtor_); ... }

//   ~ExoticClass() { DFAKE_SCOPED_LOCK_THREAD_LOCKED(ctor_dtor_); ... }

//

//   void Shareable() { DFAKE_SCOPED_LOCK(shareable_section_); ... }

//   void NotShareable() { DFAKE_SCOPED_LOCK_THREAD_LOCKED(ctor_dtor_); ... }

//   ...

//  private:

//   DFAKE_MUTEX(ctor_dtor_);

//   DFAKE_MUTEX(shareable_section_);

// };

#if !defined(NDEBUG)

// Defines a class member that acts like a mutex. It is used only as a

// verification tool.

#define DFAKE_MUTEX(obj) \

     mutable base::ThreadCollisionWarner obj

// Asserts the call is never called simultaneously in two threads. Used at

// member function scope.

#define DFAKE_SCOPED_LOCK(obj) \

     base::ThreadCollisionWarner::ScopedCheck s_check_##obj(&obj)

// Asserts the call is never called simultaneously in two threads. Used at

// member function scope. Same as DFAKE_SCOPED_LOCK but allows recursive locks.

#define DFAKE_SCOPED_RECURSIVE_LOCK(obj) \

     base::ThreadCollisionWarner::ScopedRecursiveCheck sr_check_##obj(&obj)

// Asserts the code is always executed in the same thread.

#define DFAKE_SCOPED_LOCK_THREAD_LOCKED(obj) \

     base::ThreadCollisionWarner::Check check_##obj(&obj)

#else

#define DFAKE_MUTEX(obj) typedef void InternalFakeMutexType##obj

#define DFAKE_SCOPED_LOCK(obj) ((void)0)

#define DFAKE_SCOPED_RECURSIVE_LOCK(obj) ((void)0)

#define DFAKE_SCOPED_LOCK_THREAD_LOCKED(obj) ((void)0)

#endif

namespace base {

// The class ThreadCollisionWarner uses an Asserter to notify the collision

// AsserterBase is the interfaces and DCheckAsserter is the default asserter

// used. During the unit tests is used another class that doesn't "DCHECK"

// in case of collision (check thread_collision_warner_unittests.cc)

struct BASE_EXPORT AsserterBase {

  virtual ~AsserterBase() {}

  virtual void warn() = 0;

};

struct BASE_EXPORT DCheckAsserter : public AsserterBase {

  virtual ~DCheckAsserter() {}

  virtual void warn() override;

};

class BASE_EXPORT ThreadCollisionWarner {

 public:

  // The parameter asserter is there only for test purpose

  explicit ThreadCollisionWarner(AsserterBase* asserter = new DCheckAsserter())

      : valid_thread_id_(0),

        counter_(0),

        asserter_(asserter) {}

  ~ThreadCollisionWarner() {

    delete asserter_;

  }

  // This class is meant to be used through the macro

  // DFAKE_SCOPED_LOCK_THREAD_LOCKED

  // it doesn't leave the critical section, as opposed to ScopedCheck,

  // because the critical section being pinned is allowed to be used only

  // from one thread

  class BASE_EXPORT Check {

   public:

    explicit Check(ThreadCollisionWarner* warner)

        : warner_(warner) {

      warner_->EnterSelf();

    }

    ~Check() {}

   private:

    ThreadCollisionWarner* warner_;

    DISALLOW_COPY_AND_ASSIGN(Check);

  };

  // This class is meant to be used through the macro

  // DFAKE_SCOPED_LOCK

  class BASE_EXPORT ScopedCheck {

   public:

    explicit ScopedCheck(ThreadCollisionWarner* warner)

        : warner_(warner) {

      warner_->Enter();

    }

    ~ScopedCheck() {

      warner_->Leave();

    }

   private:

    ThreadCollisionWarner* warner_;

    DISALLOW_COPY_AND_ASSIGN(ScopedCheck);

  };

  // This class is meant to be used through the macro

  // DFAKE_SCOPED_RECURSIVE_LOCK

  class BASE_EXPORT ScopedRecursiveCheck {

   public:

    explicit ScopedRecursiveCheck(ThreadCollisionWarner* warner)

        : warner_(warner) {

      warner_->EnterSelf();

    }

    ~ScopedRecursiveCheck() {

      warner_->Leave();

    }

   private:

    ThreadCollisionWarner* warner_;

    DISALLOW_COPY_AND_ASSIGN(ScopedRecursiveCheck);

  };

 private:

  // This method stores the current thread identifier and does a DCHECK

  // if a another thread has already done it, it is safe if same thread

  // calls this multiple time (recursion allowed).

  void EnterSelf();

  // Same as EnterSelf but recursion is not allowed.

  void Enter();

  // Removes the thread_id stored in order to allow other threads to

  // call EnterSelf or Enter.

  void Leave();

  // This stores the thread id that is inside the critical section, if the

  // value is 0 then no thread is inside.

  volatile subtle::Atomic64 valid_thread_id_;

  // Counter to trace how many time a critical section was "pinned"

  // (when allowed) in order to unpin it when counter_ reaches 0.

  volatile subtle::Atomic64 counter_;

  // Here only for class unit tests purpose, during the test I need to not

  // DCHECK but notify the collision with something else.

  AsserterBase* asserter_;

  DISALLOW_COPY_AND_ASSIGN(ThreadCollisionWarner);

};

}  // namespace base

#endif  // YB_GUTIL_THREADING_THREAD_COLLISION_WARNER_H