.\".\" Edited by I.J.Wang, 2004.\".TH Wy_Thread 3wy "libwy v0.31".SH NAMEWy_Thread \- class to handle thread.SH SYNOPSIS.B #include <wy_thread.h>.PPWy_Thread is the class that the member tmain() can be run in a created thread..PPNote: 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..PPImplementation 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 NOTEProject is in development, http://sourceforge.net/projects/libwx