bigRWMutex.h

//
// Copyright 2022 Pixar
//
// Licensed under the Apache License, Version 2.0 (the "Apache License")
// with the following modification; you may not use this file except in
// compliance with the Apache License and the following modification to it:
// Section 6. Trademarks. is deleted and replaced with:
//
// 6. Trademarks. This License does not grant permission to use the trade
//    names, trademarks, service marks, or product names of the Licensor
//    and its affiliates, except as required to comply with Section 4(c) of
//    the License and to reproduce the content of the NOTICE file.
//
// You may obtain a copy of the Apache License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the Apache License with the above modification is
// distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the Apache License for the specific
// language governing permissions and limitations under the Apache License.
//
#ifndef PXR_BASE_TF_BIG_RW_MUTEX_H
#define PXR_BASE_TF_BIG_RW_MUTEX_H

#include "pxr/pxr.h"
#include "pxr/base/tf/api.h"

#include "pxr/base/arch/align.h"
#include "pxr/base/arch/hints.h"
#include "pxr/base/tf/diagnosticLite.h"
#include "pxr/base/tf/hash.h"
#include "pxr/base/tf/spinRWMutex.h"

#include <atomic>
#include <memory>
#include <thread>

PXR_NAMESPACE_OPEN_SCOPE

class TfBigRWMutex
{
public:
    // Number of different cache-line-sized lock states.
    static constexpr unsigned NumStates = 16;

    // Lock states -- 0 means not locked, -1 means locked for write, other
    // positive values count the number of readers locking this particular lock
    // state object.
    static constexpr int NotLocked = 0;
    static constexpr int WriteLocked = -1;

    TF_API TfBigRWMutex();

    struct ScopedLock {

        // Acquisition states: -1 means not acquired, -2 means acquired for
        // write (exclusive lock), >= 0 indicates locked for read, and the value
        // indicates which lock state index the reader has incremented.
        static constexpr int NotAcquired = -1;
        static constexpr int WriteAcquired = -2;

        explicit ScopedLock(TfBigRWMutex &m, bool write=true)
            : _mutex(&m)
            , _acqState(NotAcquired) {
            Acquire(write);
        }

        ScopedLock() : _mutex(nullptr), _acqState(NotAcquired) {}

        ~ScopedLock() {
            Release();
        }

        void Acquire(TfBigRWMutex &m, bool write=true) {
            Release();
            _mutex = &m;
            Acquire(write);
        }            

        void Acquire(bool write=true) {
            if (write) {
                AcquireWrite();
            }
            else {
                AcquireRead();
            }
        }

        void Release() {
            switch (_acqState) {
            case NotAcquired:
                break;
            case WriteAcquired:
                _ReleaseWrite();
                break;
            default:
                _ReleaseRead();
                break;
            };
        }

        void AcquireRead() {
            TF_AXIOM(_acqState == NotAcquired);
            _acqState = _mutex->_AcquireRead(_GetSeed());
        }

        void AcquireWrite() {
            TF_AXIOM(_acqState == NotAcquired);
            _mutex->_AcquireWrite();
            _acqState = WriteAcquired;
        }

        bool UpgradeToWriter() {
            TF_AXIOM(_acqState >= 0);
            Release();
            AcquireWrite();
            return false;
        }
        
    private:

        void _ReleaseRead() {
            TF_AXIOM(_acqState >= 0);
            _mutex->_ReleaseRead(_acqState);
            _acqState = NotAcquired;
        }

        void _ReleaseWrite() {
            TF_AXIOM(_acqState == WriteAcquired);
            _mutex->_ReleaseWrite();
            _acqState = NotAcquired;
        }

        // Helper for returning a seed value associated with this lock object.
        // This helps determine which lock state a read-lock should use.
        inline int _GetSeed() const {
            return static_cast<int>(
                static_cast<unsigned>(TfHash()(this)) >> 8);
        }

        TfBigRWMutex *_mutex;
        int _acqState; // NotAcquired (-1), WriteAcquired (-2), otherwise
                       // acquired for read, and index indicates which lock
                       // state we are associated with.
    };

private:

    // Optimistic read-lock case inlined.
    inline int _AcquireRead(int seed) {
        // Determine a lock state index to use.
        int stateIndex = seed % NumStates;
        if (ARCH_UNLIKELY(_writerActive) ||
            !_states[stateIndex].mutex.TryAcquireRead()) {
            _AcquireReadContended(stateIndex);
        }
        return stateIndex;
    }

    // Contended read-lock helper.
    TF_API void _AcquireReadContended(int stateIndex);

    void _ReleaseRead(int stateIndex) {
        _states[stateIndex].mutex.ReleaseRead();
    }

    TF_API void _AcquireWrite();
    TF_API void _ReleaseWrite();
    
    struct _LockState {
        TfSpinRWMutex mutex;
        // This padding ensures that \p state instances sit on different cache
        // lines.
        char _unused_padding[
            ARCH_CACHE_LINE_SIZE-(sizeof(mutex) % ARCH_CACHE_LINE_SIZE)];
    };

    std::unique_ptr<_LockState []> _states;
    std::atomic<bool> _writerActive;
    
};

PXR_NAMESPACE_CLOSE_SCOPE

#endif // PXR_BASE_TF_BIG_RW_MUTEX_H