UT/UT_Thread.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
 *      477 Richmond Street West
 *      Toronto, Ontario
 *      Canada   M5V 3E7
 *      416-504-9876
 *
 * NAME:        UT_Thread.h ( UT Library, C++)
 *
 * COMMENTS:    Generic thread class.
 *      The owner of the thread can do things like:
 *
 *      killThread()    - Stop execution of thread
 *      waitThread()    - Wait until thread finishes execution
 *      suspendThread() - Suspend execution of thread
 *      restartThread() - Restart a stopped thread
 *      niceThread()    - Prioritize thread (0 low priority, 100 high)
 *
 *  TODO:  It might be nice to have a way to get the exit status of a thread.
 */

#ifndef __UT_Thread__
#define __UT_Thread__

#include "UT_API.h"
#include <stdlib.h>
#include <SYS/SYS_Types.h>
#include "UT_Assert.h"
#include "UT_Defines.h"

#if defined(WIN32)
    typedef int         ut_thread_id_t;
#elif defined(USE_PTHREADS)
    #include <pthread.h>
    typedef pthread_t   ut_thread_id_t;
#else
    #error Unsupported Platform for UT_Thread
#endif

#define UT_INVALID_THREAD_ID ((ut_thread_id_t)0)

// some stack size defines
#define UT_THREAD_DEFAULT_STACK_SIZE    (8U*1024U*1024U)
#define UT_THREAD_SMALL_STACK_SIZE      (1U*1024U*1024U)

typedef void *(*UTthreadFunc)(void*);

// forward declarations
class UT_TaskScope;

class UT_API UT_Thread
{
public:
    // The destructor will wait until the thread is idle before it completes
    // If you wish to kill the thread, call killThread() first.
    virtual ~UT_Thread();

    // This enum specifies the current state for a persistent thread.  The
    // thread will typically be running or idle.  If the thread is idle, it's
    // behaviour will be determined by the SpinState.
    enum {
        ThreadIdle,
        ThreadRunning
    };

    // // The thread status determines how the thread will behave once the
    // callback function is completed:
    //    ThreadSingleRun       - The thread cannot be restarted
    //    ThreadLowUsage        - The thread will yeild cycles while idle
    //
    enum {
        ThreadSingleRun,
        ThreadLowUsage,
    };

    static UT_Thread    *allocThread(int spin_mode);

    static int           getNumProcessors();

    /// Reset the number of threads that is used by Houdini. This will reread
    /// the HOUDINI_MAXTHREADS setting.
    /// @note There should be no active tasks when this is called.
    /// @note Only call this from the MAIN THREAD!
    static void          resetNumProcessors();

    // getMyThreadId() is inlined for speed if we're using pthreads.
#if defined(USE_PTHREADS)
    static ut_thread_id_t getMyThreadId() { return pthread_self(); }
#else
    static ut_thread_id_t getMyThreadId();
#endif

    static ut_thread_id_t getMainThreadId();
    static int            getMainSequentialThreadId();
    static inline int     isMainThread()
                          {
                             return getMyThreadId() == getMainThreadId();
                          }

    // getMySequentialThreadIndex() will return a unique index for the
    // calling thread.  If it hasn't been called from this thread, it will
    // return the next sequential unused index.  The thread indices it returns
    // start at 0, and the maximum number will be less than the total number of
    // different threads that have called this method.  As a result, the
    // thread indices are much more amenable for indexing into arrays than
    // the values returned by getMyThreadId().
    static int           getMySequentialThreadIndex();

    // Return the lowest possible sequential index value. Values lower than
    // this are not allowed for any thread. Note that the main thread might not
    // be this value. This value is subject to change.
    static int           getFirstSequentialThreadIndex()    { return 1; }

    /// Configure the global number of tasks used by the system and the default
    /// stack size for threads. Use negative values to indicate no change. Use
    /// 0 to use default system values.
    /// @note Only call this in the main thread when there are no tasks active.
    /// @note This function is NOT thread-safe.
    static void          configureMaxThreads(int maxthreads = -1,
                                             int stacksize  = -1);

    // Start the thread running.  If the thread is not in idle state, the
    // thread will wait until it's in idle before starting. If the thread
    // doesn't exist yet, it will be created.
    virtual bool         startThread(UTthreadFunc func, void *data) = 0;

    // This method is called when the thread function is first entered.
    // By default it does nothing but some sub-classes may need this.
    virtual void         threadStarted();

    // This method is called when the thread function is returned from.
    // By default it sets the state to idle.
    virtual void         threadEnded();


    // Some thread architectures have very expensive resources (i.e. sproc()
    // threads).  While these threads spin (are idle), they consume system
    // resources.  This method will let the user know whether the threads are
    // resource hogs (so that if they spin for a long time, they could
    // possibley be cleaned up).
    virtual int          isResourceHog() const;

    // For persistent threads (which get restarted)
    virtual int          getState();
    virtual int          getSpinMode();
    virtual void         waitForState(int desired) = 0;
    virtual void         setSpinMode(int spin_mode);

    // Terminate the thread process
    virtual void         killThread() = 0;

    // If it's possible to perform these tasks, the return code will be 1.  If
    // not, the return code will be 0.  Not all
    virtual int          niceThread(int priority) = 0;
    virtual int          suspendThread() = 0;
    virtual int          restartThread() = 0;

    int                  isActive()
                         { return waitThread(0); }

    static void  interval(int count, int thisSection, int numSections,
                          int &start, int &len)
                 {
                   start = (int)(thisSection*count/(fpreal)numSections+0.5F);
                   len = (int)((thisSection+1)*count/(fpreal)numSections+0.5F) -
                                start;
                 }

protected:
    // System dependent internal functions.
    //  waitThread() returns 1 if the thread is still active (i.e. exists) and
    //  should return 0 if the thread doesn't exist.  If waitThread detects
    //  that the thread no longer exists, it should do appropriate cleanup.
    virtual int          waitThread(int block=1) = 0;

    // Quick check to see that the thread is really active
    virtual int          isValid();

    // This method can be used to kill an idle process.
    void                 killIdle();

    static void         *threadWrapper(void *data);

    // Internally used to change the state safely.
    virtual void         setState(int state) = 0;

    volatile int         myState;
    int                  mySpinMode;
    UTthreadFunc         myCallback;
    void                *myCBData;

    const UT_TaskScope  *myTaskScope;

    UT_Thread(int spin_mode);
};

// For debugging, the following uses a single thread (i.e. is not
// multi-threaded)
class UT_API UT_NullThread : public UT_Thread
{
public:
             UT_NullThread();
    virtual ~UT_NullThread();

    virtual bool         startThread(UTthreadFunc func, void *data);
    virtual void         killThread();
    virtual int          waitThread(int block);
    virtual void         waitForState(int );

    virtual int          niceThread(int priority);
    virtual int          suspendThread();
    virtual int          restartThread();

protected:
    virtual void         setState(int state);
};


class UT_API UT_ThreadSet
{
public:
     UT_ThreadSet(int nthreads=-1, int null_thread_if_1_cpu = 0);
    ~UT_ThreadSet();

    void        setFunc(UTthreadFunc func)
                {
                    myFunc = func;
                }
    void        setUserData(void *user_data_array, size_t structlen)
                {
                    myUserData = user_data_array;
                    myUserDataInc = structlen;
                }
    void        setUserData(void *user_data)
                {
                    myUserData = user_data;
                    myUserDataInc = 0;
                }

    void        reuse(int spin_mode);
    void        go();
    int         wait(int block=1);

    int                  getNumThreads() const { return myThreadCount; }
    UT_Thread           *getThread(int which);
    UT_Thread           *operator[](int which)
                         {
                             UT_ASSERT_P(which < myThreadCount);
                             return myThreads[which];
                         }

protected:
    int           myThreadCount;
    UT_Thread   **myThreads;
    UTthreadFunc  myFunc;
    void         *myUserData;
    int64         myUserDataInc;
};

class UT_API UT_ThreadFarm
{
public:
    // similar to UT_ThreadSet, but a bit simpler. Called UT_ThreadFarm
    // because it farms out the next available thread. You also don't need to
    // match the number of data chunks to the number of threads.
    // ie.
    // farm = new UT_ThreadFarm(4);
    // while(!done) {
    //     thread = farm->nextThread();
    //     thread->startThread(entrypoint, mydata);
    // }
    // farm->wait();
    
     UT_ThreadFarm(int nthreads=-1);
    ~UT_ThreadFarm();

    // waits for the next available thread, (or returns null if none are
    // available and block = 0). thread_index will contain the thread index
    // if you pass it a non-null pointer.
    UT_Thread   *nextThread(int *thread_index =0,int block = 1);

    // waits until all threads are finished (or, returns 0 if not finished and
    // block = 0).
    int          wait(int block = 1);

    int          getEntries() const     { return myThreadCount; }
    
protected:
    int           myThreadCount;
    UT_Thread   **myThreads;
};

static inline int
UTgetSTID()
{
    return UT_Thread::getMySequentialThreadIndex();
}

#endif

---