Main MRPT website > C++ reference for MRPT 1.4.0
threads.h
Go to the documentation of this file.
1/* +---------------------------------------------------------------------------+
2 | Mobile Robot Programming Toolkit (MRPT) |
3 | http://www.mrpt.org/ |
4 | |
5 | Copyright (c) 2005-2016, Individual contributors, see AUTHORS file |
6 | See: http://www.mrpt.org/Authors - All rights reserved. |
7 | Released under BSD License. See details in http://www.mrpt.org/License |
8 +---------------------------------------------------------------------------+ */
9#ifndef MRPT_SYSTEM_THREADS_H
10#define MRPT_SYSTEM_THREADS_H
11
13
14namespace mrpt
15{
16 namespace system
17 {
18 /** \addtogroup mrpt_thread Threads (in #include <mrpt/system/threads.h>)
19 * \ingroup mrpt_base_grp
20 * @{ */
21
22 /** This structure contains the information needed to interface the threads API on each platform:
23 * \sa createThread
24 */
26 {
27#ifdef MRPT_OS_WINDOWS
28 TThreadHandle() : //!< Sets the handle to a predefined value meaning it is uninitialized.
29 hThread(NULL),
30 idThread(0)
31 {
32 }
33
34 /** Mark the handle as invalid.
35 * \sa isClear
36 */
37 void clear()
38 {
39 idThread = 0;
40 hThread = NULL;
41 }
42 void *hThread; //!< The thread "HANDLE"
43# if defined(HAVE_OPENTHREAD) // defined(_MSC_VER) && (_MSC_VER>=1400)
44 uintptr_t idThread; //!< The thread ID.
45# else
46 unsigned long idThread; //!< The thread ID.
47# endif
48#endif
49#if defined(MRPT_OS_LINUX) || defined(MRPT_OS_APPLE)
50 TThreadHandle() : idThread(0) //!< Sets the handle to a predefined value meaning it is uninitialized.
51 {
52 }
53 unsigned long idThread; //!< The thread ID.
54
55 /** Mark the handle as invalid.
56 * \sa isClear
57 */
58 void clear()
59 {
60 idThread = 0;
61 }
62#endif
63 /** Returns true if the handle is uninitialized */
64 bool isClear() const { return idThread==0; }
65 };
66
67 /** The type for cross-platform process (application) priorities.
68 * \sa changeCurrentProcessPriority
69 */
71 ppIdle = 0,
75 };
76
77 /** The type for cross-platform thread priorities.
78 * \sa changeThreadPriority
79 */
81 tpLowests =-15, // Win32: THREAD_PRIORITY_IDLE
82 tpLower = -2, // Win32: THREAD_PRIORITY_LOWEST
83 tpLow = -1, // Win32: THREAD_PRIORITY_BELOW_NORMAL
84 tpNormal = 0, // Win32: THREAD_PRIORITY_NORMAL
85 tpHigh = 1, // Win32: THREAD_PRIORITY_ABOVE_NORMAL
86 tpHigher = 2, // Win32: THREAD_PRIORITY_HIGHEST
87 tpHighest = 15 // Win32: THREAD_PRIORITY_TIME_CRITICAL
88 };
89
90 /** Auxiliary classes used internally to MRPT */
91 namespace detail {
92 TThreadHandle BASE_IMPEXP createThreadImpl(void (*func)(void *),void *param);
93 template<typename T> class ThreadCreateFunctor { //T may (and should!) be passed by reference, but mustn't be const.
94 public:
95 void (*func)(T);
96 T obj;
97 inline ThreadCreateFunctor(void (*f)(T),T o):func(f),obj(o) {}
98 inline static void createThreadAux(void *obj) {
99 ThreadCreateFunctor<T> *auxStruct=static_cast<ThreadCreateFunctor<T> *>(obj);
100 auxStruct->func(auxStruct->obj);
101 delete auxStruct;
102 }
103 inline static TThreadHandle createThread(void (*f)(T),T param) {
105 return createThreadImpl(&createThreadAux,static_cast<void *>(tcs));
106 }
107 };
108 // Specialization for T=void*, which is easier to handle:
109 template<> class ThreadCreateFunctor<void *> {
110 public:
111 inline static TThreadHandle createThread(void (*f)(void *),void *param) {
112 return createThreadImpl(f,param);
113 }
114 };
115 // Special case, since T cannot be "void":
117 public:
118 void (*func)(void);
119 ThreadCreateFunctorNoParams( void (*f)(void) ) : func(f) { }
120
121 inline static void createThreadAux(void *f) {
123 d->func(); // Call the user function.
124 delete d;
125 }
126 inline static TThreadHandle createThread( void (*f)(void) ) {
128 return createThreadImpl(&createThreadAux, static_cast<void*>(dat) );
129 }
130 };
131 // Template for running a non-static method of an object as a thread.
132 template <class CLASS,class PARAM>
134 public:
135 typedef void (CLASS::*objectfunctor_t)(PARAM);
136 CLASS *obj;
138 PARAM p;
139 inline ThreadCreateObjectFunctor(CLASS *o,objectfunctor_t f, PARAM param):obj(o),func(f),p(param) {}
140 inline static void createThreadAux(void *p) {
142 objectfunctor_t f = auxStruct->func;
143 (auxStruct->obj->*f)(auxStruct->p);
144 delete auxStruct;
145 }
146 inline static TThreadHandle createThread(CLASS *o,objectfunctor_t f, PARAM param) {
148 return createThreadImpl(&createThreadAux,static_cast<void *>(tcs));
149 }
150 };
151 // Template for running a non-static method of an object as a thread - no params
152 template <class CLASS>
154 public:
155 typedef void (CLASS::*objectfunctor_t)(void);
156 CLASS *obj;
159 inline static void createThreadAux(void *p) {
161 objectfunctor_t f = auxStruct->func;
162 (auxStruct->obj->*f)();
163 delete auxStruct;
164 }
165 inline static TThreadHandle createThread(CLASS *o,objectfunctor_t f) {
167 return createThreadImpl(&createThreadAux,static_cast<void *>(tcs));
168 }
169 };
170 } // end detail
171
172 /** Creates a new thread from a function (or static method) with one generic parameter.
173 * This function creates, and start, a new thread running some code given by a function.
174 * The thread function should end by returning as normal.
175 * \param func The function with the code to run in the thread.
176 * \param param The parameter to be passed to the new thread function.
177 * \return A structure that represents the thread (it contains its ID and, in Windows, its HANDLE).
178 * \exception std::exception If the operation fails
179 * \sa createThreadFromObjectMethod, joinThread, changeThreadPriority
180 */
181 template<typename T> inline TThreadHandle createThread(void (*func)(T),T param) {
183 }
184 //! \overload
185 template<typename T> inline TThreadHandle createThreadRef(void (*func)(T&),T& param) {
187 }
188 //! \overload
189 inline TThreadHandle createThread(void (*func)(void)) {
191 }
192
193 /** Creates a new thread running a non-static method (so it will have access to "this") from another method of the same class - with one generic parameter.
194 * This function creates, and start, a new thread running some code given by a function.
195 * The thread function should end by returning as normal.
196 * Example of usage:
197 *
198 * \code
199 * class MyClass {
200 * public:
201 * void myThread(int n);
202 * void someMethod() {
203 * createThreadFromObjectMethod(this, &MyClass::myThread, 123 );
204 * ....
205 * }
206 * };
207 * \endcode
208 *
209 * \param func The function with the code to run in the thread.
210 * \param param The parameter to be passed to the new thread function.
211 * \return A structure that represents the thread (it contains its ID and, in Windows, its HANDLE).
212 * \exception std::exception If the operation fails
213 * \sa createThread, joinThread, changeThreadPriority
214 */
215 template <typename CLASS,typename PARAM>
216 inline TThreadHandle createThreadFromObjectMethod(CLASS *obj, void (CLASS::*func)(PARAM), PARAM param) {
218 }
219 //! \overload
220 template <typename CLASS,typename PARAM>
221 inline TThreadHandle createThreadFromObjectMethodRef(CLASS *obj, void (CLASS::*func)(PARAM&), PARAM &param) {
223 }
224 //! \overload
225 template <typename CLASS>
226 inline TThreadHandle createThreadFromObjectMethod(CLASS *obj, void (CLASS::*func)(void)) {
228 }
229
230
231 /** Waits until the given thread ends.
232 * \sa createThread
233 */
234 void BASE_IMPEXP joinThread( const TThreadHandle &threadHandle );
235
236 /** Returns the ID of the current thread.
237 * \sa getCurrentThreadHandle
238 */
240
241 /** Returns a handle to the current thread.
242 */
244
245 /** Explicit close of the current (running) thread.
246 * Do not use normally, it's better just to return from the running thread function.
247 * \sa createThread
248 */
250
251 /** Returns the creation and exit times of the current thread and its CPU time consumed.
252 * \param creationTime The creation time of the thread.
253 * \param exitTime The exit time of the thread, or undefined if it is still running.
254 * \param cpuTime The CPU time consumed by the thread, in seconds.
255 * \exception std::exception If the operation fails
256 * \sa getCurrentThreadHandle, getCurrentThreadId, createThread
257 */
259 time_t &creationTime,
260 time_t &exitTime,
261 double &cpuTime );
262
263 /** Change the priority of the given thread - for Windows, see also changeCurrentProcessPriority()
264 * - Windows: This is equivalent to [SetThreadPriority()](https://msdn.microsoft.com/en-us/library/windows/desktop/ms686277(v=vs.85).aspx) (read the docs there)
265 * - Linux (pthreads): May require `root` permissions! This sets the Round Robin scheduler with the given priority level. Read [sched_setscheduler](http://linux.die.net/man/2/sched_setscheduler).
266 * \sa createThread, changeCurrentProcessPriority
267 */
268 void BASE_IMPEXP changeThreadPriority( const TThreadHandle &threadHandle, TThreadPriority priority );
269
270 /** Terminate a thread, giving it no choice to delete objects, etc (use only as a last resource) */
272
273 /** Change the priority of the given process (it applies to all the threads, plus independent modifiers for each thread).
274 * - Windows: See [SetPriorityClass](https://msdn.microsoft.com/es-es/library/windows/desktop/ms686219(v=vs.85).aspx)
275 * - Linux (pthreads): Requires `root` permissions to increase process priority! Internally it calls [nice()](http://linux.die.net/man/3/nice), so it has no effect if changeThreadPriority() was called and a SCHED_RR is already active.
276 * \sa createThread, changeThreadPriority
277 */
279
280 /** Return the number of processors ("cores"), or 1 if it cannot be determined.
281 */
283
284 /** An OS-independent method for sending the current thread to "sleep" for a given period of time.
285 * \param time_ms The sleep period, in miliseconds.
286 */
287 void BASE_IMPEXP sleep( int time_ms ) MRPT_NO_THROWS;
288
289 /** Executes the given command (which may contain a program + arguments), and waits until it finishes.
290 * \return false on any error, true otherwise
291 */
292 bool BASE_IMPEXP launchProcess( const std::string & command );
293
294 /** @} */
295
296 } // End of namespace
297
298} // End of namespace
299
300#endif
static TThreadHandle createThread(void(*f)(void *), void *param)
Definition: threads.h:111
static TThreadHandle createThread(void(*f)(T), T param)
Definition: threads.h:103
static void createThreadAux(void *obj)
Definition: threads.h:98
static TThreadHandle createThread(void(*f)(void))
Definition: threads.h:126
ThreadCreateObjectFunctor(CLASS *o, objectfunctor_t f, PARAM param)
Definition: threads.h:139
static TThreadHandle createThread(CLASS *o, objectfunctor_t f, PARAM param)
Definition: threads.h:146
static TThreadHandle createThread(CLASS *o, objectfunctor_t f)
Definition: threads.h:165
ThreadCreateObjectFunctorNoParams(CLASS *o, objectfunctor_t f)
Definition: threads.h:158
TThreadHandle createThreadFromObjectMethod(CLASS *obj, void(CLASS::*func)(PARAM), PARAM param)
Creates a new thread running a non-static method (so it will have access to "this") from another meth...
Definition: threads.h:216
void BASE_IMPEXP getCurrentThreadTimes(time_t &creationTime, time_t &exitTime, double &cpuTime)
Returns the creation and exit times of the current thread and its CPU time consumed.
unsigned int BASE_IMPEXP getNumberOfProcessors()
Return the number of processors ("cores"), or 1 if it cannot be determined.
TThreadHandle createThreadFromObjectMethodRef(CLASS *obj, void(CLASS::*func)(PARAM &), PARAM &param)
This is an overloaded member function, provided for convenience. It differs from the above function o...
Definition: threads.h:221
TThreadHandle createThread(void(*func)(T), T param)
Creates a new thread from a function (or static method) with one generic parameter.
Definition: threads.h:181
TThreadPriority
The type for cross-platform thread priorities.
Definition: threads.h:80
TThreadHandle BASE_IMPEXP getCurrentThreadHandle() MRPT_NO_THROWS
Returns a handle to the current thread.
void BASE_IMPEXP joinThread(const TThreadHandle &threadHandle)
Waits until the given thread ends.
TThreadHandle createThreadRef(void(*func)(T &), T &param)
This is an overloaded member function, provided for convenience. It differs from the above function o...
Definition: threads.h:185
unsigned long BASE_IMPEXP getCurrentThreadId() MRPT_NO_THROWS
Returns the ID of the current thread.
TProcessPriority
The type for cross-platform process (application) priorities.
Definition: threads.h:70
void BASE_IMPEXP changeThreadPriority(const TThreadHandle &threadHandle, TThreadPriority priority)
Change the priority of the given thread - for Windows, see also changeCurrentProcessPriority()
void BASE_IMPEXP changeCurrentProcessPriority(TProcessPriority priority)
Change the priority of the given process (it applies to all the threads, plus independent modifiers f...
void BASE_IMPEXP sleep(int time_ms) MRPT_NO_THROWS
An OS-independent method for sending the current thread to "sleep" for a given period of time.
bool BASE_IMPEXP launchProcess(const std::string &command)
Executes the given command (which may contain a program + arguments), and waits until it finishes.
void BASE_IMPEXP exitThread() MRPT_NO_THROWS
Explicit close of the current (running) thread.
void BASE_IMPEXP terminateThread(TThreadHandle &threadHandle) MRPT_NO_THROWS
Terminate a thread, giving it no choice to delete objects, etc (use only as a last resource)
@ ppVeryHigh
Definition: threads.h:74
#define MRPT_NO_THROWS
Used after member declarations.
Definition: mrpt_macros.h:391
TThreadHandle BASE_IMPEXP createThreadImpl(void(*func)(void *), void *param)
This is the global namespace for all Mobile Robot Programming Toolkit (MRPT) libraries.
STL namespace.
This structure contains the information needed to interface the threads API on each platform:
Definition: threads.h:26
bool isClear() const
Returns true if the handle is uninitialized.
Definition: threads.h:64



Page generated by Doxygen 1.9.6 for MRPT 1.4.0 SVN: at Fri Jan 20 02:28:26 UTC 2023