root/OpenSceneGraph/trunk/include/OpenThreads/Thread @ 13041

Revision 13041, 12.1 kB (checked in by robert, 3 years ago)

Ran script to remove trailing spaces and tabs

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1/* -*-c++-*- OpenThreads library, Copyright (C) 2002 - 2007  The Open Thread Group
2 *
3 * This library is open source and may be redistributed and/or modified under
4 * the terms of the OpenSceneGraph Public License (OSGPL) version 0.0 or
5 * (at your option) any later version.  The full license is in LICENSE file
6 * included with this distribution, and on the openscenegraph.org website.
7 *
8 * This library is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11 * OpenSceneGraph Public License for more details.
12*/
13
14
15//
16// Thread - C++ Thread class
17// ~~~~~~~~
18//
19
20#ifndef _OPENTHREADS_THREAD_
21#define _OPENTHREADS_THREAD_
22
23#include <sys/types.h>
24
25#include <OpenThreads/Mutex>
26
27namespace OpenThreads {
28
29/**
30 *  Get the number of processors.
31 *
32 *  Note, systems where no support exists for querrying the number of processors, 1 is returned.
33 *
34 */
35extern OPENTHREAD_EXPORT_DIRECTIVE int GetNumberOfProcessors();
36
37/**
38 *  Set the processor affinity of current thread.
39 *
40 *  Note, systems where no support exists no affinity will be set, and -1 will be returned.
41 *
42 */
43extern OPENTHREAD_EXPORT_DIRECTIVE int SetProcessorAffinityOfCurrentThread(unsigned int cpunum);
44
45/**
46 *  @class Thread
47 *  @brief  This class provides an object-oriented thread interface.
48 */
49class OPENTHREAD_EXPORT_DIRECTIVE Thread {
50
51public:
52
53    /**
54     *  Set the concurrency level for a running application.  This method
55     *  only has effect if the pthreads thread model is being used, and
56     *  then only when that model is many-to-one (eg. irix).
57     *  in other cases it is ignored.  The concurrency level is only a
58     *  *hint* as to the number of execution vehicles to use, the actual
59     *  implementation may do anything it wants.  Setting the value
60     *  to 0 returns things to their default state.
61     *
62     *  @return previous concurrency level, -1 indicates no-op.
63     */
64    static int SetConcurrency(int concurrencyLevel);
65
66    /**
67     *  Get the concurrency level for a running application.  In this
68     *  case, a return code of 0 means that the application is in default
69     *  mode.  A return code of -1 means that the application is incapable
70     *  of setting an arbitrary concurrency, because it is a one-to-one
71     *  execution model (sprocs, linuxThreads)
72     */
73    static int GetConcurrency();
74
75    /**
76     *  Enumerated Type for thread priority
77     */
78    enum ThreadPriority {
79
80        THREAD_PRIORITY_MAX,      /**< The maximum possible priority  */
81        THREAD_PRIORITY_HIGH,     /**< A high (but not max) setting   */
82        THREAD_PRIORITY_NOMINAL,  /**< An average priority            */
83        THREAD_PRIORITY_LOW,      /**< A low (but not min) setting    */
84        THREAD_PRIORITY_MIN,      /**< The miniumum possible priority */
85        THREAD_PRIORITY_DEFAULT   /**< Priority scheduling default    */
86
87    };
88
89    /**
90     *  Enumerated Type for thread scheduling policy
91     */
92    enum ThreadPolicy {
93
94        THREAD_SCHEDULE_FIFO,        /**< First in, First out scheduling         */
95        THREAD_SCHEDULE_ROUND_ROBIN, /**< Round-robin scheduling (LINUX_DEFAULT) */
96        THREAD_SCHEDULE_TIME_SHARE,  /**< Time-share scheduling (IRIX DEFAULT)   */
97        THREAD_SCHEDULE_DEFAULT      /**< Default scheduling                     */
98
99    };
100
101    /**
102     *  Constructor
103     */
104    Thread();
105
106    /**
107     *  Destructor
108     */
109    virtual ~Thread();
110
111
112    /**
113     *  Return a pointer to the current running thread
114     */
115    static Thread *CurrentThread();
116
117
118    /**
119     *  Initialize Threading in a program.  This method must be called before
120     *  you can do any threading in a program.
121     */
122    static void Init();
123
124    /**
125     *  Yield the processor.
126     *
127     *  @note This method operates on the calling process.  And is
128     *  equivalent to calling sched_yield().
129     *
130     *  @return 0 if normal, -1 if errno set, errno code otherwise.
131     */
132    static int YieldCurrentThread();
133
134    /**
135     *  This method will return the ThreadPriority of the master process.
136     *  (ie, the one calling the thread->start() methods for the first time)
137     *  The method will almost certainly return
138     *  Thread::THREAD_PRIORITY_DEFAULT if
139     *  Init() has not been called.
140     *
141     *  @return the Thread::ThreadPriority of the master thread.
142     */
143    static ThreadPriority GetMasterPriority() {return s_masterThreadPriority;};
144
145
146    /**
147     *  Get a unique thread id.  This id is monotonically increasing.
148     *
149     *  @return a unique thread identifier
150     */
151    int getThreadId();
152
153    /**
154     *  Get the thread's process id.  This is the pthread_t or pid_t value
155     *  depending on the threading model being used.
156     *
157     *  @return thread process id.
158     */
159    size_t getProcessId();
160
161    /**
162     *  Start the thread.  This method will configure the thread, set
163     *  it's priority, and spawn it.
164     *
165     *  @note if the stack size specified setStackSize is smaller than the
166     *  smallest allowable stack size,  the threads stack size will be set to
167     *  the minimum allowed, and may be retrieved via the getStackSize()
168     *
169     *  @return 0 if normal, -1 if errno set, errno code otherwise.
170     */
171    int start();
172    int startThread();
173
174    /**
175     * Test the cancel state of the thread.  If the thread has been canceled
176     * this method will cause the thread to exit now.  This method operates
177     * on the calling thread.
178     *
179     * Returns 0 if normal, -1 if called from a thread other that this.
180     */
181    int testCancel();
182
183
184    /**
185     *  Cancel the thread.  Equivalent to SIGKILL.
186     *
187     *  @return 0 if normal, -1 if errno set, errno code otherwise.
188     */
189    virtual int cancel();
190
191    /**
192     *  Set the thread's schedule priority.  This is a complex method.
193     *  Beware of thread priorities when using a many-to-many kernel
194     *  entity implemenation (such as IRIX pthreads).  If one is not carefull
195     *  to manage the thread priorities, a priority inversion deadlock can
196     *  easily occur (Although the OpenThreads::Mutex & OpenThreads::Barrier
197     *  constructs have been designed with this senario in mind).  Unless
198     *  you have explicit need to set the schedule pirorites for a given
199     *  task, it is best to leave them alone.
200     *
201     *  @note some implementations (notably LinuxThreads and IRIX Sprocs)
202     *  only alow you to decrease thread priorities dynamically.  Thus,
203     *  a lower priority thread will not allow it's priority to be raised
204     *  on the fly.
205     *
206     *  @note seting the environment variable OUTPUT_THREADLIB_SCHEDULING_INFO
207     *  will output scheduling information for each thread to stdout.
208     *
209     *  @return 0 if normal, -1 if errno set, errno code otherwise.
210     */
211    int setSchedulePriority(ThreadPriority priority);
212
213    /**
214     *  Get the thread's schedule priority (if able)
215     *
216     *  @note seting the environment variable OUTPUT_THREADLIB_SCHEDULING_INFO
217     *  will output scheduling information for each thread to stdout.
218     *
219     *  @return 0 if normal, -1 if errno set, errno code otherwise.
220     */
221    int getSchedulePriority();
222
223    /**
224     *  Set the thread's scheduling policy (if able)
225     *
226     *  @note On some implementations (notably IRIX Sprocs & LinuxThreads)
227     *  The policy may prohibit the use of SCHEDULE_ROUND_ROBIN and
228     *  SCHEDULE_FIFO policies - due to their real-time nature, and
229     *  the danger of deadlocking the machine when used as super-user.
230     *  In such cases, the command is a no-op.
231     *
232     *  @note seting the environment variable OUTPUT_THREADLIB_SCHEDULING_INFO
233     *  will output scheduling information for each thread to stdout.
234     *
235     *  @return 0 if normal, -1 if errno set, errno code otherwise.
236     */
237    int setSchedulePolicy(ThreadPolicy policy);
238
239    /**
240     *  Get the thread's policy (if able)
241     *
242     *  @note seting the environment variable OUTPUT_THREADLIB_SCHEDULING_INFO
243     *  will output scheduling information for each thread to stdout.
244     *
245     *  @return policy if normal, -1 if errno set, errno code otherwise.
246     */
247    int getSchedulePolicy();
248
249    /**
250     *  Set the thread's desired stack size (in bytes).
251     *  This method is an attribute of the thread and must be called
252     *  *before* the start() method is invoked.
253     *
254     *  @note a return code of 13 (EACESS) means that the thread stack
255     *  size can no longer be changed.
256     *
257     *  @return 0 if normal, -1 if errno set, errno code otherwise.
258     */
259    int setStackSize(size_t size);
260
261    /**
262     *  Get the thread's desired stack size.
263     *
264     *  @return the thread's stack size.  0 indicates that the stack size
265     *   has either not yet been initialized, or not yet been specified by
266     *   the application.
267     */
268    size_t getStackSize();
269
270    /**
271     *  Print the thread's scheduling information to stdout.
272     */
273    void printSchedulingInfo();
274
275    /**
276     *  Detach the thread from the calling process.
277     *
278     *  @return 0 if normal, -1 if errno set, errno code otherwise.
279     */
280    int detach();
281
282    /**
283     *  Join the calling process with the thread
284     *
285     *  @return 0 if normal, -1 if errno set, errno code otherwise.
286     */
287    int join();
288
289    /**
290     *  Disable thread cancelation altogether. Thread::cancel() has no effect.
291     *
292     *  @return 0 if normal, -1 if errno set, errno code otherwise.
293     */
294    int setCancelModeDisable();
295
296    /**
297     *  Mark the thread to cancel aysncronously on Thread::cancel().
298     *  (May not be available with process-level implementations).
299     *
300     *  @return 0 if normal, -1 if errno set, errno code otherwise.
301     */
302    int setCancelModeAsynchronous();
303
304    /**
305     *  Mark the thread to cancel at the earliest convenience on
306     *  Thread::cancel() (This is the default)
307     *
308     *  @return 0 if normal, -1 if errno set, errno code otherwise.
309     */
310    int setCancelModeDeferred();
311
312    /**
313     *  Query the thread's running status
314     *
315     *  @return true if running, false if not.
316     */
317    bool isRunning();
318
319    /**
320     *  Thread's run method.  Must be implemented by derived classes.
321     *  This is where the action happens.
322     */
323    virtual void run() = 0;
324
325    /**
326     *  Thread's cancel cleanup routine, called upon cancel(), after the
327     *  cancelation has taken place, but before the thread exits completely.
328     *  This method should be used to repair parts of the thread's data
329     *  that may have been damaged by a pre-mature cancel.  No-op by default.
330     */
331    virtual void cancelCleanup() {};
332
333    void* getImplementation(){ return _prvData; };
334
335    /** Thread's processor affinity method.  This binds a thread to a
336      * processor whenever possible.   This call must be made before
337      * start() or startThread() and has no effect after the thread
338      * has been running.  In the pthreads implementation, this is only
339      * implemented on sgi, through a pthread extension.  On other pthread
340      * platforms this is ignored.  Returns 0 on success, implementation's
341      * error on failure, or -1 if ignored.
342      */
343    int setProcessorAffinity( unsigned int cpunum );
344
345    /** microSleep method, equivilant to the posix usleep(microsec).
346      *  This is not strictly thread API but is used
347      * so often with threads. It's basically UNIX usleep. Parameter is
348      * number of microseconds we current thread to sleep. Returns 0 on
349      * succes, non-zero on failure (UNIX errno or GetLastError() will give
350      * detailed description.
351      */
352    static int microSleep( unsigned int microsec);
353
354private:
355
356    /**
357     *  The Private Actions class is allowed to operate on private data.
358     */
359    friend class ThreadPrivateActions;
360
361     /**
362      *  Private copy constructor, to prevent tampering.
363      */
364    Thread(const Thread &/*t*/) {};
365
366    /**
367      *  Private copy assignment, to prevent tampering.
368      */
369    Thread &operator=(const Thread &/*t*/) {return *(this);};
370
371    /**
372     *  Implementation-specific data
373     */
374    void * _prvData;
375
376    /**
377     *  Master thread's priority, set by Thread::Init.
378     */
379    static ThreadPriority s_masterThreadPriority;
380
381    /**
382     *  Is initialized flag
383     */
384    static bool s_isInitialized;
385};
386
387}
388
389#endif // !_OPENTHREADS_THREAD_
Note: See TracBrowser for help on using the browser.