common/sharedptr.h

/*
*******************************************************************************
* Copyright (C) 2014, International Business Machines Corporation and         
* others. All Rights Reserved.                                                
*******************************************************************************
*                                                                             
* File SHAREDPTR.H                                                             
*******************************************************************************
*/

#ifndef __SHARED_PTR_H__
#define __SHARED_PTR_H__

#include "unicode/uobject.h"
#include "umutex.h"
#include "uassert.h"

U_NAMESPACE_BEGIN

// Wrap u_atomic_int32_t in a UMemory so that we allocate them in the same
// way we allocate all other ICU objects.
struct AtomicInt : public UMemory {
    u_atomic_int32_t value;
};

/**
 * SharedPtr are shared pointers that support copy-on-write sematics.
 * SharedPtr makes the act of copying large objects cheap by deferring the
 * cost of the copy to the first write operation after the copy.
 *
 * A SharedPtr<T> instance can refer to no object or an object of type T.
 * T must have a clone() method that copies
 * the object and returns a pointer to the copy. Copy and assignment of
 * SharedPtr instances are cheap because they only involve copying or
 * assigning the SharedPtr instance, not the T object which could be large.
 * Although many SharedPtr<T> instances may refer to the same T object,
 * clients can still assume that each SharedPtr<T> instance has its own
 * private instance of T because each SharedPtr<T> instance offers only a
 * const view of its T object through normal pointer operations. If a caller
 * must change a T object through its SharedPtr<T>, it can do so by calling
 * readWrite() on the SharedPtr instance. readWrite() ensures that the
 * SharedPtr<T> really does have its own private T object by cloning it if
 * it is shared by using its clone() method. SharedPtr<T> instances handle
 * management by reference counting their T objects. T objects that are
 * referenced by no SharedPtr<T> instances get deleted automatically.
 */

// TODO (Travis Keep): Leave interface the same, but find a more efficient
// implementation that is easier to understand.
template<typename T>
class SharedPtr {
public:
    /**
     * Constructor. If there is a memory allocation error creating
     * reference counter then this object will contain NULL, and adopted
     * pointer will be freed. Note that when passing NULL or no argument to
     * constructor, no memory allocation error can happen as NULL pointers
     * are never reference counted.
     */
    explicit SharedPtr(T *adopted=NULL) : ptr(adopted), refPtr(NULL) {
        if (ptr != NULL) {
            refPtr = new AtomicInt();
            if (refPtr == NULL) {
                delete ptr;
                ptr = NULL;
            } else {
                refPtr->value = 1;
            }
        }
    }

    /**
     * Copy constructor.
     */
    SharedPtr(const SharedPtr<T> &other) :
            ptr(other.ptr), refPtr(other.refPtr) {
        if (refPtr != NULL) {
            umtx_atomic_inc(&refPtr->value);
        }
    }

    /**
     * assignment operator.
     */
    SharedPtr<T> &operator=(const SharedPtr<T> &other) {
        if (ptr != other.ptr) {
            SharedPtr<T> newValue(other);
            swap(newValue);
        }
        return *this;
    }

    /**
     * Destructor.
     */
    ~SharedPtr() {
        if (refPtr != NULL) {
            if (umtx_atomic_dec(&refPtr->value) == 0) {
                delete ptr;
                delete refPtr;
            }
        }
    }

    /**
     * reset adopts a new pointer. On success, returns TRUE.
     * On memory allocation error creating reference counter for adopted
     * pointer, returns FALSE while leaving this instance unchanged.
     */
    bool reset(T *adopted) {
        SharedPtr<T> newValue(adopted);
        if (adopted != NULL && newValue.ptr == NULL) {
            // We couldn't allocate ref counter.
            return FALSE;
        }
        swap(newValue);
        return TRUE;
    }

    /**
     * reset makes this instance refer to no object.
     */
    void reset() {
        reset(NULL);
    }

    /**
     * count returns how many SharedPtr instances, including this one,
     * refer to the T object. Used for testing. Clients need not use in
     * practice.
     */
    int32_t count() const {
        if (refPtr == NULL) {
            return 0;
        }
        return umtx_loadAcquire(refPtr->value);
    }

    /**
     * Swaps this instance with other.
     */
    void swap(SharedPtr<T> &other) {
        T *tempPtr = other.ptr;
        AtomicInt *tempRefPtr = other.refPtr;
        other.ptr = ptr;
        other.refPtr = refPtr;
        ptr = tempPtr;
        refPtr = tempRefPtr;
    }

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

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

    bool operator==(const T *other) const {
        return ptr == other;
    }

    bool operator!=(const T *other) const {
        return ptr != other;
    }

    /**
     * readOnly gives const access to this instance's T object. If this
     * instance refers to no object, returns NULL.
     */
    const T *readOnly() const {
        return ptr;
    }

    /**
     * readWrite returns a writable pointer to its T object copying it first
     * using its clone() method if it is shared.
     * On memory allocation error or if this instance refers to no object,
     * this method returns NULL leaving this instance unchanged.
     * <p>
     * If readWrite() returns a non NULL pointer, it guarantees that this
     * object holds the only reference to its T object enabling the caller to
     * perform mutations using the returned pointer without affecting other
     * SharedPtr objects. However, the non-constness of readWrite continues as
     * long as the returned pointer is in scope. Therefore it is an API
     * violation to call readWrite() on A; perform B = A; and then proceed to
     * mutate A via its writeable pointer as that would be the same as setting
     * B = A while A is changing. The returned pointer is guaranteed to be
     * valid only while this object is in scope because this object maintains
     * ownership of its T object. Therefore, callers must never attempt to
     * delete the returned writeable pointer. The best practice with readWrite
     * is this: callers should use the returned pointer from readWrite() only
     * within the same scope as that call to readWrite, and that scope should
     * be made as small as possible avoiding overlap with other operatios on
     * this object.
     */
    T *readWrite() {
        int32_t refCount = count();
        if (refCount <= 1) {
            return ptr;
        }
        T *result = (T *) ptr->clone();
        if (result == NULL) {
            // Memory allocation error
            return NULL;
        }
        if (!reset(result)) {
            return NULL;
        }
        return ptr;
    }
private:
    T *ptr;
    AtomicInt *refPtr;
    // No heap allocation. Use only stack.
    static void * U_EXPORT2 operator new(size_t size);
    static void * U_EXPORT2 operator new[](size_t size);
#if U_HAVE_PLACEMENT_NEW
    static void * U_EXPORT2 operator new(size_t, void *ptr);
#endif
};

U_NAMESPACE_END

#endif