UT/UT_ThreadSpecificValue.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.
 *
 * Produced by:
 *      Side Effects Software Inc
 *      123 Front Street West, Suite 1401
 *      Toronto, Ontario
 *      Canada   M5J 2M2
 *      416-504-9876
 *
 * COMMENTS:
 *     This class defines a thread-specific pointer that can be used to
 *     implement thread-local storage.  Each thread that accesses the
 *     pointer will have its own copy of the pointer's value, and the
 *     initial value for all threads is null.
 *
 *     To replace a global variable like
 *
 *         static int theGlobalValue = 0;
 *         // use theGlobalValue
 *
 *     to use thread-local storage, you would write something like
 *
 *         static UT_ThreadSpecificValue<int> theGlobalValue;
 *         // use theGlobalValue.get()
 *
 *     Note that the default constructor for the values will be called.
 *     (For native data types like ints, floats, pointers, etc., they will
 *     be initialized to zero/null.)
 *
 *     This class has been tuned for speed.  Speed of TLS is surprisingly
 *     sensitive to changes to this class.
 */

#ifndef __UT_ThreadSpecificValue_h__
#define __UT_ThreadSpecificValue_h__

#if defined(GAMEOS)
#define HAS_NO_TLS
#endif

#ifndef HAS_NO_TLS
#include "UT_Thread.h"
#include "UT_Lock.h"
#endif

#include "UT_PtrArray.h"
#include <limits>

#define UT_TYPICAL_MAX_THREADS 16

template <typename T> class ut_IsPointer
{ public: static const bool value = false; };

template <typename U> class ut_IsPointer<U*>
{ public: static const bool value = true; };

// Simple implementation for platforms which have no thread support
template <typename T>
class UT_ThreadSpecificValue
{
public:
    UT_ThreadSpecificValue()
    {
        // If T is an object, the default constructor will have been called.
        // Otherwise, initialize the memory to 0.
        if (std::numeric_limits<T>::is_specialized || ut_IsPointer<T>::value)
            memset(myPreallocatedValues, 0, sizeof(T) * UT_TYPICAL_MAX_THREADS);
    }

    ~UT_ThreadSpecificValue()
    {
        for (int i=0; i<myDynamicValues.entries(); ++i)
            delete myDynamicValues(i);
    }

    // getMySequentialThreadIndex() will "allocate" an index for this thread
    // if it has never been called from this thread.  The thread indices it
    // returns start at 0.  See UT_Thread.h for more information.
    //
    // Note that we use a UT_PtrArray instead of a UT_RefArray.  This way,
    // one thread can call get(), growing myDynamicValues, and hold a reference
    // to the result.  Then a second thread can call get(), growing
    // myDynamicValues again.  If we used a UT_RefArray instead of a
    // UT_PtrArray, the first thread's reference would become invalid.
    T &get()
    {
#ifdef HAS_NO_TLS
        int index = 0;
#else
        int index = UT_Thread::getMySequentialThreadIndex() - 1;
#endif
        if (index < UT_TYPICAL_MAX_THREADS)
            return myPreallocatedValues[index];

        return growDynamicValues(index);
    }

    const T &get() const
    {
#ifdef HAS_NO_TLS
        int index = 0;
#else
        int index = UT_Thread::getMySequentialThreadIndex() - 1;
#endif
        if (index < UT_TYPICAL_MAX_THREADS)
            return myPreallocatedValues[index];

        return growDynamicValues(index);
    }

    /// Access the value for a particular thread index.
    /// Note that the threads you care about may not have
    /// been assigned sequentially!  Always loop up to the maxthreads
    /// value and be able to handle zero-initialized empty data.
    T &getValueForThread(int thread_index)
    {
        // We want to catch cases where people are passing in the default 0
        // thread value. However, for HDK users, we will fall back to computing
        // it automatically for correctness.
        UT_ASSERT(thread_index > 0);
        if (thread_index == 0)
            thread_index = UT_Thread::getMySequentialThreadIndex() - 1;
        else
            thread_index--;

        if (thread_index < UT_TYPICAL_MAX_THREADS)
            return myPreallocatedValues[thread_index];

        return growDynamicValues(thread_index);
    }
    const T &getValueForThread(int thread_index) const
    {
        // We want to catch cases where people are passing in the default 0
        // thread value. However, for HDK users, we will fall back to computing
        // it automatically for correctness.
        UT_ASSERT(thread_index > 0);
        if (thread_index == 0)
            thread_index = UT_Thread::getMySequentialThreadIndex() - 1;
        else
            thread_index--;

        if (thread_index < UT_TYPICAL_MAX_THREADS)
            return myPreallocatedValues[thread_index];

        return growDynamicValues(thread_index);
    }

    /// The highest value of thread index that has been seen by
    /// this threadspecific value.  Iterating over 0..maxthreads-1
    /// will allow you to check all thread output.
    int maxThreadsSeen() const
    {
        // This may be less than the actual number if someone
        // is currently writing to myDynamicValues, but then one
        // is doing something very questionable.
        return UT_TYPICAL_MAX_THREADS + myDynamicValues.entries();
    }

private:
    UT_ThreadSpecificValue(const UT_ThreadSpecificValue<T> &); // unimplemented

    T &growDynamicValues(int thread_index) const
    {
        // UT_PtrArray will properly grow the array if necessary and return
        // a null pointer.
        UT_AutoLock auto_lock(myDynamicValueLock);
        T *&value_pointer =
            myDynamicValues[thread_index - UT_TYPICAL_MAX_THREADS];
        if (!value_pointer)
            value_pointer = new T();
        return *value_pointer;
    }

private:
    T myPreallocatedValues[UT_TYPICAL_MAX_THREADS];
    mutable UT_PtrArray<T *> myDynamicValues;
    mutable UT_Lock myDynamicValueLock;
};

#undef UT_TYPICAL_MAX_THREADS

#endif

---