/**
 * gThread.h
 * Copyright (C) 2002 Daniel Karrels <dan@karrels.com>
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software 
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307,
 * USA.
 * 
 * $Id: gThread.h,v 1.5 2003/12/29 23:59:36 dan_karrels Exp $
 */

#ifndef __GTHREAD_H
#define __GTHREAD_H "$Id: gThread.h,v 1.5 2003/12/29 23:59:36 dan_karrels Exp $"

#include	<pthread.h>

#include	<map>
#include	<string>

#include	"misc.h"

namespace gnuworld
{

/**
 * The base class for creating a thread.
 * Simply subclass this class and overload the Exec()
 * method, and call Start() to have a running thread.
 * Once started, each thread is responsible for monitoring
 * this object's 'keepRunning' variable.  It should
 * poll this variable (note: do not block indefinitely)
 * and return from its Exec() method when keepRunning
 * is set to false; this indicates that a Stop() request
 * has been issued.
 */
class gThread
{

protected:
	/**
	 * The type used to store mutexes.
	 */
	typedef std::map< std::string, pthread_mutex_t, noCaseCompare >	
			mutexMapType ;

	/**
	 * The iterator type to the mutex map.
	 */
	typedef mutexMapType::iterator		mutexIterator ;

	/**
	 * The const_iterator type to the mutex map.
	 */
	typedef mutexMapType::const_iterator	constMutexIterator ;

public:

	/**
	 * Default constructor.
	 */
	gThread() ;

	/**
	 * The destructor will stop the thread, issue a join(), and
	 * destroy any mutexes.
	 */
	virtual ~gThread() ;

	/**
	 * Invoke this method to begin the Exec() method in a new
	 * thread.
	 */
	virtual bool		Start() ;

	/**
	 * Return true if this thread is running, false otherwise.
	 */
	virtual bool		isRunning() const
		{ return (keepRunning && (threadID != 0)) ; }

	/**
	 * Request that this thread stop processing.  This could take
	 * an arbitrary length of time to fully stop, depending on how
	 * well the thread subclass follows directions (see above).
	 */
	virtual void		Stop()
		{ keepRunning = false ; }

	/**
	 * Issue a pthread_join() on this (already stopped) thread to
	 * cleanup.
	 */
	virtual void		Join() ;

	/**
	 * Create a mutex with the given case insensitive name.
	 * True is returned if successfull, false otherwise.
	 */
	virtual bool		CreateMutex( const std::string& mutexName ) ;

	/**
	 * Destroy a mutex with the given case insensitive name.
	 * True is returned if successfull, false otherwise.
	 */
	virtual bool		DestroyMutex( const std::string& mutexName ) ;

	/**
	 * Destroy all active mutexes.
	 */
	virtual void		DestroyAllMutexes() ;

	/**
	 * Locks the mutex specified by mutexName.
	 * This method blocks indefinitely until the lock is obtained.
	 */
	virtual void		LockMutex( const std::string& mutexName ) 
;

	/**
	 * Unlocks the mutex specified by mutexName.
	 * This method will return immediately.
	 */
	virtual void		UnLockMutex( const std::string& mutexName ) ;

	/**
	 * This method is invoked in a new thread when the Start()
	 * method is invoked.  Subclasses must overload this method
	 * to perform the meaningful duty of the thread proper.
	 * This method must halt when keepRunning is set to false.
	 */
	virtual void		Exec() {}

protected:

	/**
	 * The running status of the thread.  Subclasses must honor
	 * the value of this variable.
	 */
	bool			keepRunning ;

	/**
	 * True if shutdown has completed (keepRunning request has
	 * been honored), and it is clear to issue a join(), false
	 * otherwise.
	 */
	bool			isShutdownComplete ;

	/**
	 * The thread ID for this thread, 0 if not running.
	 */
	pthread_t		threadID ;

	/**
	 * The container used to store the active mutexes.
	 */
	mutexMapType		mutexMap ;

	/**
	 * A general purpose mutex on which to wait.
	 */
	pthread_mutex_t		waitMutex ;

} ; // class gThread

} // namespace gnuworld

#endif // __GTHREAD_H