Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages   Examples  

vpr::ThreadNSPR Class Reference

Threads implementation using the NSPR API. More...

#include <ThreadNSPR.h>

Inheritance diagram for vpr::ThreadNSPR:

Inheritance graph
[legend]
Collaboration diagram for vpr::ThreadNSPR:

Collaboration graph
[legend]
List of all members.

Public Methods

 ThreadNSPR (VPRThreadPriority priority=VPR_PRIORITY_NORMAL, VPRThreadScope scope=VPR_GLOBAL_THREAD, VPRThreadState state=VPR_JOINABLE_THREAD, PRUint32 stack_size=0)
 Non-spawning constructor. More...

 ThreadNSPR (thread_func_t func, void *arg=NULL, VPRThreadPriority priority=VPR_PRIORITY_NORMAL, VPRThreadScope scope=VPR_GLOBAL_THREAD, VPRThreadState state=VPR_JOINABLE_THREAD, PRUint32 stack_size=0)
 Spawning constructor. More...

 ThreadNSPR (BaseThreadFunctor *functor_ptr, VPRThreadPriority priority=VPR_PRIORITY_NORMAL, VPRThreadScope scope=VPR_GLOBAL_THREAD, VPRThreadState state=VPR_JOINABLE_THREAD, PRUint32 stack_size=0)
 Spawning constructor (functor version). More...

virtual ~ThreadNSPR ()
 Destructor. More...

virtual void setFunctor (BaseThreadFunctor *functorPtr)
 Sets the functor that this thread will execute. More...

virtual vpr::ReturnStatus start ()
 Creates a new thread that will execute this thread's functor. More...

virtual int join (void **status=NULL)
 Makes the calling thread wait for the termination of this thread. More...

virtual int resume ()
 Resumes the execution of a thread that was previously suspended using suspend(). More...

virtual int suspend ()
 Suspends the execution of this thread. More...

virtual int getPrio (VPRThreadPriority *prio)
 Gets this thread's priority. More...

virtual int setPrio (VPRThreadPriority prio)
 Sets this thread's priority. More...

virtual int kill (int signum)
 Sends the specified signal to this thread (not necessarily SIGKILL). More...

virtual void kill ()
 Kills (cancels) this thread. More...

virtual std::ostream & outStream (std::ostream &out)
 Provides a way of printing the process ID neatly. More...


Static Public Methods

BaseThread * self (void)
 Gets a pointer to the thread we are in. More...

void yield (void)
 Yields execution of the calling thread to allow a different blocked thread to execute. More...

Detailed Description

Threads implementation using the NSPR API.

Definition at line 75 of file ThreadNSPR.h.

Constructor & Destructor Documentation

vpr::ThreadNSPR::ThreadNSPR (  VPRThreadPriority    priority = VPR_PRIORITY_NORMAL,
VPRThreadScope    scope = VPR_GLOBAL_THREAD,
VPRThreadState    state = VPR_JOINABLE_THREAD,
PRUint32    stack_size = 0
) 
 

Non-spawning constructor.

This will not start a thread.

Definition at line 59 of file ThreadNSPR.cpp. 

00061    : mThread(NULL), mUserThreadFunctor(NULL), mPriority(priority),
00062      mScope(scope), mState(state), mStackSize(stackSize)
00063 {
00064 }

vpr::ThreadNSPR::ThreadNSPR (  thread_func_t    func,
void *    arg = NULL,
VPRThreadPriority    priority = VPR_PRIORITY_NORMAL,
VPRThreadScope    scope = VPR_GLOBAL_THREAD,
VPRThreadState    state = VPR_JOINABLE_THREAD,
PRUint32    stack_size = 0
) 
 

Spawning constructor.

This will start a new thread that will execute the specified function.

Definition at line 68 of file ThreadNSPR.cpp.

References setFunctor, start, and vpr::thread_func_t. 

00071    : mThread(NULL), mUserThreadFunctor(NULL), mPriority(priority),
00072      mScope(scope), mState(state), mStackSize(stackSize)
00073 {
00074    // XXX: Memory leak.
00075    setFunctor(new ThreadNonMemberFunctor(func, arg));
00076    start();
00077 }

vpr::ThreadNSPR::ThreadNSPR (  BaseThreadFunctor *    functor_ptr,
VPRThreadPriority    priority = VPR_PRIORITY_NORMAL,
VPRThreadScope    scope = VPR_GLOBAL_THREAD,
VPRThreadState    state = VPR_JOINABLE_THREAD,
PRUint32    stack_size = 0
) 
 

Spawning constructor (functor version).

This will start a new thread that will execute the specified functor.

Definition at line 81 of file ThreadNSPR.cpp.

References setFunctor, and start. 

00084    : mThread(NULL), mUserThreadFunctor(NULL), mPriority(priority),
00085      mScope(scope), mState(state), mStackSize(stackSize)
00086 {
00087    setFunctor(functorPtr);
00088    start();
00089 }

vpr::ThreadNSPR::~ThreadNSPR (    )  [virtual]
 

Destructor.

Precondition:
None.
Postcondition:
This thread is removed from the thread table and from the local thread hash.

Definition at line 92 of file ThreadNSPR.cpp. 

00093 {
00094    ;
00095 }

Member Function Documentation

void vpr::ThreadNSPR::setFunctor (  BaseThreadFunctor *    functorPtr )  [virtual]
 

Sets the functor that this thread will execute.

Precondition:
The thread is not already running. The functor is valid.

Implements vpr::BaseThread.

Definition at line 97 of file ThreadNSPR.cpp.

References vprASSERT.

Referenced by ThreadNSPR. 

00098 {
00099    vprASSERT(mThread == NULL && "Thread already running");
00100    vprASSERT(functorPtr->isValid());
00101 
00102    mUserThreadFunctor = functorPtr;
00103 }

vpr::ReturnStatus vpr::ThreadNSPR::start (    )  [virtual]
 

Creates a new thread that will execute this thread's functor.

Precondition:
The functor to execute has been set. The thread is not already running.
Postcondition:
A thread (with any specified attributes) is created that begins executing our functor. Depending on the scheduler, it may begin execution immediately, or it may block for a short time before beginning execution.
Returns:
A vpr::ReturnStatus obj is returned to indicate the result of the thread creation.

Implements vpr::BaseThread.

Definition at line 106 of file ThreadNSPR.cpp.

References vpr::CondVarNSPR::acquire, vpr::ReturnStatus::Fail, vpr::BaseThread::getTID, vpr::NSPR_PrintError, vpr::BaseThread::registerThread, vpr::CondVarNSPR::release, vpr::ReturnStatus::setCode, vpr::ReturnStatus::Succeed, vprASSERT, vpr::vprThreadFunctorFunction, and vpr::CondVarNSPR::wait.

Referenced by ThreadNSPR. 

00107 {
00108    vpr::ReturnStatus status;
00109 
00110    if ( NULL != mThread )
00111    {
00112       vprASSERT(false && "Thread already running");
00113       status.setCode(vpr::ReturnStatus::Fail);
00114    }
00115    else if ( NULL == mUserThreadFunctor )
00116    {
00117       vprASSERT(false && "No functor set");
00118       status.setCode(vpr::ReturnStatus::Fail);
00119    }
00120    else
00121    {
00122       PRThreadPriority nspr_prio;
00123       PRThreadScope nspr_scope;
00124       PRThreadState nspr_state;
00125 
00126       nspr_prio  = vprThreadPriorityToNSPR(mPriority);
00127       nspr_scope = vprThreadScopeToNSPR(mScope);
00128       nspr_state = vprThreadStateToNSPR(mState);
00129 
00130       vprASSERT(mUserThreadFunctor->isValid());
00131 
00132       // Store the member functor and create the functor for spawning to our
00133       // start routine.
00134       // XXX: Memory leak.
00135       ThreadMemberFunctor<ThreadNSPR>* start_functor =
00136             new ThreadMemberFunctor<ThreadNSPR>(this, &ThreadNSPR::startThread,
00137                                                 NULL);
00138 
00139       // Finally create the thread.
00140       // - On success --> The start method registers the actual thread info
00141       mThreadStartCompleted = false;      // Initialize registration flag (uses cond var for this)
00142       PRThread* ret_thread = PR_CreateThread(PR_USER_THREAD, vprThreadFunctorFunction,
00143                                 (void*) start_functor, nspr_prio, nspr_scope,
00144                                 nspr_state, (PRUint32) mStackSize);
00145 
00146       // Inform the caller if the thread was not created successfully.
00147       if ( NULL == ret_thread )
00148       {
00149          ThreadManager::instance()->lock();
00150          {
00151             registerThread(false);
00152          }
00153          ThreadManager::instance()->unlock();
00154 
00155          NSPR_PrintError("vpr::ThreadNSPR::spawn() - Cannot create thread");
00156          status.setCode(vpr::ReturnStatus::Fail);
00157       }
00158       else
00159       {
00160          // start thread will register the thread, so let's wait for it
00161          // -- Wait for registration to complete
00162          mThreadStartCondVar.acquire();
00163          {
00164             while ( !mThreadStartCompleted )    // While not desired state (ie. register completed)
00165             { mThreadStartCondVar.wait();}
00166          }
00167          mThreadStartCondVar.release();
00168          // ASSERT: Thread has completed registration
00169          vprASSERT(NULL != mThread && "Thread registration failed");
00170          vprASSERT(-1 != getTID() && "Thread id is invalid for successful thread");
00171 
00172          // Set the return code to success
00173          status.setCode(vpr::ReturnStatus::Succeed);
00174       }
00175    }
00176 
00177    return status;
00178 }

int vpr::ThreadNSPR::join (  void **    status = NULL )  [virtual]
 

Makes the calling thread wait for the termination of this thread.

Precondition:
None.
Postcondition:
The caller blocks until this thread finishes its execution (i.e., finishes its root function). This routine may return immediately if this thread has already exited.
Returns:
0 is returned upon successful completion. -1 is returned if an error occurred.

Reimplemented from vpr::BaseThread.

Definition at line 180 of file ThreadNSPR.cpp. 

00181 {
00182    boost::ignore_unused_variable_warning(status);
00183    return PR_JoinThread(mThread);
00184 }

virtual int vpr::ThreadNSPR::resume (  void    )  [inline, virtual]
 

Resumes the execution of a thread that was previously suspended using suspend().

Precondition:
This thread was previously suspended using the suspend() member function.
Postcondition:
This thread is sent the SIGCONT signal and is allowed to begin executing again.
Returns:
0 is returned upon successful completion. -1 is returned if an error occurred.

Reimplemented from vpr::BaseThread.

Definition at line 160 of file ThreadNSPR.h. 

00161    {
00162 //        return kill(SIGCONT);
00163       return -1;
00164    }

virtual int vpr::ThreadNSPR::suspend (  void    )  [inline, virtual]
 

Suspends the execution of this thread.

Precondition:
None.
Postcondition:
This thread is sent the SIGSTOP signal and is thus suspended from execution until the member function resume() is called.
Returns:
0 is returned upon successful completion. -1 is returned if an error occurred.

Reimplemented from vpr::BaseThread.

Definition at line 176 of file ThreadNSPR.h. 

00177    {
00178 //        return kill(SIGSTOP);
00179       return -1;
00180    }

virtual int vpr::ThreadNSPR::getPrio (  VPRThreadPriority *    prio )  [inline, virtual]
 

Gets this thread's priority.

Precondition:
This is a valid thread.
Postcondition:
The priority of this thread is returned in the integer pointer variable.
Parameters:
prio  Pointer to an int variable that will have the thread's priority stored in it.
Returns:
0 is returned upon successful completion. -1 is returned if an error occurred.

Reimplemented from vpr::BaseThread.

Definition at line 195 of file ThreadNSPR.h. 

00196    {
00197       *prio = nsprThreadPriorityToVPR(PR_GetThreadPriority(mThread));
00198 
00199       return 0;
00200    }

int vpr::ThreadNSPR::setPrio (  VPRThreadPriority    prio )  [virtual]
 

Sets this thread's priority.

Precondition:
None.
Postcondition:
This thread has its priority set to the specified value.
Parameters:
prio  The new priority for this thread.
Returns:
0 is returned upon successful completion. -1 is returned if an error occurred.
Note:
The priority must correspond to a value in the PRThreadPriority enumerated type.

Reimplemented from vpr::BaseThread.

Definition at line 235 of file ThreadNSPR.cpp. 

00236 {
00237    int retval(0);
00238 
00239    if ( prio > 3 )
00240    {
00241       retval = -1;
00242    }
00243    else
00244    {
00245       PR_SetThreadPriority(mThread, vprThreadPriorityToNSPR(prio));
00246    }
00247 
00248    return retval;
00249 }

virtual int vpr::ThreadNSPR::kill (  int    signum )  [inline, virtual]
 

Sends the specified signal to this thread (not necessarily SIGKILL).

Precondition:
None.
Postcondition:
This thread receives the specified signal.
Parameters:
signum  The signal to send to the specified thread.
Returns:
0 is returned upon successful completion. -1 is returned if an error occurred.

Reimplemented from vpr::BaseThread.

Definition at line 229 of file ThreadNSPR.h. 

00230    {
00231       boost::ignore_unused_variable_warning(signum);
00232       return -1;
00233    }

virtual void vpr::ThreadNSPR::kill (    )  [inline, virtual]
 

Kills (cancels) this thread.

Precondition:
None.
Postcondition:
This thread is cancelled. Depending on the cancellation attributes of the specified thread, it may terminate immediately, it may wait until a pre-defined cancel point to stop or it may ignore the cancel altogether. Thus, immediate cancellation is not guaranteed.
Note:
For the sake of clarity, it is probably better to use the cancel() routine instead of kill() because a two-argument version of kill() is also used for sending signals to threads. This kill() and cancel() do exactly the same thing.

Reimplemented from vpr::BaseThread.

Definition at line 250 of file ThreadNSPR.h. 

00251    {
00252    }

BaseThread * vpr::ThreadNSPR::self (  void    )  [static]
 

Gets a pointer to the thread we are in.

Returns:
NULL - Thread is not in global table NonNull - Ptr to the thread that we are running within

Definition at line 186 of file ThreadNSPR.cpp.

References vpr::BaseThread::BaseThread, and vprASSERT. 

00187 {
00188    vprASSERT((statics.mStaticsInitialized==1221) && "Trying to call vpr::ThreadNSPR::self before statics are initialized. Don't do that");
00189 
00190    BaseThread* my_thread;
00191    threadIdKey().getspecific((void**)&my_thread);
00192 
00193    return my_thread;
00194 }

void vpr::ThreadNSPR::yield (  void    )  [inline, static]
 

Yields execution of the calling thread to allow a different blocked thread to execute.

Precondition:
None.
Postcondition:
The caller yields its execution control to another thread or process.

Definition at line 270 of file ThreadNSPR.h. 

00271    {
00272       PR_Sleep(PR_INTERVAL_NO_WAIT);
00273    }

virtual std::ostream& vpr::ThreadNSPR::outStream (  std::ostream &    out )  [inline, virtual]
 

Provides a way of printing the process ID neatly.

Reimplemented from vpr::BaseThread.

Definition at line 278 of file ThreadNSPR.h. 

00279    {
00280       out.setf(std::ios::right);
00281       out << std::setw(7) << std::setfill('0') << getpid() << "/";
00282       out.unsetf(std::ios::right);
00283       BaseThread::outStream(out);
00284       out << std::setfill(' ');
00285       return out;
00286    }

The documentation for this class was generated from the following files:
Generated on Sun May 2 14:47:02 2004 for VR Juggler Portable Runtime by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002