VCF::Thread

VCF::Thread Class Reference

The Thread class represents a thread of execution in a process. More...

#include <vcf/FoundationKit/Thread.h>

Inheritance diagram for VCF::Thread:


Public Member Functions
	Thread ()
	Thread (const bool &autoDelete)
	Thread (Runnable *runnableObject, const bool &autoDelete)
	creates a thread with the attached runnableObject (if appropriate)
	Thread (Runnable *runnableObject, const bool &autoDeleteRunnable, const bool &autoDelete)
	Creates a thread with a runnable object, and allows the thread to automatically delete the runnable if appropriate.
	Thread (Runnable *runnableObject)
virtual	~Thread ()
virtual bool	run ()
	run method for the thread.
virtual void	stop ()
	gracefully stops the thread and shuts it down, releasing any OS resources associated with the thread.
bool	start ()
	Starts (or resumes) a thread running.
void	sleep (uint32 milliseconds)
	causes the thread the thread to sleep for the specified number of milliseconds
bool	canContinue ()
	can the thread continue to execute ?
bool	canAutoDelete ()
	can the thread auto delete itself ?
uint32	getThreadID ()
	returns the thread associated with this thread of execution
uint32	getOwningProcessID ()
	returns the process ID that this thread is part of
ThreadPeer *	getPeer ()
bool	isActive ()
	Returns TRUE if thread is running, FALSE if not.
virtual WaitResult	wait ()
virtual Waitable::WaitResult	wait (uint32 milliseconds)
virtual OSHandleID	getPeerHandleID ()
RunLoop *	getRunLoop ()
bool	internal_isStopped ()
	for thread peer's usage only - called to see if the thread is being shutdown via the stop() method.
void	internal_initBeforeRun ()
	Called by the thread peer implementation.
Static Public Member Functions
static Thread *	getMainThread ()
Protected Attributes
bool	canContinue_
Runnable *	runnableObject_
ThreadPeer *	peer_
bool	autoDelete_
bool	autoDeleteRunnable_
bool	stopped_
RunLoop *	runLoop_
Static Protected Attributes
static Thread *	mainThread

Detailed Description

The Thread class represents a thread of execution in a process.

A Thread object can automatically delete itself if neccessary. A Thread can either be derived from and the run() method overridden, or a separate class that derives from Runnable may be passed into the Thread's constructor and this class's run() method will get called.

For example:

Method 1) deriving a new thread class and over riding the run() method

class MyThread : public VCF::Thread {
public:
    MyThread() : VCF::Thread() {};

    virtual bool run() {
        //do stuff here, for example a loop
        //be a good citizen and check with the
        //canContinue() method to see if we should
        //still be executing
        while ( true == canContinue() ) {
            //do some work

            if ( somethingWentWrong ) {
                return false;
            }
        }
        return true;
    }
};

usage:

int main() {
    FoundationKit::init();

    MyThread* thread = new MyThread();
    thread->start(); //start the thread

    //program does stuff here

    //stop the thread cause we are shutting down
    thread->stop();

    //delete the thread since it is NOT set to auto delete
    //if we had passed in true in the Thread constructor then
    //we would not need this part
    thread->free();

    FoundationKit::terminate();
    return 0;
}

Method 2) deriving a new class from Runnable and pass it to a Thread you create

class MyMultiThreadedClass : public VCF::Object, public VCF::Runnable  {
public:
    MyMultiThreadedClass() {};

    //other methods here...

    //override the run() method of Runnable - MUST do this
    //for your class to be a concrete class
    virtual bool run() {
        //do stuff here, for example a loop

        //you must supply you own check methods to
        //determine if you can keep looping,
        //assuming that is what you need to do

        return true;
    }
};

usage:

int main() {
    FoundationKit::init();

    MyMultiThreadedClass multiThreader;

    Thread* thread = new Thread( &multiThreader, true ); //will auto delete

    thread->start(); //start the thread

    //program does stuff here

    //stop the thread cause we are shutting down
    thread->stop();

    //thread will auto delete itself

    FoundationKit::terminate();
    return 0;
}

Constructor & Destructor Documentation

VCF::Thread::Thread ( )

VCF::Thread::Thread ( const bool & autoDelete )

VCF::Thread::Thread ( Runnable * runnableObject,

const bool & autoDelete

)

creates a thread with the attached runnableObject (if appropriate)

Parameters:

Runnable the runnableObject the thread will use. By default this is NULL, which means the Thread's run method has been overridden in a derived class.

bool indicates whose responsibility it is to clean up after the thread is stopped. If autoDelete is true then the thread instance will clean up for itself, if autoDelete is false, then it is the caller's responsibility to clean up

VCF::Thread::Thread ( Runnable * runnableObject,

const bool & autoDeleteRunnable,

const bool & autoDelete

)

Creates a thread with a runnable object, and allows the thread to automatically delete the runnable if appropriate.

VCF::Thread::Thread ( Runnable * runnableObject )

virtual VCF::Thread::~Thread ( ) [virtual]

Member Function Documentation

bool VCF::Thread::canAutoDelete ( ) [inline]

can the thread auto delete itself ?

Returns:
bool true if the thread will auto delete itself. Determined by the parameters passed into the thread's constructor

bool VCF::Thread::canContinue ( ) [inline]

can the thread continue to execute ?

Returns:
bool true if the thread can safely continue to execute, otherwise false indicating it should stop executing.

static Thread* VCF::Thread::getMainThread ( ) [static]

uint32 VCF::Thread::getOwningProcessID ( )

returns the process ID that this thread is part of

ThreadPeer* VCF::Thread::getPeer ( ) [inline]

virtual OSHandleID VCF::Thread::getPeerHandleID ( ) [virtual]

Implements VCF::Waitable.

RunLoop* VCF::Thread::getRunLoop ( )

uint32 VCF::Thread::getThreadID ( )

returns the thread associated with this thread of execution

void VCF::Thread::internal_initBeforeRun ( )

Called by the thread peer implementation.
Initializes the thread with the thread manager.

bool VCF::Thread::internal_isStopped ( ) [inline]

for thread peer's usage only - called to see if the thread is being shutdown via the stop() method.

bool VCF::Thread::isActive ( )

Returns TRUE if thread is running, FALSE if not.

virtual bool VCF::Thread::run ( ) [virtual]

run method for the thread.
Overide this method to provide additional functionality. If runnableObject_ is non NULL then it's run() will be called in here.
Implements VCF::Runnable.
Reimplemented in VCFNet::SocketListeningLoop.

void VCF::Thread::sleep ( uint32 milliseconds )

causes the thread the thread to sleep for the specified number of milliseconds

Parameters:

uint32 - the number of milliseconds to sleep

bool VCF::Thread::start ( )

Starts (or resumes) a thread running.

virtual void VCF::Thread::stop ( ) [virtual]

gracefully stops the thread and shuts it down, releasing any OS resources associated with the thread.
Once a thread is stopped that thread instance may NOT be started again. If the thread is set of automatic deletion this is where it will happen
Implements VCF::Runnable.