ThreadMgr Class Reference

A basic thread management class. More...

Collaboration diagram for ThreadMgr:

Classes
struct	func_arguments
	structure for static wrapper function arguments More...

Public Member Functions
	ThreadMgr ()
	constructor More...
int	cancel_thread (pthread_t *tid)
	cancel a thread More...
int	condWait (void **thread_return_val)
	wait on a condition variable for a thread to terminate More...
pthread_t	createThread (void *(*thread_func)(void *), void *arg)
	attempt to create a new thread and register it More...
int	threadsActive ()
	return the number of active threads More...
bool	no_threads_terminated ()
	answers the question "are there no theads terminated?" More...

Protected Member Functions
int	removeTerminated (void **return_val)
	remove a terminated thread LIFO More...
void	addID (pthread_t id, func_arguments *arg)
	add a thread id to the id vector More...

Static Protected Member Functions
static void *	func (void *arg)
	internal thread function More...
static void *	addTerminated (ThreadMgr *arg)
	add a thread id to the m_terminated stack More...
static void	shutdown_thread (void *arg)
	shutdown a thread from pthread_cleanup_pop(). More...

Private Attributes
pthread_mutex_t *	m_mutex
	mutex for data access (m_ids, m_terminated) More...
pthread_mutex_t *	m_cond_mutex
	mutex for condition variable More...
pthread_cond_t *	m_cond_var
	condition variable More...
std::map< pthread_t, ThreadMgr::func_arguments * >	m_ids
	map of all thread ids and function attributes More...
std::stack< pthread_t >	m_terminated
	stack of terminated thread ids More...

Detailed Description

A basic thread management class.

Author

Karl N. Redman (karl..nosp@m.redm.nosp@m.an@gm.nosp@m.ail..nosp@m.com)

Purpose:

This is an example class intended to be used as a guidline for the work required to handle pthreads where the main process (the parent of the initial threads) waits on a condition variable for the threads to terminate. The functions that are specified for the pthread_create are user defined.

This class should be pretty fast and relatively easy to use for most general purpose thread programming. In general, it's a good place to start.

Basic pthread "voidness" has been retained for demonstration purposes. It is concevable that this class could be instantiated from and / or altered to make the user interface easier to work with (in other words -we could get rid of much of the user end casting through inheritance).

Note

This class is not intended for use by detached threads unless some of the functions are overridden. Also, the use of long casting was used in favor of readability in the interests of speed.

Definition at line 60 of file threadDeath3.cc.

Constructor & Destructor Documentation

ThreadMgr::ThreadMgr ( )

inline

constructor

Note

this function instantiates static pthread_x_t variables for mutexes and a condition variable

Definition at line 80 of file threadDeath3.cc.

References m_cond_mutex, m_cond_var, and m_mutex.

  { 
    //the data mutex
    static pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER; 
    m_mutex = &mutex; 

    //the condition variable mutex
    static pthread_mutex_t cond_mutex = PTHREAD_MUTEX_INITIALIZER;
    m_cond_mutex = &cond_mutex;

    //the condition variable
    static pthread_cond_t cond_var = PTHREAD_COND_INITIALIZER;
    m_cond_var = &cond_var;
  }

Member Function Documentation

void ThreadMgr::addID ( pthread_t  id, func_arguments *  arg  )

inlineprotected

add a thread id to the id vector

Definition at line 386 of file threadDeath3.cc.

References m_ids, and m_mutex.

Referenced by createThread().

  {
    //lock the data mutex
    pthread_mutex_lock(m_mutex);
    
    //add the thread to the std::map
    m_ids.insert(std::make_pair(id, arg));

    //unlock the data mutex
    pthread_mutex_unlock(m_mutex);
  }

static void* ThreadMgr::addTerminated ( ThreadMgr *  arg )

inlinestaticprotected

add a thread id to the m_terminated stack

Definition at line 317 of file threadDeath3.cc.

References m_cond_var, m_mutex, and m_terminated.

Referenced by func().

  { 
    //pthread_mutex_lock(((ThreadMgr *)arg)->m_mutex);
    pthread_mutex_lock(arg->m_mutex);

    //add self to list of stuff to be terminated (joined)
    arg->m_terminated.push(pthread_self());

    //broadcast to threads waiting on the condition variable to notify
    //them to wake up
    pthread_cond_broadcast(arg->m_cond_var);

    pthread_mutex_unlock(arg->m_mutex);

    //return NULL -blah
    return NULL;
  }

int ThreadMgr::cancel_thread ( pthread_t *  tid )

inline

cancel a thread

Returns

return value of a pthread_cancel() for parameter tid

Parameters

tid	pointer to the thread id to kill

Warning

If the thread has allocated dynamic memory and has been canceled this class does not compensate. In other words, never cancel a thread (with this class) that allocates dynamic memory -you will lose your pointer. This is because pthread_cancel does not allow you to recieve anything back from a canceled thread. However, you could delete your pointer before you retrurn from the thread if that is your wish.

use of the function pthread_cancel() for threads managed by this class may result in loss of dynamic memory pointers, or worse, a race condition for m_mutex resulting in a deadlock of the threads. Don not use pthread_cancel() for threads managed by this class. Use ThreadMgr::cancel_thread() instead.

Todo:

add more robust thread canceling ability

Definition at line 100 of file threadDeath3.cc.

References m_ids, and m_mutex.

Referenced by main().

  {
    //cancel a thread
    int ret = 0;
    pthread_mutex_lock(m_mutex);        //lock the data mutex 
    m_ids.erase(*tid);                  //remove from id map

    //cancel the thread
    ret = pthread_cancel(*tid);
    
    pthread_mutex_unlock(m_mutex);      // unlock data mutex

    return ret; 
  }

int ThreadMgr::condWait ( void **  thread_return_val )

inline

wait on a condition variable for a thread to terminate

Purpose:

Act like a seamless condition variable. Allows a process to block until a thread has terminated and returns the thread functions return value through the parameter.

Parameters

a	pointer to the pointer of the threads return value.

Returns

pthread_join status from removeTerminated()

Warning

This function may not be safe for threads that are canceled

Definition at line 140 of file threadDeath3.cc.

References m_cond_mutex, m_cond_var, no_threads_terminated(), and removeTerminated().

Referenced by main(), TwaitStringThreads(), and waitStringThreads().

  {
    int ret = 0;
    
    //condition variable mutex lock
    pthread_mutex_lock(m_cond_mutex);

    //check predicate
    while(no_threads_terminated())
      {
        //wait on condition variable
        pthread_cond_wait(m_cond_var, m_cond_mutex);
      }


    //remove the thread from the terminated list (handle join)
    ret = removeTerminated(thread_return_val);

    //unlock
    pthread_mutex_unlock(m_cond_mutex);

    //return join status
    return ret;
  }

Here is the call graph for this function:

pthread_t ThreadMgr::createThread ( void *(*)(void *)  thread_func, void *  arg  )

inline

attempt to create a new thread and register it

Purpose:

Create a new thread and register it for management by this class.

Returns

0 on error, pthread_t thread ID on success

Parameters

pointer

to function to run as thread, pointer to argument. [i.e. createThread(myfunc, arg);]

Note

This function works by building the an argument list from the one provided by the user and some internal stuff in order to call an internal function that sets things up for return values, etc. and then calls the users function. This adds about the size of 8 (roughly) pointers to the memory usage of each thread being created -but that's the price for wanting to keep track of this stuff generically i guess.

Definition at line 181 of file threadDeath3.cc.

References addID(), ThreadMgr::func_arguments::arg, ThreadMgr::func_arguments::cancel_func, ThreadMgr::func_arguments::func, and ThreadMgr::func_arguments::thisObject.

Referenced by main().

  {
    pthread_t tid = 0;          // Id of thread
    int ret_val;                // return value
 
    //arguments for the function
    struct func_arguments *arguments = new func_arguments;

    arguments->func = thread_func;      // users function
    arguments->cancel_func = NULL;      // NOT IMPLIMENTED
    arguments->arg = arg;               // users argument

    //this is the this pointer (so far, every thread get's one -eek!)
    arguments->thisObject = this;

    //create a new thread
    /*
      default attributes (for now), 
      internal function, func(), calls users function,
      arguments contain other info + user's argument.
    */
    ret_val = pthread_create(&tid, (pthread_attr_t *) NULL, func, (void *)arguments);

    if(ret_val == 0)
      {
        //register the thread and arguments in the ids map
        addID(tid, arguments);
    
        //return thread id
        return tid;
      }
    else
      std::cout << "pthread_create FAIL" << std::endl;


    //return 0 on error
    return 0;
  }

Here is the call graph for this function:

static void* ThreadMgr::func ( void *  arg )

inlinestaticprotected

internal thread function

Purpose:

This function is called from the call to pthread_create() within member function createThread. This function handles basic thread management issues and is a wrapper around the user function -which is called from here as well.

Returns

NONE -this function shouldn't return!!! it calls pthread_exit().

Parameters

arg	shold be a pointer to a func_arguments structure.

Definition at line 265 of file threadDeath3.cc.

References addTerminated(), ThreadMgr::func_arguments::arg, ThreadMgr::func_arguments::cancel_func, ThreadMgr::func_arguments::func, shutdown_thread(), and ThreadMgr::func_arguments::thisObject.

  {
    //convenience this object
    ThreadMgr *thisObject = ((struct func_arguments *)arg)->thisObject;

    //return argument from user function
    void *tmpArg = NULL;

    //basic cancel stuff -should be more robust
    struct func_arguments *cancel_arg = new func_arguments;
    cancel_arg->cancel_func = shutdown_thread;
    cancel_arg->func = NULL;
    cancel_arg->arg = NULL;
    cancel_arg->thisObject = thisObject;

    //set the cleanup function
    pthread_cleanup_push(shutdown_thread, (void *)cancel_arg);

    //call the user's function
    tmpArg = ((struct func_arguments *)arg)->func( ((struct func_arguments *)arg)->arg );
    //std::cout << "func() passing \"" << *(std::string *)tmpArg << "\" to pthread_exit()" << std::endl;

    //delete (struct func_arguments *)arg;

    //pop the cleanup handler off the cleanup stack
    //delete the arg variable list from the createThread function.
    pthread_cleanup_pop(1);
    
    //add this thread to the terminated list
    thisObject->addTerminated(thisObject);

    //exit this thread
    pthread_exit(tmpArg);

    //we will never get here
    return NULL;
  }

Here is the call graph for this function:

bool ThreadMgr::no_threads_terminated ( )

inline

answers the question "are there no theads terminated?"

Returns

boolean of terminated threads in terminate queue

Definition at line 251 of file threadDeath3.cc.

References m_mutex, and m_terminated.

Referenced by condWait(), and main().

  {
    pthread_mutex_lock(m_mutex);
    bool ret = m_terminated.empty();
    pthread_mutex_unlock(m_mutex);
    return ret;
  }

int ThreadMgr::removeTerminated ( void **  return_val )

inlineprotected

remove a terminated thread LIFO

Returns

result of pthread_join

Parameters

pointer

to user function return value pointer

Note

the void **retrun_val is a result of the pthread_join.

Warning

the thread is unregistered only if the pthread_join was successfull. This may be a problem down the line (but VERY rare)

Definition at line 336 of file threadDeath3.cc.

References m_ids, m_mutex, and m_terminated.

Referenced by condWait().

  {
    int ret = 0;
    pthread_t tempID;

    //lock critical section
    pthread_mutex_lock(m_mutex);

    //make sure we have something
    if(!m_terminated.empty())
      {
        //get id from stack
        tempID = m_terminated.top();

        //join with the terminated thread
        if( (ret = pthread_join(tempID, return_val)) == 0)
          {
            //delete the arguments (created in createThread)
            //delete m_ids.find(tempID)->second;
            
            //get rid of the ID from active list
            m_ids.erase(tempID);
            
            //remove id from stack
            m_terminated.pop();
          }
        else
          std::cout << "pthread_join() = " << ret << std::endl;
      }

    //unlock critical section
    pthread_mutex_unlock(m_mutex);

    //return value of pthread_join
    return ret;
  }

static void ThreadMgr::shutdown_thread ( void *  arg )

inlinestaticprotected

shutdown a thread from pthread_cleanup_pop().

Parameters

arg	must be void * per pthread_cleanup_x()

Definition at line 399 of file threadDeath3.cc.

Referenced by func().

  {
    delete ((struct func_arguments *)arg);
    return;
  }

int ThreadMgr::threadsActive ( )

inline

return the number of active threads

Definition at line 241 of file threadDeath3.cc.

References m_ids, and m_mutex.

Referenced by main(), TwaitStringThreads(), and waitStringThreads().

  { 
    pthread_mutex_lock(m_mutex);
    int ret =  m_ids.size(); 
    pthread_mutex_unlock(m_mutex);
    
    return ret;
  }

Member Data Documentation

pthread_mutex_t* ThreadMgr::m_cond_mutex

private

mutex for condition variable

Definition at line 413 of file threadDeath3.cc.

Referenced by condWait(), and ThreadMgr().

pthread_cond_t* ThreadMgr::m_cond_var

private

condition variable

Definition at line 416 of file threadDeath3.cc.

Referenced by addTerminated(), condWait(), and ThreadMgr().

std::map<pthread_t, ThreadMgr::func_arguments *> ThreadMgr::m_ids

private

map of all thread ids and function attributes

Definition at line 419 of file threadDeath3.cc.

Referenced by addID(), cancel_thread(), removeTerminated(), and threadsActive().

pthread_mutex_t* ThreadMgr::m_mutex

private

mutex for data access (m_ids, m_terminated)

Definition at line 410 of file threadDeath3.cc.

Referenced by addID(), addTerminated(), cancel_thread(), no_threads_terminated(), removeTerminated(), ThreadMgr(), and threadsActive().

std::stack<pthread_t> ThreadMgr::m_terminated

private

stack of terminated thread ids

Definition at line 422 of file threadDeath3.cc.

Referenced by addTerminated(), no_threads_terminated(), and removeTerminated().

---

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

• threadDeath3.cc