Thread

/* -*-c++-*- OpenThreads library, Copyright (C) 2002 - 2007  The Open Thread Group
 *
 * This library is open source and may be redistributed and/or modified under  
 * the terms of the OpenSceneGraph Public License (OSGPL) version 0.0 or 
 * (at your option) any later version.  The full license is in LICENSE file
 * included with this distribution, and on the openscenegraph.org website.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
 * OpenSceneGraph Public License for more details.
*/


//
// Thread - C++ Thread class
// ~~~~~~~~
//

#ifndef _OPENTHREADS_THREAD_
#define _OPENTHREADS_THREAD_

#include <sys/types.h>

#include <OpenThreads/Mutex>

namespace OpenThreads {

/**
 *  Get the number of processors.
 *
 *  Note, systems where no support exists for querrying the number of processors, 1 is returned. 
 *
 */
extern OPENTHREAD_EXPORT_DIRECTIVE int GetNumberOfProcessors();

/**
 *  Set the processor affinity of current thread.
 *
 *  Note, systems where no support exists no affinity will be set, and -1 will be returned. 
 *
 */
extern OPENTHREAD_EXPORT_DIRECTIVE int SetProcessorAffinityOfCurrentThread(unsigned int cpunum);

/**
 *  @class Thread
 *  @brief  This class provides an object-oriented thread interface.
 */
class OPENTHREAD_EXPORT_DIRECTIVE Thread {

public:

    /**
     *  Set the concurrency level for a running application.  This method
     *  only has effect if the pthreads thread model is being used, and
     *  then only when that model is many-to-one (eg. irix).
     *  in other cases it is ignored.  The concurrency level is only a
     *  *hint* as to the number of execution vehicles to use, the actual
     *  implementation may do anything it wants.  Setting the value
     *  to 0 returns things to their default state.
     *
     *  @return previous concurrency level, -1 indicates no-op.
     */
    static int SetConcurrency(int concurrencyLevel);

    /**
     *  Get the concurrency level for a running application.  In this
     *  case, a return code of 0 means that the application is in default
     *  mode.  A return code of -1 means that the application is incapable
     *  of setting an arbitrary concurrency, because it is a one-to-one
     *  execution model (sprocs, linuxThreads)
     */
    static int GetConcurrency();

    /**
     *  Enumerated Type for thread priority
     */
    enum ThreadPriority {

	THREAD_PRIORITY_MAX,      /**< The maximum possible priority  */
	THREAD_PRIORITY_HIGH,     /**< A high (but not max) setting   */
	THREAD_PRIORITY_NOMINAL,  /**< An average priority            */
	THREAD_PRIORITY_LOW,      /**< A low (but not min) setting    */
	THREAD_PRIORITY_MIN,      /**< The miniumum possible priority */
	THREAD_PRIORITY_DEFAULT   /**< Priority scheduling default    */

    };

    /**
     *  Enumerated Type for thread scheduling policy
     */
    enum ThreadPolicy {

	THREAD_SCHEDULE_FIFO,        /**< First in, First out scheduling         */
	THREAD_SCHEDULE_ROUND_ROBIN, /**< Round-robin scheduling (LINUX_DEFAULT) */
	THREAD_SCHEDULE_TIME_SHARE,  /**< Time-share scheduling (IRIX DEFAULT)   */
	THREAD_SCHEDULE_DEFAULT      /**< Default scheduling                     */

    };

    /**
     *  Constructor
     */
    Thread();

    /**
     *  Destructor
     */
    virtual ~Thread();


    /**
     *  Return a pointer to the current running thread
     */
    static Thread *CurrentThread();


    /**
     *  Initialize Threading in a program.  This method must be called before
     *  you can do any threading in a program.
     */
    static void Init();

    /**
     *  Yield the processor.
     *
     *  @note This method operates on the calling process.  And is
     *  equivalent to calling sched_yield().
     *
     *  @return 0 if normal, -1 if errno set, errno code otherwise.
     */
    static int YieldCurrentThread();

    /**
     *  This method will return the ThreadPriority of the master process.
     *  (ie, the one calling the thread->start() methods for the first time)
     *  The method will almost certainly return
     *  Thread::THREAD_PRIORITY_DEFAULT if
     *  Init() has not been called.
     *
     *  @return the Thread::ThreadPriority of the master thread.
     */
    static ThreadPriority GetMasterPriority() {return s_masterThreadPriority;};


    /**
     *  Get a unique thread id.  This id is monotonically increasing.
     *
     *  @return a unique thread identifier
     */
    int getThreadId();

    /**
     *  Get the thread's process id.  This is the pthread_t or pid_t value
     *  depending on the threading model being used.
     *
     *  @return thread process id.
     */
    size_t getProcessId();

    /**
     *  Start the thread.  This method will configure the thread, set
     *  it's priority, and spawn it.
     *
     *  @note if the stack size specified setStackSize is smaller than the
     *  smallest allowable stack size,  the threads stack size will be set to
     *  the minimum allowed, and may be retrieved via the getStackSize()
     *
     *  @return 0 if normal, -1 if errno set, errno code otherwise.
     */
    int start();
    int startThread();

    /**
     * Test the cancel state of the thread.  If the thread has been canceled
     * this method will cause the thread to exit now.  This method operates
     * on the calling thread.
     *
     * Returns 0 if normal, -1 if called from a thread other that this.
     */
    int testCancel();


    /**
     *  Cancel the thread.  Equivalent to SIGKILL.
     *
     *  @return 0 if normal, -1 if errno set, errno code otherwise.
     */
    virtual int cancel();

    /**
     *  Set the thread's schedule priority.  This is a complex method.
     *  Beware of thread priorities when using a many-to-many kernel
     *  entity implemenation (such as IRIX pthreads).  If one is not carefull
     *  to manage the thread priorities, a priority inversion deadlock can
     *  easily occur (Although the OpenThreads::Mutex & OpenThreads::Barrier
     *  constructs have been designed with this senario in mind).  Unless
     *  you have explicit need to set the schedule pirorites for a given
     *  task, it is best to leave them alone.
     *
     *  @note some implementations (notably LinuxThreads and IRIX Sprocs)
     *  only alow you to decrease thread priorities dynamically.  Thus,
     *  a lower priority thread will not allow it's priority to be raised
     *  on the fly.
     *
     *  @note seting the environment variable OUTPUT_THREADLIB_SCHEDULING_INFO
     *  will output scheduling information for each thread to stdout.
     *
     *  @return 0 if normal, -1 if errno set, errno code otherwise.
     */
    int setSchedulePriority(ThreadPriority priority);

    /**
     *  Get the thread's schedule priority (if able)
     *
     *  @note seting the environment variable OUTPUT_THREADLIB_SCHEDULING_INFO
     *  will output scheduling information for each thread to stdout.
     *
     *  @return 0 if normal, -1 if errno set, errno code otherwise.
     */
    int getSchedulePriority();

    /**
     *  Set the thread's scheduling policy (if able)
     *
     *  @note On some implementations (notably IRIX Sprocs & LinuxThreads)
     *  The policy may prohibit the use of SCHEDULE_ROUND_ROBIN and
     *  SCHEDULE_FIFO policies - due to their real-time nature, and
     *  the danger of deadlocking the machine when used as super-user.
     *  In such cases, the command is a no-op.
     *
     *  @note seting the environment variable OUTPUT_THREADLIB_SCHEDULING_INFO
     *  will output scheduling information for each thread to stdout.
     *
     *  @return 0 if normal, -1 if errno set, errno code otherwise.
     */
    int setSchedulePolicy(ThreadPolicy policy);

    /**
     *  Get the thread's policy (if able)
     *
     *  @note seting the environment variable OUTPUT_THREADLIB_SCHEDULING_INFO
     *  will output scheduling information for each thread to stdout.
     *
     *  @return policy if normal, -1 if errno set, errno code otherwise.
     */
    int getSchedulePolicy();

    /**
     *  Set the thread's desired stack size (in bytes).
     *  This method is an attribute of the thread and must be called
     *  *before* the start() method is invoked.
     *
     *  @note a return code of 13 (EACESS) means that the thread stack
     *  size can no longer be changed.
     *
     *  @return 0 if normal, -1 if errno set, errno code otherwise.
     */
    int setStackSize(size_t size);

    /**
     *  Get the thread's desired stack size.
     *
     *  @return the thread's stack size.  0 indicates that the stack size
     *   has either not yet been initialized, or not yet been specified by
     *   the application.
     */
    size_t getStackSize();

    /**
     *  Print the thread's scheduling information to stdout.
     */
    void printSchedulingInfo();

    /**
     *  Detach the thread from the calling process.
     *
     *  @return 0 if normal, -1 if errno set, errno code otherwise.
     */
    int detach();

    /**
     *  Join the calling process with the thread
     *
     *  @return 0 if normal, -1 if errno set, errno code otherwise.
     */
    int join();

    /**
     *  Disable thread cancelation altogether. Thread::cancel() has no effect.
     *
     *  @return 0 if normal, -1 if errno set, errno code otherwise.
     */
    int setCancelModeDisable();

    /**
     *  Mark the thread to cancel aysncronously on Thread::cancel().
     *  (May not be available with process-level implementations).
     *
     *  @return 0 if normal, -1 if errno set, errno code otherwise.
     */
    int setCancelModeAsynchronous();

    /**
     *  Mark the thread to cancel at the earliest convenience on
     *  Thread::cancel() (This is the default)
     *
     *  @return 0 if normal, -1 if errno set, errno code otherwise.
     */
    int setCancelModeDeferred();

    /**
     *  Query the thread's running status
     *
     *  @return true if running, false if not.
     */
    bool isRunning();

    /**
     *  Thread's run method.  Must be implemented by derived classes.
     *  This is where the action happens.
     */
    virtual void run() = 0;

    /**
     *  Thread's cancel cleanup routine, called upon cancel(), after the
     *  cancelation has taken place, but before the thread exits completely.
     *  This method should be used to repair parts of the thread's data
     *  that may have been damaged by a pre-mature cancel.  No-op by default.
     */
    virtual void cancelCleanup() {};

    void* getImplementation(){ return _prvData;	};

    /** Thread's processor affinity method.  This binds a thread to a
      * processor whenever possible.   This call must be made before
      * start() or startThread() and has no effect after the thread
      * has been running.  In the pthreads implementation, this is only
      * implemented on sgi, through a pthread extension.  On other pthread
      * platforms this is ignored.  Returns 0 on success, implementation's
      * error on failure, or -1 if ignored.
      */
    int setProcessorAffinity( unsigned int cpunum );

    /** microSleep method, equivilant to the posix usleep(microsec).
      *  This is not strictly thread API but is used
      * so often with threads. It's basically UNIX usleep. Parameter is
      * number of microseconds we current thread to sleep. Returns 0 on
      * succes, non-zero on failure (UNIX errno or GetLastError() will give
      * detailed description.
      */
    static int microSleep( unsigned int microsec);

private:

    /**
     *  The Private Actions class is allowed to operate on private data.
     */
    friend class ThreadPrivateActions;

     /**
      *  Private copy constructor, to prevent tampering.
      */
    Thread(const Thread &/*t*/) {};

    /**
      *  Private copy assignment, to prevent tampering.
      */
    Thread &operator=(const Thread &/*t*/) {return *(this);};

    /**
     *  Implementation-specific data
     */
    void * _prvData;
    
    /**
     *  Master thread's priority, set by Thread::Init.
     */
    static ThreadPriority s_masterThreadPriority;

    /**
     *  Is initialized flag
     */
    static bool s_isInitialized;
};

}

#endif // !_OPENTHREADS_THREAD_