CloneOnWritePtr.h

Go to the documentation of this file.

#ifndef SimTK_SimTKCOMMON_CLONE_ON_WRITE_PTR_H_
#define SimTK_SimTKCOMMON_CLONE_ON_WRITE_PTR_H_

/* -------------------------------------------------------------------------- *
 *                       Simbody(tm): SimTKcommon                             *
 * -------------------------------------------------------------------------- *
 * This is part of the SimTK biosimulation toolkit originating from           *
 * Simbios, the NIH National Center for Physics-Based Simulation of           *
 * Biological Structures at Stanford, funded under the NIH Roadmap for        *
 * Medical Research, grant U54 GM072970. See https://simtk.org/home/simbody.  *
 *                                                                            *
 * Portions copyright (c) 2015 Stanford University and the Authors.           *
 * Authors: Michael Sherman                                                   *
 * Contributors:                                                              *
 *                                                                            *
 * 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.                                             *
 * -------------------------------------------------------------------------- */

#include "SimTKcommon/internal/common.h"

#include <memory>
#include <iosfwd>
#include <cassert>

namespace SimTK {

//==============================================================================
//                          CLONE ON WRITE PTR
//==============================================================================
template <class T> class CloneOnWritePtr {
public:
    typedef T  element_type; 
    typedef T* pointer;      
    typedef T& reference;    
    
    CloneOnWritePtr() noexcept {init();}

    CloneOnWritePtr(std::nullptr_t) noexcept : CloneOnWritePtr() {}

    explicit CloneOnWritePtr(T* x) : CloneOnWritePtr()
    {   if (x) {p=x; count=new long(1);} } 

    explicit CloneOnWritePtr(const T* x) : CloneOnWritePtr(cloneOrNull(x)) {}

    explicit CloneOnWritePtr(const T& x) : CloneOnWritePtr(&x) {}

    CloneOnWritePtr(const CloneOnWritePtr& src) noexcept : CloneOnWritePtr() 
    {   shareWith(src); }

    template <class U>
    CloneOnWritePtr(const CloneOnWritePtr<U>& src) noexcept : CloneOnWritePtr() 
    {   shareWith<U>(src); }

    CloneOnWritePtr(CloneOnWritePtr&& src) noexcept : CloneOnWritePtr() 
    {   moveFrom(std::move(src)); }

    template <class U>
    CloneOnWritePtr(CloneOnWritePtr<U>&& src) noexcept : CloneOnWritePtr()
    {   moveFrom<U>(std::move(src)); }
    CloneOnWritePtr& operator=(const CloneOnWritePtr& src) noexcept { 
        if (src.p != p) 
        {   reset(); shareWith(src); }
        return *this;
    }

    template <class U>
    CloneOnWritePtr& operator=(const CloneOnWritePtr<U>& src) noexcept { 
        if (static_cast<T*>(src.p) != p) 
        {   reset(); shareWith<U>(src); }
        return *this;
    }

    CloneOnWritePtr& operator=(CloneOnWritePtr&& src) noexcept { 
        if (&src != this) 
        {   reset(); moveFrom(std::move(src)); }
        return *this;
    }

    template <class U>
    CloneOnWritePtr& operator=(CloneOnWritePtr<U>&& src) noexcept {
        // Can't be the same container since the type is different.
        reset(); moveFrom<U>(std::move(src));
        return *this;
    }

    CloneOnWritePtr& operator=(const T& x)          
    {   reset(cloneOrNull(&x)); return *this; }

    CloneOnWritePtr& operator=(T* x) noexcept
    {   reset(x); return *this; }
    ~CloneOnWritePtr() noexcept {reset();}
    const T* get() const noexcept {return p;}

    T* upd() {detach(); return p;}

    const T& getRef() const { 
        SimTK_ERRCHK(!empty(), "CloneOnWritePtr::getRef()", 
                    "An attempt was made to dereference a null pointer."); 
        return *get(); 
    } 

    T& updRef() { 
        SimTK_ERRCHK(!empty(), "CloneOnWritePtr::updRef()", 
                    "An attempt was made to dereference a null pointer.");
        return *upd(); 
    }

    const T* operator->() const { return &getRef(); }

    T* operator->() { return &updRef(); }

    const T& operator*() const {return getRef();}

    T& operator*() {return updRef();}
    void reset() noexcept {
        if (empty()) return;
        if (decr()==0) {delete p; delete count;} 
        init();
    }

    void reset(T* x) { // could throw when allocating count
        if (x != p) {
            reset();
            if (x) {p=x; count=new long(1);}
        }
    }

    void swap(CloneOnWritePtr& other) noexcept {
        std::swap(p, other.p);
        std::swap(count, other.count);
    }

    long use_count() const noexcept {return count ? *count : 0;}

    bool unique() const noexcept {return use_count()==1;}
   
    bool empty() const noexcept {return !p;} // count should be null also

    explicit operator bool() const noexcept {return !empty();}

    T* release() { // could throw during detach()
        detach(); // now use count is 1 or 0
        T* save = p; delete count; init();
        return save;
    }

    void detach() { // can throw during clone()
        if (use_count() > 1) 
        {   decr(); p=p->clone(); count=new long(1); }
    }
private:
template <class U> friend class CloneOnWritePtr;

    // If src is non-null, clone it; otherwise return null.
    static T* cloneOrNull(const T* src) {
        return src ? src->clone() : nullptr;
    }

    // Set an empty pointer to share with the given object. Type U* must be
    // implicitly convertible to type T*.
    template <class U> void shareWith(const CloneOnWritePtr<U>& src) noexcept {
        assert(!(p||count)); 
        if (!src.empty()) {p=src.p; count=src.count; incr();}
    }

    // Steal the object and count from the source to initialize this *empty* 
    // pointer, leaving the source empty.
    template <class U> void moveFrom(CloneOnWritePtr<U>&& src) noexcept {
        assert(!(p||count)); 
        p=src.p; count=src.count; src.init();
    }

    // Increment/decrement use count and return the result.
    long incr() const noexcept {assert(count && *count>=0); return ++(*count);}
    long decr() const noexcept {assert(count && *count>=1); return --(*count);}

    void init() noexcept {p=nullptr; count=nullptr;}

    // Can't use std::shared_ptr here due to lack of release() method.
    T*      p;          // this may be null
    long*   count;      // if p is null so is count
};    


//==============================================================================
//                       SimTK namespace-scope functions
//==============================================================================
// These namespace-scope functions will be resolved by the compiler using
// "Koenig lookup" which examines the arguments' namespaces first.
// See Herb Sutter's discussion here: http://www.gotw.ca/publications/mill08.htm.

template <class T> inline void
swap(CloneOnWritePtr<T>& p1, CloneOnWritePtr<T>& p2) {
    p1.swap(p2);
}

template <class charT, class traits, class T>
inline std::basic_ostream<charT,traits>& 
operator<<(std::basic_ostream<charT,traits>& os, 
           const CloneOnWritePtr<T>&  p) 
{   os << p.get(); return os; }

template <class T, class U>
inline bool operator==(const CloneOnWritePtr<T>& lhs,
                       const CloneOnWritePtr<U>& rhs)
{   return lhs.get() == rhs.get(); }

template <class T>
inline bool operator==(const CloneOnWritePtr<T>& lhs, std::nullptr_t)
{   return lhs.empty(); }

template <class T>
inline bool operator==(std::nullptr_t, const CloneOnWritePtr<T>& rhs)
{   return rhs.empty(); }

template <class T, class U>
inline bool operator<(const CloneOnWritePtr<T>& lhs,
                      const CloneOnWritePtr<U>& rhs)
{   return lhs.get() < rhs.get(); }

template <class T>
inline bool operator<(const CloneOnWritePtr<T>& lhs, std::nullptr_t)
{   return false; }

template <class T>
inline bool operator<(std::nullptr_t, const CloneOnWritePtr<T>& rhs)
{   return !rhs.empty(); }


// These functions are derived from operator== and operator<.

template <class T, class U>
inline bool operator!=(const CloneOnWritePtr<T>& lhs,
                       const CloneOnWritePtr<U>& rhs)
{   return !(lhs==rhs); }
template <class T>
inline bool operator!=(const CloneOnWritePtr<T>& lhs, std::nullptr_t)
{   return !(lhs==nullptr); }
template <class T>
inline bool operator!=(std::nullptr_t, const CloneOnWritePtr<T>& rhs)
{   return !(nullptr==rhs); }

template <class T, class U>
inline bool operator>(const CloneOnWritePtr<T>& lhs,
                      const CloneOnWritePtr<U>& rhs)
{   return rhs < lhs; }
template <class T>
inline bool operator>(const CloneOnWritePtr<T>& lhs, std::nullptr_t)
{   return nullptr < lhs; }

template <class T>
inline bool operator>(std::nullptr_t, const CloneOnWritePtr<T>& rhs)
{   return rhs < nullptr; }


template <class T, class U>
inline bool operator>=(const CloneOnWritePtr<T>& lhs,
                       const CloneOnWritePtr<U>& rhs)
{   return !(lhs < rhs); }
template <class T>
inline bool operator>=(const CloneOnWritePtr<T>& lhs, std::nullptr_t)
{   return !(lhs < nullptr); }

template <class T>
inline bool operator>=(std::nullptr_t, const CloneOnWritePtr<T>& rhs)
{   return !(nullptr < rhs); }


template <class T, class U>
inline bool operator<=(const CloneOnWritePtr<T>& lhs,
                       const CloneOnWritePtr<U>& rhs)
{   return !(rhs < lhs); }
template <class T>
inline bool operator<=(const CloneOnWritePtr<T>& lhs, std::nullptr_t)
{   return !(nullptr < lhs); }
template <class T>
inline bool operator<=(std::nullptr_t, const CloneOnWritePtr<T>& rhs)
{   return !(rhs < nullptr); }

} // namespace SimTK

#endif // SimTK_SimTKCOMMON_CLONE_ON_WRITE_PTR_H_