---

vpr::ThreadPosix Class Reference

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

#include <ThreadPosix.h>

Inheritance diagram for vpr::ThreadPosix:

[legend]Collaboration diagram for vpr::ThreadPosix:

[legend]List of all members.

Public Methods
	ThreadPosix (VPRThreadPriority priority=VPR_PRIORITY_NORMAL, VPRThreadScope scope=VPR_GLOBAL_THREAD, VPRThreadState state=VPR_JOINABLE_THREAD, size_t stack_size=0)
	Non-spawning constructor. More...
	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. More...
	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). More...
virtual	~ThreadPosix ()
	Destructor. More...
virtual void	setFunctor (BaseThreadFunctor *functorPtr)
	Sets the functor that this thread will execute. More...
virtual vpr::ReturnStatus	start ()
	Starts this thread's execution. More...
virtual int	join (void **status=0)
	Makes the calling thread wait for the termination of this thread. More...
virtual int	resume (void)
	Resumes the execution of a thread that was previously suspended using suspend(). More...
virtual int	suspend (void)
	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	setRunOn (int cpu)
	Sets the CPU affinity for this thread (the CPU on which this thread will exclusively run). More...
virtual int	getRunOn (int *cur_cpu)
	Gets the CPU affinity for this thread (the CPU on which this thread exclusively runs). 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...
std::ostream &	outStream (std::ostream &out)
	Provides a way of printing the process ID neatly. More...
Static Public Methods
void	yield ()
	Yields execution of the calling thread to allow a different blocked thread to execute. More...
BaseThread *	self ()
	Get a ptr to the thread we are in. More...
Protected Methods
vpr::ReturnStatus	spawn (BaseThreadFunctor *functorPtr)
	Creates a new thread that will execute functorPtr. More...
void	startThread (void *nullParam)
	Called by the spawn routine to start the user thread function. More...

---

Detailed Description

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

Functions by recieving a function in the constructor that is the function to call when the new thread is created. This 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

Definition at line 80 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 75 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 92 of file ThreadPosix.cpp. References setFunctor, start, and vpr::thread_func_t. : 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 114 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. Precondition: None. Postcondition: This thread is removed from the thread table and from the local thread hash. Definition at line 132 of file ThreadPosix.cpp. { if ( mDeleteThreadFunctor ) { delete mUserThreadFunctor; } if ( NULL != mStartFunctor ) { delete mStartFunctor; } }

---

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 145 of file ThreadPosix.cpp. References 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 153 of file ThreadPosix.cpp. References vpr::CondVarPosix::acquire, vpr::ReturnStatus::Fail, vpr::BaseThread::registerThread, vpr::CondVarPosix::release, vpr::ReturnStatus::setCode, spawn, 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. Precondition: None. 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 209 of file ThreadPosix.cpp. References vpr::ReturnStatus::Fail, sched_param_t, 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 279 of file ThreadPosix.cpp. References vpr::CondVarPosix::acquire, vpr::BaseThread::registerThread, vpr::CondVarPosix::release, and vpr::CondVarPosix::signal. { 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. Precondition: None. 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 (  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 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. 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 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 228 of file ThreadPosix.h. References kill. { return kill(SIGSTOP); }

int vpr::ThreadPosix::getPrio (  VPRThreadPriority *    prio )  [virtual]

Gets this thread's priority. Precondition: None. 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. Reimplemented from vpr::BaseThread. Definition at line 305 of file ThreadPosix.cpp. References sched_param_t. { #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. 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 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. Reimplemented from vpr::BaseThread. Definition at line 323 of file ThreadPosix.cpp. References sched_param_t. { #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 338 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 362 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 }

void vpr::ThreadPosix::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 311 of file ThreadPosix.h. { sched_yield(); }

int vpr::ThreadPosix::kill (  int    signum )  [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 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 386 of file ThreadPosix.cpp. { return pthread_kill(mThread, signum); }

virtual void vpr::ThreadPosix::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 346 of file ThreadPosix.h. Referenced by resume, and suspend. { pthread_cancel(mThread); }

BaseThread * vpr::ThreadPosix::self (    )  [static]

Get a ptr 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 391 of file ThreadPosix.cpp. References vpr::BaseThread::BaseThread, and vprASSERT. { vprASSERT((statics.mStaticsInitialized==1221) && "Trying to call vpr::ThreadPosix::self before statics are initialized. Don't do that"); BaseThread* 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 402 of file ThreadPosix.cpp. { out.setf(std::ios::right); out << std::setw(7) << std::setfill('0') << getpid() << "/"; 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
• ThreadPosix.cpp

---