thread.h

radius协议源码÷The Radius Stack will connect to a Radius Server. This stack implementation is built upo

       If #susp# is TRUE this increments an internal count of
       suspensions that must be matched by an equal number of calls to
       #Resume()# or #Suspend(FALSE)# before the
       thread actually executes again.

       If #susp# is FALSE then this decrements the internal count of
       suspensions. If the count is <= 0 then the thread will run. Note that
       the thread will not be suspended until an equal number of
       #Suspend(TRUE)# calls are made.
     */
    virtual void Suspend(
      BOOL susp = TRUE    /// Flag to suspend or resume a thread.
    );

    /** Resume thread execution, this is identical to
       #Suspend(FALSE)#.
     */
    virtual void Resume();

    /** Determine if the thread is currently suspended. This checks the
       suspension count and if greater than zero returns TRUE for a suspended
       thread.

       @return
       TRUE if thread is suspended.
     */
    virtual BOOL IsSuspended() const;

    /// Suspend the current thread for the specified amount of time.
    virtual void Sleep(
      const PTimeInterval & delay   /// Time interval to sleep for.
    );

    /** Set the priority of the thread relative to other threads in the current
       process.
     */
    virtual void SetPriority(
      Priority priorityLevel    /// New priority for thread.
    );

    /** Get the current priority of the thread in the current process.

       @return
       current thread priority.
     */
    virtual Priority GetPriority() const;

    /** Get the name of the thread. Thread names are a optional debugging aid.

       @return
       current thread name.
     */
    virtual PString GetThreadName() const;

    /** Change the name of the thread. Thread names are a optional debugging aid.

       @return
       current thread name.
     */
    virtual void SetThreadName(
      const PString & name        /// New name for the thread.
    );
  //@}

  /**@name Miscellaneous */
  //@{
    /** User override function for the main execution routine of the thread. A
       descendent class must provide the code that will be executed in the
       thread within this function.
       
       Note that the correct way for a thread to terminate is to return from
       this function.
     */
    virtual void Main() = 0;

    /** Get the currently running thread object instance. It is possible, even
       likely, that the smae code may be executed in the context of differenct
       threads. Under some circumstances it may be necessary to know what the
       current codes thread is and this static function provides that
       information.

       @return
       pointer to current thread.
     */
    static PThread * Current();

    /** Yield to another thread. If there are no other threads then this
       function does nothing. Note that on most platforms the threading is
       cooperative and this function must be called for other threads to run
       at all. There may be an implicit call to Yield within the I/O functions
       of #PChannel# classes. This is so when a thread is I/O blocked then
       other threads can, as far as possible, continue to run.
       
       If the platform directly supports multiple threads then this function
       will do nothing.
     */
    static void Yield();
  //@}

  protected:
    void InitialiseProcessThread();
    /* Initialialise the primordial thread, the one in the PProcess. This is
       required due to the bootstrap logic of processes and threads.
     */

#ifndef P_PLATFORM_HAS_THREADS
    virtual BOOL IsNoLongerBlocked();
    /* Check if the condition that has blocked a thread in an I/O function,
       for example, has ceased. This is required by the internal cooperative
       thread scheduler.

       This function is not present for platforms that support threads.
       
       <H2>Returns:</H2>
       TRUE if the thread is no longer blocked.
     */
#endif

  private:
    PThread();
    // Create a new thread instance as part of a PProcess class.

    friend class PProcess;
    // So a PProcess can get at PThread() constructor but nothing else.

    PThread(const PThread &) { }
    // Empty constructor to prevent copying of thread instances.

    PThread & operator=(const PThread &) { return *this; }
    // Empty assignment operator to prevent copying of thread instances.

    BOOL autoDelete;
    // Automatically delete the thread on completion.

    // Give the thread a name for debugging purposes.
    PString threadName;

#ifndef P_PLATFORM_HAS_THREADS
    void AllocateStack(
      PINDEX stackSize  // Size of the stack to allocate.
    );
    /* Allocate the stack for the thread.

       The stack size specified is {\bf not} simply in bytes. It is a value
       that is multiplied by a factor into bytes depending on the target
       platform. For example a Unix system with a RISC processor may use
       significantly more stack than an MS-DOS platform. These sizes are
       normalised to the "stack factor" provided here. For some platforms, eg
       Windows NT, the stack size is only an initial size and the stack will
       automatically be increased as required.

       This function is not present for platforms that support threads.
     */

    void ClearBlock();
    /* Clear the blocked thread. This is used by platform dependent code to
       signal to the common code scheduler that the thread is no longer
       blocked.

       This function is not present for platforms that support threads.
     */

    void BeginThread();
    /* Function to start #Main()# and exit when completed.

       This function is not present for platforms that support threads.
     */

    virtual void SwitchContext(
      PThread * from    // Thread being switched from.
    );
    /* Do the machinations needed to jump to the current thread. This is a
       platform dependent function that utilises the standard C
       #setjmp()# and #longjmp()# functions to implement
       the co-routines.
    
       This function is not present for platforms that support threads.
     */


    // Member fields
    Priority basePriority;
    /* The threads priority level, relative to other threads.

       This variable is not present for platforms that support threads.
     */

    int dynamicPriority;
    /* The threads priority during this scheduled slice. A thread that has not
       been scheduled has its dynamic priority increased so that next time
       the scheduler is looking for a thread to run it has a better chance of
       executing. Once a thread is executed the dynamic priority is set back
       to the base priority as set by #SetPriority()#.

       This variable is not present for platforms that support threads.
     */

    int suspendCount;
    /* The threads count of calls to #Suspend()# or #Resume()#.
       If <=0 then can run, if >0 means suspended and is not to be scheduled.

       This variable is not present for platforms that support threads.
     */

    PTimer sleepTimer;
    /* Time for thread to remain asleep. Thread is not scheduled while this
       is running after a #Sleep()# call.

       This variable is not present for platforms that support threads.
     */

    PSemaphore * blockingSemaphore;
    /* Semaphore that is blocking this thread.

       This variable is not present for platforms that support threads.
     */

    PThread * link;
    /* Link to next thread in circular list. The use of a list rather than
       priority queues or other sophisticated task queuing technique is to
       simplify the scheduler. It is expected that any given process will not
       have a large number of threads, ie less than approximately ten, so the
       overhead of the list search is small in comparison to the overhead in
       complex data structures.

       This variable is not present for platforms that support threads.
     */

    enum {
      Starting,         // Thread is starting up.
      Running,          // Thread is the currently executing context.
      Waiting,          // Thread is waiting to be scheduled.
      Sleeping,         // Thread is sleeping until sleepTimer is up.
      Suspended,        // Thread is currently suspended.
      BlockedIO,        // Thread is currently blocked in I/O.
      SuspendedBlockIO, // Thread is blocked {\bf and} suspended.
      BlockedSem,       // Thread is currently blocked by a semaphore.
      SuspendedBlockSem,// Thread is blocked {\bf and} suspended.
      Terminating,      // Thread is terminating but has not died yet.
      Terminated        // Thread has terminated.
    } status;
    /* Thread status for scheduler handling.

       This variable is not present for platforms that support threads.
     */

    jmp_buf context;
    /* Buffer for context switching.

       This variable is not present for platforms that support threads.
     */

    char PSTATIC * stackBase;
    /* Base of stack allocated for the thread. The PSTATIC is for DOS-Windows.

       This variable is not present for platforms that support threads.
     */

    char PSTATIC * stackTop;
    /* Top of stack allocated for the thread.

       This variable is not present for platforms that support threads.
     */


    friend class PSemaphore;
#endif

#ifdef DOC_PLUS_PLUS
};
#endif

// Class declaration continued in platform specific header file ///////////////