UT_DoubleLock.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        UT_DoubleLock.h ( UT Library, C++)
 *
 * COMMENTS:
 */

#ifndef __UT_DoubleLock__
#define __UT_DoubleLock__

#include "UT_API.h"
#include "UT_Lock.h"
#include "UT_NonCopyable.h"
#include "UT_UniquePtr.h"
#include <SYS/SYS_MemoryOrder.h>

///
/// A double-checked lock.  Only locks the thread lock when the value is 0.
/// 
/// To use this lock:
///
/// static UT_Lock theLock;
/// static OBJECT *theObj = 0;
///
/// OBJECT *
/// getSingleton()
/// {
///     UT_DoubleLock<OBJECT *> lock(theLock, theObj);
///
///     if (!lock.getValue())
///     {
///         // NOTE: This doesn't set theObj.  theObj is set when
///         //       destructing lock.
///         lock.setValue(new OBJECT());
///     }
///     return lock.getValue();
/// }
///
/// NOTE: DO NOT roll your own double checked lock!  If you
///       don't know when to use which memory fences and why,
///       odds are high that your custom implementation will be
///       thread-unsafe.
///
/// For simple singleton initialization, consider using UT_Singleton.
///
template <typename ValueT, typename LockT = UT_Lock>
class UT_DoubleLock
{
    template <typename Y> class ValueTrait;
    template <typename Y, typename DT> class ValueTrait<UT_UniquePtr<Y, DT>>;
    template <typename Y, typename DT> class ValueTrait<UT_UniquePtr<Y[], DT>>;

    using TraitT = ValueTrait<ValueT>;

public:
    using GetT = typename TraitT::GetT;
    using SetT = typename TraitT::SetT;
    static_assert(sizeof(ValueT) == sizeof(GetT), "T is not trivial");

    UT_DoubleLock(LockT &lock, volatile ValueT &val)
        : myLock(lock)
        , myValue(val)
        , myPendingValue{} // default value initialize
        , myIsLocked(false)
        , myNeedInit(false)
    {
        if (!relaxedLoad(val))
        {
            myLock.lock();
            myIsLocked = true;
            if (!relaxedLoad(val))
                myNeedInit = true;
        }
    }
    
    ~UT_DoubleLock()
    {
        if (myIsLocked)
        {
            if (myNeedInit)
            {
                UT_ASSERT_P(myPendingValue);

                // Ensure that the data that myPendingValue refers to is
                // written out to main memory before setting myValue.
                SYSstoreFence();

                relaxedStore(myValue, TraitT::release(myPendingValue));

                // NOTE: LockT::unlock also does a store fence before
                //       unlocking, which ensures that myValue is written out to
                //       main memory before the lock is unlocked.  If it didn't,
                //       the next thread might read myValue of 0 and try to
                //       initialize it again.  The store fence above is also
                //       needed.
            }
            myLock.unlock();
        }
    }

    UT_NON_COPYABLE(UT_DoubleLock)

    GetT getValue() const
    {
        if (myPendingValue)
            return TraitT::get(myPendingValue);

        GetT v = relaxedLoad(myValue);

        // This load fence is to ensure that any side effects of allocation
        // in another thread, including values in the heap itself, are not
        // speculatively read before the read of myValue.  Also, some places
        // do more than allocate a single item pointed to by v, especially
        // for cases with UT_DoubleLock<bool>, so those count as side
        // effects here.
        SYSloadFence();

        return v;
    }
    void setValue(SetT val)
    {
        UT_ASSERT_P(myNeedInit);
        TraitT::move(myPendingValue, val);
    }

    /// Abort writing back out to the val passed in the constructor upon
    /// destruction.
    void abort()
    {
        myNeedInit = false;
    }

private:
    template <typename Y>
    class ValueTrait
    {
    public:
        using GetT = Y;
        using SetT = Y;

        static Y    release(Y &v)               { return v; }
        static GetT get(const Y &v)             { return v; }
        static void move(Y &dst, const Y &src)  { dst = src; }
    };
    template <typename Y, typename DT>
    class ValueTrait<UT_UniquePtr<Y, DT>>
    {
        using PtrT = UT_UniquePtr<Y, DT>;
    public:
        using GetT = Y*;
        using SetT = PtrT &&;

        static GetT release(PtrT &v)            { return v.release(); }
        static GetT get(const PtrT &v)          { return v.get(); }
        static void move(PtrT &dst, PtrT &src)  { dst.reset(src.release()); }
    };
    template <typename Y, typename DT>
    class ValueTrait<UT_UniquePtr<Y[], DT>>
    {
        using PtrT = UT_UniquePtr<Y[], DT>;
    public:
        using GetT = Y*;
        using SetT = PtrT &&;

        static GetT release(PtrT &v)            { return v.release(); }
        static GetT get(const PtrT &v)          { return v.get(); }
        static void move(PtrT &dst, PtrT &src)  { dst.reset(src.release()); }
    };

    static GetT relaxedLoad(const volatile ValueT &ptr)
    {
        const volatile GetT *addr
                = reinterpret_cast<const volatile GetT *>(&ptr);
        return *static_cast<const volatile GetT *>(addr);
    }
    static void relaxedStore(volatile ValueT &ptr, GetT src)
    {
        volatile GetT *addr = reinterpret_cast<volatile GetT *>(&ptr);
        *static_cast<volatile GetT *>(addr) = src;
    }
    
private:
    LockT           &myLock;
    volatile ValueT &myValue;
    ValueT           myPendingValue;
    bool             myIsLocked;
    bool             myNeedInit;
};

#endif