wy_thread.3wy

一个不错

.\"
.\" Edited by I.J.Wang, 2004
.\"
.TH Wy_Thread 3wy "libwy v0.31"
.SH NAME
Wy_Thread \- class to handle thread
.SH SYNOPSIS
.B #include <wy_thread.h>
.PP
Wy_Thread is the class that the member tmain() can be run in a created thread.
.PP
Note: Classes and functions of this library are mostly not aimed for
      access by more than one thread concurrently except WyOnce,
      WyMutex, Wy_Thread and a few other functions. Functions or
      members are cancellation points if and only if they are 
      wrappers of documented C-library functions which are also
      cancellation points. Refer to "Programming with POSIX Thread"
      [David R. Butenhof, p147-148] for POSIX cancellation points.
.PP
Implementation Note:
      Wy_Thread is composed of pthread functions, thread detatch
      state cannot be modified.
      Current version is based on the C++ implement that cancellation
      and thread exit function will unwind the stack. Therefore, 
      function that contains cancellation points or uses
      Wy_Thread::exit should not have throw specification without
      cancellation disabled.
.PP
\fBBasic Usage\fP:

 1. Declare an object of the application class that inherits Wy_Thread
    and reimplements tmain() to run in the created thread.
 2. Call begin(), then tmain() is scheduled to run in a created thread.

 Example:
   #include <wytimespec.h>
   #include <wy_thread.h>
   #include <wy_uty.h>

   class Thread : public Wy_Thread {
       WyTimeSpec dtime;     // delay time

     public:
       Thread() : dtime("1.5") /*1.5 seconds*/ {};
       ~Thread() throw() {
         tmain_close();      // stop a possibly active thread
       };

     protected:
       WyRet tmain(void) {   // reimplement the default tmain()
         for(int i=0; i<5; ++i) {
           Wy::sleep(dtime);
           Wy::cerr << 'Z';
         }
         return(Ok);
       };
   };

   int main(void)
   try {
     WyRet r;
     Thread thrd;               // declare a Thread object
     if((r=thrd.begin())!=Ok) { // begin a new thread to run tmain()
       WY_THROW(r);
     }
     if((r=thrd.wait_not(Wy_Thread::Active))!=Ok) {
       WY_THROW(r);                                 
     }
     return(0);
   }
   catch(const WyRet& e) {
     Wy::cerr << Wy::wrd(e) << '\\n';
     throw;
   }
   catch(...) {
     Wy::cerr << "Unidentified throw object\\n";
     throw;
   };
.SH "PUBLIC MEMBERS"
 class \fBReply\fP : public WyRet
 enum ThreadState { \fBNull\fP, \fBActive\fP, \fBStopped\fP }
 enum CancelType { \fBDeferred\fP, \fBAsynchronous\fP }
 \fBWy_Thread\fP()
 virtual \fB~Wy_Thread\fP() throw()
 bool \fBis_default\fP(void) const
 Wy_ThreadID \fBthread_id\fP(void) const
 ThreadState \fBthread_state\fP(void) const
 WyRet \fBexitcode\fP(void) const
 virtual WyRet \fBreset\fP(void)
 virtual WyRet \fBbegin\fP(void)
 virtual WyRet \fBcancel\fP(void)
 virtual WyRet \fBwait_not\fP(ThreadState)

 static Wy_ThreadID \fBthread_self\fP(void)
 static WyRet \fByield\fP(void)
 static Wy_Thread* \fBtbase_ptr\fP(void)
 static bool \fBset_cancelable\fP(bool)
 static CancelType \fBset_canceltype\fP(CancelType)
 static void \fBcancel_point\fP(void)
 static void \fBexit\fP(WyRet)
 static size_t \fBactive_threads\fP(void)
 static size_t \fBmax_threads\fP(void) throw()
.SH "PROTECTED MEMBERS"
 virtual WyRet \fBtmain\fP(void)
 void \fBtmain_close\fP(void) throw()
.SH "DESCRIPTION"
.\"--------------------------------------------
.PP
.BI "class Reply : public WyRet"
.PP
    Class specific throw type
.\"--------------------------------------------
.PP
.BI "enum ThreadState"
           Null ...... No thread
           Active .... Thread is begun
           Stopped ... Thread terminated
.\"--------------------------------------------
.PP
.BI "enum CancelType"
           Deferred ....... cancel on cancellation point
           Asynchronous ... cancel as soon as requested
.\"--------------------------------------------
.PP
.BI "Wy_Thread()"
.PP
    Construct default object

      thread_state()= Null
      thread_id()   = Wy_ThreadID()
      exitcode()    = WyRet()
.PP
    [\fBThrow\fP] Reply
            Wym_ENOMEM      Not enough memory
.\"--------------------------------------------
.PP
.BI "virtual ~Wy_Thread() throw()"
.PP
    Destruct *this
.PP
    Note: If the thread is of Defered cancellation type, tmain()
          should make sure cancellation points are executed in a
          given time interval to avoid the destructor (or reset())
          waiting for indefinite time.

    Note: All destructor of the inheriting classes should stop an
          active thread from accessing the about-to-be-destroyed
          data members, \fBsee tmain_close\fP().
.\"--------------------------------------------
.PP
.BI "bool is_default(void) const"
.PP
    Is *this equivalent to the default object
.PP
    [\fBRet\fP] true= *this is equivalent to Wy_Thread().
         false= otherwise
.\"--------------------------------------------
.PP
.BI "Wy_ThreadID thread_id(void) const"
.PP
    Get the ID of the thread that runs tmain()
.PP 
    [\fBRet\fP] Wy_ThreadID, thread ID of tmain().
.\"--------------------------------------------
.PP
.BI "ThreadState thread_state(void) const"
.PP
    Get the thread state
.PP 
    [\fBRet\fP] enum ThreadSate of the following:
          Null ...... No thread
          Active .... Thread is begun
          Stopped ... Thread terminated
.\"--------------------------------------------
.PP
.BI "WyRet exitcode(void) const"
.PP
    Get the tmain() exit code.
.PP 
    [\fBRet\fP] WyRet that tmain() returned or exited with
          Default object gets default WyRet. The value is not
          defined if the thread is in Active state. If the 
          thread was cancelled, Wym_ETHRDCAN is returned.
.\"--------------------------------------------
.PP
.BI "virtual WyRet reset(void)"
.PP
    Reset *this to the state as Wy_Thread()

    The Active tmain() thread will get a cancel request. Function
    waits until the thread is terminated.

    Note: tmain() should not reset itself. Behavior in this illegal
          case is unspecified (implementation may throw WyRet)
.PP 
    [\fBRet\fP] Ok               Succeed
.\"--------------------------------------------
.PP
.BI "virtual WyRet begin(void)"
.PP
    Creates a thread to run tmain().

    The thread is created as if the following functions called:

    set_cancelable(true);
    set_canceltype(CancelType::Deferred);
.PP 
    [\fBRet\fP] Ok               Succeed. Thread is created and scheduled
                           to run tmain(). Thread state is Active.
          Wym_EBADF        Thread state is not Null
          Wym_ENFILE       active_threads() has reaches max_threads()
          Wym_EAGAIN       Not enough system resource
          Wym_ENOMEM       Not enough memory
.PP 
    [\fBRefer\fP] ::pthread_create
.\"--------------------------------------------
.PP
.BI "virtual WyRet cancel(void)"
.PP
    Send request to cancel(stop) the thread created.
.PP 
    [\fBRet\fP] Ok               Succeed. Cancel request is sent.
                           The thread may not be terminated yet.
          Wym_ESRCH        No thread found
          Wym_EPERM        tmain() can not cancel itself
.PP 
    [\fBRefer\fP] ::pthread_cancel
.\"--------------------------------------------
.PP
.BI "virtual WyRet wait_not(ThreadState " "state" ")"
.PP
    Wait until thread state is detected not \fIstate\fP
.PP 
    [\fBRet\fP] Ok               Succeed. thread state is not \fIstate\fP
          Wym_EPERM        tmain() cannot wait on itself
.PP 
    [\fBRefer\fP] ::pthread_cond_wait
.\"--------------------------------------------
.SH "PUBLIC STATIC MEMBERS"
.PP
.BI "static Wy_ThreadID thread_self(void)"
.PP
    Get the thread ID of the calling thread
.PP 
    [\fBRet\fP] Wy_ThreadID of the calling thread.
.PP 
    [\fBRefer\fP] ::pthread_self
.\"--------------------------------------------
.PP
.BI "static WyRet yield(void)"
.PP
    Try yielding for other threads to resume execution.
.PP 
    [\fBRet\fP] Ok               Succeed.
          ...              do not care for now
.PP 
    [\fBRefer\fP] ::sched_yield
.\"--------------------------------------------
.PP
.BI "static Wy_Thread* tbase_ptr(void)"
.PP
    Get the handling Wy_Thread object of the calling thread

    Note: This member is primarily for the function that is not
          a member of the reimplemented thread class. Cast the 
          returned pointer to the deriving thread class to access
          members of that class object.

    Note: Implementation searches internal tables, which may be 
          considered slow.
.PP 
    [\fBRet\fP] Pointer to the Wy_Thread object of the calling thread.
          NULL= the calling thread is not created by Wy_Thread
.\"--------------------------------------------
.PP
.BI "static bool set_cancelable(bool " "en" ")"
.PP
    Enable(\fIen\fP==true) or disable(\fIen\fP==false) the calling thread to
    respond to the cancel request
.PP 
    [\fBRet\fP] Previous cancellability of the calling thread.
          true = cancellable.
          false= not cancellable.
.PP 
    [\fBRefer\fP] ::pthread_setcancelstate
.\"--------------------------------------------
.PP
.BI "static CancelType set_canceltype(CancelType " "type" ")"
.PP
    Set the type of response to cancellation request

    Warning: Library functions and classes are mostly not 
             implemented for asynchronous type of cancellation.
             Users have to know the physical effect to use this
             type of cancellation.
.PP 
    [\fBRet\fP] Previous cancel type of the calling thread.
.PP 
    [\fBRefer\fP] ::pthread_setcanceltype
.\"--------------------------------------------
.PP
.BI "static void cancel_point(void)"
.PP
    Cancellation(Defered type) may take place in this function, 
    nothing is otherwise done.
.PP 
    [\fBRefer\fP] ::pthread_testcancel
.\"--------------------------------------------
.PP
.BI "static void exit(WyRet r)"
.PP
    Exit the calling thread (by stack unwind) and set exitcode as \fIr\fP
.PP 
    [\fBRefer\fP] ::pthread_exit
.\"--------------------------------------------
.PP
.BI "static size_t active_threads(void)"
.PP
    Get the number of threads in Active state(created by this class)
.PP 
    [\fBRet\fP] Number of active threads
.\"--------------------------------------------
.PP
.BI "static size_t max_threads(void) throw()"
.PP
    Get the maximum number of threads this class can create
.PP 
    [\fBRet\fP] The maximum number of threads this class can create
.\"--------------------------------------------
.SH "PROTECTED MEMBERS"
.PP
.BI "virtual WyRet tmain(void)"
.PP
    Reimplement this function to run the created thread
    The default function immediately returns WyRet(Ok)

    Note: tmain() is not allowed to use non-static members to
          manipulate itself (other threads are fine)
.\"--------------------------------------------
.PP
.BI "void tmain_close(void) throw()"
.PP
    Cancel the possibly active thread and disable cancellability
    of the calling thread. This member is supposedly called only
    in the destructor.

    Destructor of inheriting classes should stop the possibly active
    thread from accessing the about-to-be-destroyed data members.
   
    For example, definition of inheriting destructors would be like
    the following:

      class T : public Wy_Thread {
        public:
          ~T() {
            tmain_close();  // cancel active thread and disable
                            // cancellability of the destructor.
            ...             // others
          };
      };
.PP 
    [\fBRefer\fP] ::pthread_cancel
.\"--------------------------------------------
.SH "SEE ALSO"
.BR wyret
.BR wymutex
.BR wylock
.BR wycond
.BR wyonce
.BR wytimespec
.BR wy_threadid
.SH NOTE
Project is in development, http://sourceforge.net/projects/libwx