vpr::ThreadPosix Class Reference

Threads implementation using POSIX threads (both Draft 4 and the "final" draft of the standard are supported). More...

#include <vpr/Thread/Thread.h>

Inheritance diagram for vpr::ThreadPosix:

[legend]Collaboration diagram for vpr::ThreadPosix:

[legend]List of all members.

Public Member Functions
	ThreadPosix (VPRThreadPriority priority=VPR_PRIORITY_NORMAL, VPRThreadScope scope=VPR_GLOBAL_THREAD, VPRThreadState state=VPR_JOINABLE_THREAD, size_t stack_size=0)
	Non-spawning constructor.
	ThreadPosix (thread_func_t func, void *arg=NULL, VPRThreadPriority priority=VPR_PRIORITY_NORMAL, VPRThreadScope scope=VPR_GLOBAL_THREAD, VPRThreadState state=VPR_JOINABLE_THREAD, size_t stack_size=0)
	Spawning constructor with argument.
	ThreadPosix (BaseThreadFunctor *functorPtr, VPRThreadPriority priority=VPR_PRIORITY_NORMAL, VPRThreadScope scope=VPR_GLOBAL_THREAD, VPRThreadState state=VPR_JOINABLE_THREAD, size_t stack_size=0)
	Spawning constructor (functor version).
virtual	~ThreadPosix ()
	Destructor.
virtual void	setFunctor (BaseThreadFunctor *functorPtr)
	Sets the functor that this thread will execute.
virtual vpr::ReturnStatus	start ()
	Starts this thread's execution.
virtual int	join (void **status=0)
	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 (void)
	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	setRunOn (int cpu)
	Sets the CPU affinity for this thread (the CPU on which this thread will exclusively run).
virtual int	getRunOn (int *cur_cpu)
	Gets the CPU affinity for this thread (the CPU on which this thread exclusively runs).
virtual int	kill (int signum)
	Sends the specified signal to this thread (not necessarily SIGKILL).
virtual void	kill ()
	Kills (cancels) this thread.
std::ostream &	outStream (std::ostream &out)
	Provides a way of printing the process ID neatly.
Static Public Member Functions
static void	yield ()
	Yields execution of the calling thread to allow a different blocked thread to execute.
static Thread *	self ()
	Get a pointer to the thread we are in.
Protected Member Functions
vpr::ReturnStatus	spawn (BaseThreadFunctor *functorPtr)
	Creates a new thread that will execute functorPtr.
void	startThread (void *nullParam)
	Called by the spawn routine to start the user thread function.
Classes
struct	staticWrapper

---

Detailed Description

Threads implementation using POSIX threads (both Draft 4 and the "final" draft of the standard are supported).

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 ThreadPosix.h.

---

Constructor & Destructor Documentation

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

Non-spawning constructor.

This will not start a thread.

Definition at line 76 of file ThreadPosix.cpp.

   : mUserThreadFunctor(NULL)
   , mDeleteThreadFunctor(false)
   , mRunning(false)
   , mPriority(priority)
   , mScope(scope)
   , mState(state)
   , mStackSize(stackSize)
   , mThreadStartCompleted(false)
   , mStartFunctor(NULL)
{
   /* Do nothing. */ ;
}

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

Spawning constructor with argument.

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

Definition at line 93 of file ThreadPosix.cpp.

References setFunctor(), and start().

   : mUserThreadFunctor(NULL)
   , mDeleteThreadFunctor(false)
   , mRunning(false)
   , mPriority(priority)
   , mScope(scope)
   , mState(state)
   , mStackSize(stackSize)
   , mThreadStartCompleted(false)
   , mStartFunctor(NULL)
{
   // Create the thread functor to start.  This will be deleted in the
   // destructor.
   setFunctor(new ThreadNonMemberFunctor(func, arg));
   mDeleteThreadFunctor = true;
   start();
}

vpr::ThreadPosix::ThreadPosix	(	BaseThreadFunctor *	functorPtr,
		VPRThreadPriority	priority = VPR_PRIORITY_NORMAL,
		VPRThreadScope	scope = VPR_GLOBAL_THREAD,
		VPRThreadState	state = VPR_JOINABLE_THREAD,
		size_t	stack_size = 0
	)

Spawning constructor (functor version).

This will start a new thread that will execute the function encapsulated by the functor.

Definition at line 115 of file ThreadPosix.cpp.

References setFunctor(), and start().

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

vpr::ThreadPosix::~ThreadPosix

(

)

[virtual]

Destructor.

Postcondition:

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

Definition at line 133 of file ThreadPosix.cpp.

References vpr::BaseThread::unregisterThread().

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

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

   // TELL EVERYONE THAT WE'RE DEAD!!!!
   ThreadManager::instance()->lock();      // Lock manager
   {
      unregisterThread();                  // Finish thread deallocation
   }
   ThreadManager::instance()->unlock();
}

---

Member Function Documentation

void vpr::ThreadPosix::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 155 of file ThreadPosix.cpp.

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

Referenced by ThreadPosix().

{
   vprASSERT(! mRunning && "Thread already running.");
   vprASSERT(functorPtr->isValid() && "Invalid functor.");

   mUserThreadFunctor = functorPtr;
}

vpr::ReturnStatus vpr::ThreadPosix::start

(

)

[virtual]

Starts this thread's execution.

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.

Implements vpr::BaseThread.

Definition at line 163 of file ThreadPosix.cpp.

References vpr::CondVarPosix::acquire(), vpr::ReturnStatus::Fail, vpr::BaseThread::registerThread(), vpr::CondVarPosix::release(), vpr::ReturnStatus::setCode(), spawn(), startThread(), vpr::ReturnStatus::success(), vprASSERT, and vpr::CondVarPosix::wait().

Referenced by ThreadPosix().

{
   vpr::ReturnStatus status;

   if ( mRunning )
   {
      vprASSERT(false && "Thread already started");
      status.setCode(vpr::ReturnStatus::Fail);
   }
   else if ( NULL == mUserThreadFunctor )
   {
      vprASSERT(false && "No functor set");
      status.setCode(vpr::ReturnStatus::Fail);
   }
   else
   {
      mStartFunctor =
         new ThreadMemberFunctor<ThreadPosix>(this, &ThreadPosix::startThread,
                                              NULL);

      // Spawn the thread.  If the thread is spawned successfully, the method
      // startThread() will register the actual thread info.
      mThreadStartCompleted = false;  // Make sure this is set correctly
      status = spawn(mStartFunctor);

      // Thread spawned successfully.
      if ( status.success() )
      {
         // startThread() will register the thread, so we wait for
         // registration to complete here.
         mThreadStartCondVar.acquire();
         {
            while ( ! mThreadStartCompleted )
            {
               mThreadStartCondVar.wait();
            }
         }
         mThreadStartCondVar.release();

         mRunning = true;
      }
      // Thread spawning failed.  Yikes!
      else
      {
         ThreadManager::instance()->lock();
         {
            registerThread(false);
         }
         ThreadManager::instance()->unlock();
      }
   }

   return status;
}

vpr::ReturnStatus vpr::ThreadPosix::spawn

(

BaseThreadFunctor *

functorPtr

)

[protected]

Creates a new thread that will execute functorPtr.

Postcondition:

A thread (with any specified attributes) is created that begins executing func(). Depending on the scheduler, it may begin execution immediately, or it may block for a short time before beginning execution.

Parameters:

functorPtr

Function to be executed by the thread.

Returns:

A vpr::ReturnStatus obj is returned to indicate the result of the thread creation.

Note:

The pthreads implementation on HP-UX 10.20 does not allow the stack address to be changed.

Definition at line 219 of file ThreadPosix.cpp.

References vpr::ReturnStatus::Fail, vpr::ReturnStatus::setCode(), and vpr::vprThreadFunctorFunction().

Referenced by start().

{
   vpr::ReturnStatus status;
   int ret_val;
   pthread_attr_t thread_attrs;

   int pthread_prio = vprThreadPriorityToPOSIX(mPriority);

   // Initialize thread_attrs and set the priority of the thread if it is
   // supported.
   sched_param_t prio_param;

   pthread_attr_init(&thread_attrs);
   pthread_attr_setdetachstate(&thread_attrs, vprThreadStateToPOSIX(mState));

   // If thread priority scheduling is available, set the thread's priority
   // if it is set to be higher than 0.
#  ifdef _POSIX_THREAD_PRIORITY_SCHEDULING
   int thread_scope = vprThreadScopeToPOSIX(mScope);

#  if defined(HAVE_SYS_CAPABILITY_H) && ! defined(VPR_OS_FreeBSD) && \
      ! defined(VPR_OS_Linux)
   cap_t capabilities = cap_get_proc();

   // If we have the capability to do so, set the scope of the threads
   // to system scope.
   if ( capabilities->cap_effective & CAP_SCHED_MGT )
   {
      thread_scope = PTHREAD_SCOPE_SYSTEM;
   }
#  endif   /* HAVE_SYS_CAPABILITY_H */

   pthread_attr_setscope(&thread_attrs, thread_scope);

   if ( pthread_prio > 0 )
   {
      prio_param.sched_priority = pthread_prio;
      pthread_attr_setschedparam(&thread_attrs, &prio_param);
   }
#  endif   /* _POSIX_THREAD_PRIORITY_SCHEDULING */

   // Set the stack size if a value greater than 0 is specified and this
   // pthreads implementation supports it.  Ensure that
   // _POSIX_THREAD_ATTR_STACKSIZE is defined before trying to test its
   // value.
#ifdef _POSIX_THREAD_ATTR_STACKSIZE
   if ( mStackSize > 0 )
   {
      // XXX: ** STACK SIZE CHECK NEEDED **

      pthread_attr_setstacksize(&thread_attrs, mStackSize);
   }
#endif

   // Finally create the thread.
   ret_val = pthread_create(&(mThread), &thread_attrs,
                            vprThreadFunctorFunction, (void *) functorPtr);

   // Inform the caller if the thread was not created successfully.
   if ( ret_val != 0 )
   {
      status.setCode(vpr::ReturnStatus::Fail);
      std::cerr << "vpr::ThreadPosix::spawn() - Cannot create thread:"
                << strerror(ret_val) << std::endl;
   }

   return status;
}

void vpr::ThreadPosix::startThread

(

void *

nullParam

)

[protected]

Called by the spawn routine to start the user thread function.

Precondition:

Called ONLY by a new thread.

Postcondition:

The new thread will have started the user thread function. Any necessary thread registration is performed. The user thread functor is called.

Parameters:

nullParam

Unused.

Definition at line 289 of file ThreadPosix.cpp.

References vpr::CondVarPosix::acquire(), vpr::BaseThread::registerThread(), vpr::CondVarPosix::release(), vpr::ThreadKeyPosix::setspecific(), and vpr::CondVarPosix::signal().

Referenced by start().

{
   boost::ignore_unused_variable_warning(nullParam);

   // WE are a new thread... yeah!!!!
   // TELL EVERYONE THAT WE LIVE!!!!
   ThreadManager::instance()->lock();      // Lock manager
   {
      threadIdKey().setspecific((void*)this);  // Store the pointer to me
      registerThread(true);                    // Finish thread initialization
   }
   ThreadManager::instance()->unlock();

   // Signal that thread registration is complete.
   mThreadStartCondVar.acquire();
   {
      mThreadStartCompleted = true;
      mThreadStartCondVar.signal();
   }
   mThreadStartCondVar.release();

   // --- CALL USER FUNCTOR --- //
   (*mUserThreadFunctor)();
}

virtual int vpr::ThreadPosix::join

(

void **

status = 0

)

[inline, virtual]

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

Postcondition:

The caller blocks until this thread finishes its execution (i.e., calls the exit() method). This routine may return immediately if this thread has already exited.

Parameters:

status

Current state of the terminating thread when that thread calls the exit routine (optional).

Returns:

0 is returned if this thread is "joined" successfully.
-1 is returned on an error condition.

Reimplemented from vpr::BaseThread.

Definition at line 192 of file ThreadPosix.h.

   {
      return pthread_join(mThread, status);
   }

virtual int vpr::ThreadPosix::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 if this thread resumes execuation successfully.

-1 is returned otherwise.

Note:

This is not currently supported on HP-UX 10.20.

Reimplemented from vpr::BaseThread.

Definition at line 211 of file ThreadPosix.h.

References kill().

   {
      return kill(SIGCONT);
   }

virtual int vpr::ThreadPosix::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 if this thread is suspended successfully.

-1 is returned otherwise.

Note:

This is not currently supported on HP-UX 10.20.

Reimplemented from vpr::BaseThread.

Definition at line 227 of file ThreadPosix.h.

References kill().

   {
      return kill(SIGSTOP);
   }

int vpr::ThreadPosix::getPrio

(

VPRThreadPriority *

prio

)

[virtual]

Gets this thread's priority.

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 if the priority was retrieved successfully.

-1 is returned if the priority could not be read.

Note:

This is only supported on systems that support thread priority scheduling in their pthreads implementation.

Definition at line 315 of file ThreadPosix.cpp.

{
#ifdef _POSIX_THREAD_PRIORITY_SCHEDULING
   int policy, ret_val;
   sched_param_t fifo_sched_param;

   ret_val = pthread_getschedparam(mThread, &policy, &fifo_sched_param);
   *prio = posixThreadPriorityToVPR(fifo_sched_param.sched_priority);

   return ret_val;
#else
   std::cerr << "vpr::ThreadPosix::getPrio(): Not supported\n";

   return -1;
#endif
}

int vpr::ThreadPosix::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 if this thread's priority was set successfully.

-1 is returned otherwise.

Note:

This is only supported on systems that support thread priority scheduling in their pthreads implementation.

Definition at line 333 of file ThreadPosix.cpp.

{
#ifdef _POSIX_THREAD_PRIORITY_SCHEDULING
   sched_param_t sched_param;
   sched_param.sched_priority = prio;

   return pthread_setschedparam(mThread, SCHED_RR, &sched_param);
#else
   boost::ignore_unused_variable_warning(prio);
   std::cerr << "vpr::ThreadPosix::setPrio(): Not supported\n";

   return -1;
#endif
}

int vpr::ThreadPosix::setRunOn

(

int

cpu

)

[virtual]

Sets the CPU affinity for this thread (the CPU on which this thread will exclusively run).

Precondition:

The thread must have been set to be a system-scope thread.

Postcondition:

The CPU affinity is set or an error status is returned.

Parameters:

cpu

The CPU on which this thread will run exclusively.

Returns:

0 is returned if the affinity is set successfully.

-1 is returned otherwise.

Note:

This is currently only available on IRIX 6.5 and is non-portable.

Definition at line 348 of file ThreadPosix.cpp.

{
#ifdef VPR_OS_IRIX
   int ret_val;

   if ( mScope == PTHREAD_SCOPE_SYSTEM )
   {
      ret_val = pthread_setrunon_np(cpu);
   }
   else
   {
      std::cerr << "This thread is not a system-scope thread!\n";
      ret_val = -1;
   }

   return ret_val;
#else
   boost::ignore_unused_variable_warning(cpu);
   std::cerr << "vpr::ThreadPosix::setRunOn(): Not available on this system.\n";

   return -1;
#endif
}

int vpr::ThreadPosix::getRunOn

(

int *

cur_cpu

)

[virtual]

Gets the CPU affinity for this thread (the CPU on which this thread exclusively runs).

Precondition:

The thread must have been set to be a system-scope thread, and a previous affinity must have been set using setRunOn().

Postcondition:

The CPU affinity for this thread is stored in the cur_cpu pointer.

Parameters:

cur_cpu

The CPU affinity for this thread (set by a previous call to setRunOn().

Returns:

0 is returned if the affinity is retrieved successfully.

-1 is returned otherwise.

Note:

This is currently only available on IRIX 6.5 and is non-portable.

Definition at line 372 of file ThreadPosix.cpp.

{
#ifdef VPR_OS_IRIX
   int ret_val;

   if ( mScope == PTHREAD_SCOPE_SYSTEM )
   {
      ret_val = pthread_getrunon_np(cur_cpu);
   }
   else
   {
      std::cerr << "This thread is not a system-scope thread!\n";
      ret_val = -1;
   }

   return ret_val;
#else
   boost::ignore_unused_variable_warning(cur_cpu);
   std::cerr << "vpr::ThreadPosix::getRunOn(): Not available on this system.\n";

   return -1;
#endif
}

static void vpr::ThreadPosix::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 306 of file ThreadPosix.h.

   {
      sched_yield();
   }

int vpr::ThreadPosix::kill

(

int

signum

)

[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 if the signal was sent successfully.

-1 is returned otherwise.

Note:

This is not currently supported with Pthreads Draft 4.

Reimplemented from vpr::BaseThread.

Definition at line 396 of file ThreadPosix.cpp.

{
   return pthread_kill(mThread, signum);
}

virtual void vpr::ThreadPosix::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 339 of file ThreadPosix.h.

Referenced by resume(), and suspend().

   {
      pthread_cancel(mThread);
   }

Thread * vpr::ThreadPosix::self

(

)

[static]

Get a pointer to the thread we are in.

Returns:

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

A non-NULL pointer is returned that points to the thread in which we are currently running.

Definition at line 401 of file ThreadPosix.cpp.

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

Referenced by vpr::ThreadPool::addThread(), vpr::ProfileManager::getRootNode(), vpr::Debug::getStream(), and vpr::ThreadPool::threadLoop().

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

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

   return my_thread;
}

std::ostream & vpr::ThreadPosix::outStream

(

std::ostream &

out

)

[virtual]

Provides a way of printing the process ID neatly.

Reimplemented from vpr::BaseThread.

Definition at line 234 of file ThreadNSPR.cpp.

References vpr::BaseThread::outStream().

Referenced by vpr::operator<<().

{
   out.setf(std::ios::right);
   out << std::setw(7) << std::setfill('0')
#ifdef VPR_OS_Windows
       << _getpid()
#else
       << getpid()
#endif
       << "/";
   out.unsetf(std::ios::right);
   BaseThread::outStream(out);
   out << std::setfill(' ');
   return out;
}

---

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

• ThreadPosix.h
• ThreadNSPR.cpp
• ThreadPosix.cpp

---