Main Page   Modules   Namespace List   Class Hierarchy   Compound List   Namespace Members   Compound Members   Related Pages  

GNE::Thread Class Reference
[Threading API]

#include <Thread.h>

Inheritance diagram for GNE::Thread:

GNE::ClientConnection GNE::ConnectionEventGenerator GNE::EventThread GNE::PacketStream GNE::ServerConnection GNE::Timer GNE::ListServerConnection List of all members.

Public Types

typedef SmartPtr< Thread > sptr
typedef WeakPtr< Thread > wptr
enum  ThreadType {
  USER, TIMER, SYSTEM, CONNECTION,
  ALL
}
 An enum for specifing the thread type. More...


Public Member Functions

 Thread (std::string name=DEF_NAME, int priority=DEF_PRI)
 Creates a new thread, ready to run but not yet running.

std::string getName () const
 Returns the name of this thread.

virtual void shutDown ()
 Makes a request that this thread should shutdown.

void join ()
 A blocking call that returns when this thread terminates, or returns immediately if the thread has terminated.

bool hasStarted () const
 Returns true if this Thread has ever been started.

bool isRunning () const
 Determine the running state of the thread.

void start ()
 Starts this thread running.

int getPriority () const
 Returns the priority of this class.


Static Public Member Functions

sptr currentThread ()
 Returns the Thread object that represents this calling thread.

void sleep (int ms)
 The currently running thread sleeps for the time given in milliseconds.

void yield ()
 Makes a request to the operating system to give up the remainder of this thread's timeslice to another appropriate thread.

bool waitForAllThreads (int ms)
 This method will wait for all threads that have a type != SYSTEM.

void requestAllShutdown (ThreadType threadType)
 Calls the shutDown method of all running threads of the given type.


Static Public Attributes

const int DEF_PRI = 0
 The default priority of a thread.

const std::string DEF_NAME = "Thread"
 The default name for a thread.

const int LOW_PRI = -1
 A lowered priority for a thread.

const int LOWER_PRI = -2
 A lower priority for a thread than LOW_PRI.

const int HIGH_PRI = 1
 A "boosted priority" for a thread.

const int HIGHER_PRI = 2
 Even higher priority thread than HIGH_PRI.


Protected Member Functions

void setThisPointer (const wptr &thisPtr)
 IMPORTANT: call this method in your static create function.

sptr getThisPointer () const
 Returns a SmartPtr to this object.

void setType (ThreadType newType)
 Sets this Thread's type.

virtual void run ()=0
 This function is the starting point for this thread.


Protected Attributes

volatile bool shutdown
 This variable is set to true when this thread should exit.


Detailed Description

A class resembling a thread. Derive your own classes from this class that implements the run function. Execution begins in the run method. All methods of this class are thread- safe.

Todo:
Priorities are not yet implemented.


Member Enumeration Documentation

enum GNE::Thread::ThreadType
 

An enum for specifing the thread type.

You should never need to use this directly, since anything you create should have type USER.

Enumeration values:
USER  this thread is a user-created thread
TIMER  this thread is a Timer thread
SYSTEM  this thread is a GNE-created thread
CONNECTION  this thread is for a Connection
ALL  used only as a parameter to some functions


Constructor & Destructor Documentation

GNE::Thread::Thread std::string  name = DEF_NAME,
int  priority = DEF_PRI
 

Creates a new thread, ready to run but not yet running.

Parameters:
name the name of this thread
priority the priority this thread has


Member Function Documentation

Thread::sptr GNE::Thread::currentThread  )  [static]
 

Returns the Thread object that represents this calling thread.

This will return a SmartPtr to the calling thread, or an empty SmartPtr if the calling thread is the main thread or another thread created outside of the GNE API.

Thread::sptr GNE::Thread::getThisPointer  )  const [protected]
 

Returns a SmartPtr to this object.

See also:
setThisPointer

bool GNE::Thread::hasStarted  )  const
 

Returns true if this Thread has ever been started.

This remains true if even after the Thread has stopped running.

bool GNE::Thread::isRunning  )  const
 

Determine the running state of the thread.

If running is true, then started must be true.

void GNE::Thread::requestAllShutdown ThreadType  threadType  )  [static]
 

Calls the shutDown method of all running threads of the given type.

This is simply a request to the thread that it should shut down -- it is up to the implementation whether to ignore or heed this advice, and how quickly. You can pass the special type ALL to this function.

Only GNE itself should call requestAllShutdown with a parameter besides "USER". If you call this function, you should only use the parameter USER. If you want to shut down timers or connections, use the appopriate functions of those classes.

Threads marked as SYSTEM should never be touched by the user. They will shutdown when GNE exits.

See also:
Connection::disconnectAll

Timer::stopAll

virtual void GNE::Thread::run  )  [protected, pure virtual]
 

This function is the starting point for this thread.

Derive your own class from Thread, and implement this function. When this function returns, the thread ends.

Implemented in GNE::ConnectionEventGenerator, GNE::EventThread, GNE::PacketStream, GNE::ServerConnection, and GNE::Timer.

void GNE::Thread::setThisPointer const wptr &  thisPtr  )  [protected]
 

IMPORTANT: call this method in your static create function.

Unfortunately there is no way to force an object to be managed by a smart pointer, so when you derive from Thread you must do this yourself, preferably through a public static create method. See the threading examples for this.

IF YOU DO NOT SET THIS YOUR PROGRAM WILL CRASH! You must set it before any Thread methods are called (excluding the Thread constructor).

See also:
getThisPointer

void GNE::Thread::setType ThreadType  newType  )  [protected]
 

Sets this Thread's type.

You shouldn't call this function, since the thread type USER is default, and only threads created by GNE should be anything but USER.

void GNE::Thread::shutDown  )  [virtual]
 

Makes a request that this thread should shutdown.

Tells this thread to shutdown, if it is in an infinite loop. You will probably want to call join right after calling this to wait for the shutdown to complete which is dependant on the thread you are shutting down.

This function is virtual if the thread needs any additional actions to notify itself to shutdown, for example if it is waiting for some event on a ConditionVariable.

You will want to call this function from the override to make sure that shutdown is set to true.

This function is safe to call multiple times, but you cannot undo a shutdown once it has been called.

Reimplemented in GNE::ConnectionEventGenerator, GNE::EventThread, GNE::PacketStream, GNE::ServerConnection, and GNE::Timer.

void GNE::Thread::start  ) 
 

Starts this thread running.

The thread will be marked as running before this function completes. Once a thread has stopped it can never be restarted, so only one call to start can ever be made.

Precondition:
hasStarted returns false

bool GNE::Thread::waitForAllThreads int  ms  )  [static]
 

This method will wait for all threads that have a type != SYSTEM.

This includes threads from connections and threads from timers, so if you have any active connections or timers this method will almost always timeout. Therefore this method is best meant for making sure that after you have shutdown all of the connections, timers, and threads you have created that you are guaranteed that they have ended, so that you may freely release any resources they were using.

GNE calls this method for you implicitly when GNE is shutdown. This may be a problem since by default GNE is shutdown with an atexit routine that runs after main ends. If this is a problem, you should explicitly call GNE::shutdownGNE.

The implementation of this method is simple and therefore not intended to be used to create a program where you create detached threads and then use the main thread to sit in this function until the "real" program completes. It is meant solely as a method of definitvely verifying the completion of temporary threads, and waiting short times for these threads to finish if needed. If you need to wait a long time (over 10 seconds) use join on the threads you've made, as join is much more efficient.

You may want to execute the requestAllShutdown method before calling this method.

Parameters:
ms the amount of time to wait for the threads before giving up. This is used so a stalled or crashed thread will still allow you to terminate the program.
Returns:
false if all threads have completed, or true if there are still some threads running and the method timed out.
See also:
requestAllShutdown

Connection::disconnectAll

GNE::shutdownGNE

Timer::stopAll

void GNE::Thread::yield  )  [static]
 

Makes a request to the operating system to give up the remainder of this thread's timeslice to another appropriate thread.

This function does nothing if the operating system does not support the call. Note that even if the OS supports the call, it may choose not to end your timeslice.

There are certain few cases where yielding may improve performance or response, but most of the time you are likely wanting to use a ConditionVariable to wait for an event or a Timer. You should never use yielding as mitigation for a busy-wait, because you will still use 100% CPU and essentially you will perform a busy-wait and just effectively lower the scheduling priority of your thread/process.


Member Data Documentation

const int GNE::Thread::HIGH_PRI = 1 [static]
 

A "boosted priority" for a thread.

This is optimized to give some extra priority for the network threads to reduce network latency in favor of a little in-game fps.

const int GNE::Thread::HIGHER_PRI = 2 [static]
 

Even higher priority thread than HIGH_PRI.

Used typically for the timer threads.

const int GNE::Thread::LOW_PRI = -1 [static]
 

A lowered priority for a thread.

Might be good for background operations like loading and saving files or something so it does not interfer with the user interface (be it a GUI or a game or whatever).

volatile bool GNE::Thread::shutdown [protected]
 

This variable is set to true when this thread should exit.

Users that implement a Thread class must respond to this if the thread wants to wait in an infinite loop. Threads that will eventually stop can respond only optionally to this, but if they last for a long time, shutting down all threads may take awhile. Responding to this flag usually takes nothing more than a while (!shutdown) {} loop.


The documentation for this class was generated from the following files:
Generated on Fri Aug 22 13:40:07 2003 for GNE by doxygen1.3