/usr/include/gnelib/Thread.h is in libgnelib-dev 0.75+svn20091130-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 | #ifndef THREAD_H_INCLUDED_C51E3746
#define THREAD_H_INCLUDED_C51E3746
/* GNE - Game Networking Engine, a portable multithreaded networking library.
* Copyright (C) 2001-2006 Jason Winnebeck
* Project website: http://www.gillius.org/gne/
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library 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
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
#include <gnelib/Mutex.h>
#include <gnelib/SmartPtr.h>
#include <gnelib/WeakPtr.h>
#include <string>
namespace GNE {
/**
* @ingroup threading
*
* 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.
*/
class Thread {
public: //typedefs
typedef SmartPtr<Thread> sptr;
typedef WeakPtr<Thread> wptr;
public:
/**
* An enum for specifying the thread type. You should never need to use this
* directly, since anything you create should have type USER.
*/
enum ThreadType {
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. */
};
public:
/**
* Creates a new thread, ready to run but not yet running.
* @param name the name of this thread
* @param priority the priority this thread has
*/
Thread(std::string name = DEF_NAME, int priority = DEF_PRI);
virtual ~Thread();
/**
* 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.
*/
static sptr currentThread();
/**
* The currently running thread sleeps for the time given in milliseconds.
*/
static void sleep(int ms);
/**
* 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.
*/
static void yield();
/**
* 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 definitively
* 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.
*
* @param 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.
* @return false if all threads have completed, or true if there are still
* some threads running and the method timed out.
*
* @see requestAllShutdown
* @see Connection::disconnectAll
* @see GNE::shutdownGNE
* @see Timer::stopAll
*/
static bool waitForAllThreads(int ms);
/**
* 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 appropriate functions of those classes.
*
* Threads marked as SYSTEM should never be touched by the user. They will
* shutdown when GNE exits.
*
* @see Connection::disconnectAll
* @see Timer::stopAll
*/
static void requestAllShutdown( ThreadType threadType );
/**
* Returns the name of this thread.
*/
std::string getName() const;
/**
* 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 dependent 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.
*/
virtual void shutDown();
/**
* A blocking call that returns when this thread terminates, or returns
* immediately if the thread has terminated.
*/
void join();
/**
* Returns true if this Thread has ever been started. This remains true if
* even after the Thread has stopped running.
*/
bool hasStarted() const;
/**
* Determine the running state of the thread. If running is true, then
* started must be true.
*/
bool isRunning() const;
/**
* 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.
*
* @pre hasStarted returns false
*/
void start();
/**
* Returns the priority of this class.
*/
int getPriority() const;
/**
* The default priority of a thread.
*/
static const int DEF_PRI;
/**
* The default name for a thread.
*/
static const std::string DEF_NAME;
/**
* A lowered priority for a thread. Might be good for background
* operations like loading and saving files or something so it does not
* interfere with the user interface (be it a GUI or a game or whatever).
*/
static const int LOW_PRI;
/**
* A lower priority for a thread than LOW_PRI.
*/
static const int LOWER_PRI;
/**
* 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.
*/
static const int HIGH_PRI;
/**
* Even higher priority thread than HIGH_PRI. Used typically for the timer
* threads.
*/
static const int HIGHER_PRI;
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 getThisPointer
*/
void setThisPointer( const wptr& thisPtr );
/**
* Returns a SmartPtr to this object.
*
* @see setThisPointer
*/
sptr getThisPointer() const;
/**
* 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 setType( ThreadType newType );
/**
* 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.
*/
volatile bool shutdown;
/**
* 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.
*/
virtual void run() = 0;
private:
struct ThreadIDData;
ThreadIDData* id;
#ifdef WIN32
static unsigned __stdcall threadStart(void* thread);
#else
static void* threadStart(void* thread);
#endif
/**
* Detaches the thread if it wasn't joined on when it is destructed.
*/
void detach();
/**
* This function is called internally and automatically after run ends and
* is used for internal library cleanup.
*/
void end();
static void remove( const ThreadIDData& d );
wptr thisThread;
ThreadType type;
std::string name;
bool started;
bool running;
bool joined;
int priority;
Mutex joinSync; //needed for multiple threads joining.
};
}
#endif /* THREAD_H_INCLUDED_C51E3746 */
|