vpr::ThreadNSPR Class Reference

Threads implementation using the NSPR API. More...

#include <vpr/Thread/Thread.h>

Inheritance diagram for vpr::ThreadNSPR:

[legend]Collaboration diagram for vpr::ThreadNSPR:

[legend]List of all members.

Public Member Functions
	ThreadNSPR (VPRThreadPriority priority=VPR_PRIORITY_NORMAL, VPRThreadScope scope=VPR_GLOBAL_THREAD, VPRThreadState state=VPR_JOINABLE_THREAD, PRUint32 stack_size=0)
	Non-spawning constructor.
	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.
	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).
virtual	~ThreadNSPR ()
	Destructor.
virtual void	setFunctor (BaseThreadFunctor *functorPtr)
	Sets the functor that this thread will execute.
virtual vpr::ReturnStatus	start ()
	Creates a new thread that will execute this thread's functor.
virtual int	join (void **status=NULL)
	Makes the calling thread wait for the termination of this thread.
virtual int	resume ()
	Resumes the execution of a thread that was previously suspended using suspend().
virtual int	suspend ()
	Suspends the execution of this thread.
virtual int	getPrio (VPRThreadPriority *prio)
	Gets this thread's priority.
virtual int	setPrio (VPRThreadPriority prio)
	Sets this thread's priority.
virtual int	kill (int signum)
	Sends the specified signal to this thread (not necessarily SIGKILL).
virtual void	kill ()
	Kills (cancels) this thread.
virtual std::ostream &	outStream (std::ostream &out)
	Provides a way of printing the process ID neatly.
Static Public Member Functions
static Thread *	self ()
	Gets a pointer to the thread we are in.
static void	yield ()
	Yields execution of the calling thread to allow a different blocked thread to execute.
Classes
struct	staticWrapper

---

Detailed Description

Threads implementation using the NSPR API.

This works by recieving a function in the constructor that is the function to call when the new thread is created. The function is stored internally to the class, then the class is "boot-strapped" by spawning a call to the startThread() function with in turn will call the previously set thread function.

This is typedef'd to vpr::Thread.

Definition at line 83 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 60 of file ThreadNSPR.cpp.

   : mThread(NULL)
   , mUserThreadFunctor(NULL)
   , mDeleteFunctor(false)
   , mStartFunctor(NULL)
   , mPriority(priority)
   , mScope(scope)
   , mState(state)
   , mStackSize(stackSize)
{
}

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 75 of file ThreadNSPR.cpp.

References setFunctor(), and start().

   : mThread(NULL)
   , mUserThreadFunctor(NULL)
   , mDeleteFunctor(false)
   , mStartFunctor(NULL)
   , mPriority(priority)
   , mScope(scope)
   , mState(state)
   , mStackSize(stackSize)
{
   mDeleteFunctor = true;
   setFunctor(new ThreadNonMemberFunctor(func, arg));
   start();
}

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 94 of file ThreadNSPR.cpp.

References setFunctor(), and start().

   : mThread(NULL)
   , mUserThreadFunctor(NULL)
   , mDeleteFunctor(false)
   , mStartFunctor(NULL)
   , mPriority(priority)
   , mScope(scope)
   , mState(state)
   , mStackSize(stackSize)
{
   setFunctor(functorPtr);
   start();
}

vpr::ThreadNSPR::~ThreadNSPR

(

)

[virtual]

Destructor.

Postcondition:

This thread is removed from the thread table and from the local thread hash.

Definition at line 111 of file ThreadNSPR.cpp.

References vpr::BaseThread::unregisterThread().

{
   ThreadManager::instance()->lock();
   {
      unregisterThread();
   }
   ThreadManager::instance()->unlock();

   if ( NULL != mStartFunctor )
   {
      delete mStartFunctor;
      mStartFunctor = NULL;
   }

   if ( mDeleteFunctor )
   {
      delete mUserThreadFunctor;
      mUserThreadFunctor = NULL;
   }
}

---

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 132 of file ThreadNSPR.cpp.

References vpr::BaseThreadFunctor::isValid(), and vprASSERT.

Referenced by ThreadNSPR().

{
   vprASSERT(mThread == NULL && "Thread already running");
   vprASSERT(functorPtr->isValid());

   mUserThreadFunctor = functorPtr;
}

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 141 of file ThreadNSPR.cpp.

References vpr::CondVarNSPR::acquire(), vpr::ReturnStatus::Fail, vpr::BaseThread::getTID(), vpr::BaseThreadFunctor::isValid(), 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().

{
   vpr::ReturnStatus status;

   if ( NULL != mThread )
   {
      vprASSERT(false && "Thread already running");
      status.setCode(vpr::ReturnStatus::Fail);
   }
   else if ( NULL == mUserThreadFunctor )
   {
      vprASSERT(false && "No functor set");
      status.setCode(vpr::ReturnStatus::Fail);
   }
   else
   {
      PRThreadPriority nspr_prio;
      PRThreadScope nspr_scope;
      PRThreadState nspr_state;

      nspr_prio  = vprThreadPriorityToNSPR(mPriority);
      nspr_scope = vprThreadScopeToNSPR(mScope);
      nspr_state = vprThreadStateToNSPR(mState);

      vprASSERT(mUserThreadFunctor->isValid());

      // Store the member functor and create the functor for spawning to our
      // start routine.
      mStartFunctor = 
         new ThreadMemberFunctor<ThreadNSPR>(this, &ThreadNSPR::startThread,
                                             NULL);

      // Finally create the thread.
      // - On success --> The start method registers the actual thread info
      mThreadStartCompleted = false;      // Initialize registration flag (uses cond var for this)
      PRThread* ret_thread =
         PR_CreateThread(PR_USER_THREAD, vprThreadFunctorFunction,
                         (void*) mStartFunctor, nspr_prio, nspr_scope,
                         nspr_state, (PRUint32) mStackSize);

      // Inform the caller if the thread was not created successfully.
      if ( NULL == ret_thread )
      {
         ThreadManager::instance()->lock();
         {
            registerThread(false);
         }
         ThreadManager::instance()->unlock();

         NSPR_PrintError("vpr::ThreadNSPR::spawn() - Cannot create thread");
         status.setCode(vpr::ReturnStatus::Fail);
      }
      else
      {
         // start thread will register the thread, so let's wait for it
         // -- Wait for registration to complete
         mThreadStartCondVar.acquire();
         {
            // While not desired state (ie. register completed)
            while ( !mThreadStartCompleted )
            {
               mThreadStartCondVar.wait();
            }
         }
         mThreadStartCondVar.release();
         // ASSERT: Thread has completed registration
         vprASSERT(NULL != mThread && "Thread registration failed");
         vprASSERT(-1 != getTID() && "Thread id is invalid for successful thread");

         // Set the return code to success
         status.setCode(vpr::ReturnStatus::Succeed);
      }
   }

   return status;
}

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 218 of file ThreadNSPR.cpp.

{
   boost::ignore_unused_variable_warning(status);
   return PR_JoinThread(mThread);
}

virtual int vpr::ThreadNSPR::resume

(

)

[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 167 of file ThreadNSPR.h.

   {
//      return kill(SIGCONT);
      return -1;
   }

virtual int vpr::ThreadNSPR::suspend

(

void

)

[inline, virtual]

Suspends the execution of this thread.

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 182 of file ThreadNSPR.h.

   {
//      return kill(SIGSTOP);
      return -1;
   }

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.

Definition at line 201 of file ThreadNSPR.h.

   {
      *prio = nsprThreadPriorityToVPR(PR_GetThreadPriority(mThread));

      return 0;
   }

int vpr::ThreadNSPR::setPrio

(

VPRThreadPriority

prio

)

[virtual]

Sets this thread's priority.

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.

Definition at line 288 of file ThreadNSPR.cpp.

{
   int retval(0);

   if ( prio > 3 )
   {
      retval = -1;
   }
   else
   {
      PR_SetThreadPriority(mThread, vprThreadPriorityToNSPR(prio));
   }

   return retval;
}

virtual int vpr::ThreadNSPR::kill

(

int

signum

)

[inline, virtual]

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

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 233 of file ThreadNSPR.h.

   {
      boost::ignore_unused_variable_warning(signum);
      return -1;
   }

virtual void vpr::ThreadNSPR::kill

(

)

[inline, virtual]

Kills (cancels) this thread.

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 253 of file ThreadNSPR.h.

   {
   }

Thread * vpr::ThreadNSPR::self

(

)

[static]

Gets a pointer to the thread we are in.

Returns:

NULL is returned if this thread is not in global table.

A non-NULL value is the pointer to the thread that we are running within.

Definition at line 224 of file ThreadNSPR.cpp.

References vpr::ThreadKeyNSPR::getspecific(), and vprASSERT.

{
   vprASSERT((statics.mStaticsInitialized==1221) && "Trying to call vpr::ThreadNSPR::self before statics are initialized. Don't do that");

   Thread* my_thread;
   threadIdKey().getspecific((void**)&my_thread);

   return my_thread;
}

static void vpr::ThreadNSPR::yield

(

)

[inline, static]

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

Postcondition:

The caller yields its execution control to another thread or process.

Definition at line 273 of file ThreadNSPR.h.

   {
      PR_Sleep(PR_INTERVAL_NO_WAIT);
   }

virtual std::ostream& vpr::ThreadNSPR::outStream

(

std::ostream &

out

)

[virtual]

Provides a way of printing the process ID neatly.

Reimplemented from vpr::BaseThread.

---

The documentation for this class was generated from the following files:

• ThreadNSPR.h
• ThreadNSPR.cpp

---