#include <Thread.h>
Inheritance diagram for GNE::Thread:
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. |
|
An enum for specifing the thread type. You should never need to use this directly, since anything you create should have type USER.
|
|
Creates a new thread, ready to run but not yet running.
|
|
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. |
|
Returns a SmartPtr to this object.
|
|
Returns true if this Thread has ever been started. This remains true if even after the Thread has stopped running. |
|
Determine the running state of the thread. If running is true, then started must be true. |
|
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.
|
|
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. |
|
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).
|
|
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. |
|
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. |
|
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.
|
|
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.
|
|
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. |
|
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. |
|
Even higher priority thread than HIGH_PRI. Used typically for the timer threads. |
|
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). |
|
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. |