text: ////////////////////////////////////////////////////////////////////////////////
  /// DISCLAIMER
  ///
  /// Copyright 2014-2022 ArangoDB GmbH, Cologne, Germany
  /// Copyright 2004-2014 triAGENS GmbH, Cologne, Germany
  ///
  /// 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.
  ///
  /// Copyright holder is ArangoDB GmbH, Cologne, Germany
  ///
  /// @author Max Neunhoeffer
  ////////////////////////////////////////////////////////////////////////////////
  
  #pragma once
  
  #include <algorithm>
  #include <atomic>
  #include <chrono>
  #include <thread>
  
  #include "Basics/Common.h"
  
  namespace arangodb {
  namespace basics {
  
  ////////////////////////////////////////////////////////////////////////////////
  /// @brief DataProtector, a template class to manage a single atomic
  /// value (can be a pointer to some class), optimized for many fast
  /// readers and slow writers using lockfree technology.
  /// The template parameter Nr should be on the order of magnitude of the
  /// maximal number of concurrently running threads.
  /// Usage:
  ///   Put an instance of the DataProtector next to the atomic value you
  ///   want to protect, as in:
  ///     atomic<SomeClass*> p;
  ///     DataProtector<64> prot;
  ///   If you want to read p and *p, do
  ///     auto unuser(prot.use());
  ///     auto pSeen = p;
  ///   in the scope where you want to read p and *p and then only use pSeen
  ///   and *pSeen.
  ///   It is automatically released when the unuser instances goes out of scope.
  ///   This is guaranteed to be very fast, even when multiple threads do it
  ///   concurrently.
  ///   If you want to change p (and call delete on the old value, say), then
  ///     auto oldp = p;       // save the old value of p
  ///     p = <new Value>;     // just assign p whenever you see fit
  ///     prot.scan();         // This will block until no thread is reading
  ///                          // the old value any more.
  ///     delete oldp;         // guaranteed to be safe
  ///   This can be a slow operation and only one thread should perform it
  ///   at a time. Use a mutex to ensure this.
  ///   Please note:
  ///     - The value of p *can* change under the feet of the reading threads,
  ///       which is why you need to use the pSeen variable. However, you know
  ///       that as long as unused is in scope, pSeen remains valid.
  ///     - The DataProtector instances needs 64*Nr bytes of memory.
  ///     - DataProtector.cpp needs to contain an explicit template
  ///       instantiation for all values of Nr used in the executable.
  ////////////////////////////////////////////////////////////////////////////////
  
  class DataProtector {
    static constexpr int DATA_PROTECTOR_MULTIPLICITY = 64;
  
    // disabled because of:
    //   note: uses ‘void* operator new(std::size_t)’, which does not have an
    //   alignment parameter note: use ‘-faligned-new’ to enable C++17
    //   over-aligned new support
    // struct alignas(64) Entry {  // 64 is the size of a cache line,
    struct Entry {  // 64 is the size of a cache line,
      // it is important that different list entries lie in different
      // cache lines.
      std::atomic<int> _count;
  
      Entry() : _count(0) {}
    };
  
    typename std::aligned_storage<sizeof(Entry), alignof(Entry)>::type
        _list[DATA_PROTECTOR_MULTIPLICITY];
  
    static std::atomic<int> _last;
  
    static thread_local int _mySlot;
  
   public:
    // A class to automatically unuse the DataProtector:
    class UnUser {
      DataProtector* _prot;
      int _id;
  
     public:
      UnUser(DataProtector* p, int i) : _prot(p), _id(i) {}
  
      ~UnUser() {
        if (_prot != nullptr) {
          _prot->unUse(_id);
        }
      }
  
      // A move constructor
      UnUser(UnUser&& that) : _prot(that._prot), _id(that._id) {
        // Note that return value optimization will usually avoid
        // this move constructor completely. However, it has to be
        // present for the program to compile.
        that._prot = nullptr;
      }
  
      // Explicitly delete the others:
      UnUser(UnUser const& that) = delete;
      UnUser& operator=(UnUser const& that) = delete;
      UnUser& operator=(UnUser&& that) = delete;
      UnUser() = delete;
    };
  
    DataProtector() {
      // initialize uninitialized memory
      for (int i = 0; i < DATA_PROTECTOR_MULTIPLICITY; i++) {
        new (_list + i) Entry;
      }
    }
  
    ~DataProtector() {
      for (int i = 0; i < DATA_PROTECTOR_MULTIPLICITY; i++) {
        reinterpret_cast<Entry*>(_list + i)->~Entry();
      }
    }
  
    UnUser use() {
      int id = getMyId();
      // this is implicitly using memory_order_seq_cst
      reinterpret_cast<Entry*>(_list + id)->_count++;
      return UnUser(this, id);  // return value optimization!
    }
  
    void scan() {
      for (int i = 0; i < DATA_PROTECTOR_MULTIPLICITY; i++) {
        while (reinterpret_cast<Entry*>(_list + i)->_count > 0) {
          // let other threads do some work while we're waiting
          std::this_thread::sleep_for(std::chrono::microseconds(250));
        }
      }
    }
  
   private:
    void unUse(int id) {
      // this is implicitly using memory_order_seq_cst
      reinterpret_cast<Entry*>(_list + id)->_count--;
    }
  
    int getMyId();
  };
  
  }  // namespace basics
  }  // namespace arangodb
  