Main MRPT website > C++ reference for MRPT 1.5.5
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-2017, 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 
12 #include <mrpt/utils/core_defs.h>
13 
14 namespace 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:
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 starts 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 starts 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) */
271  void BASE_IMPEXP terminateThread( TThreadHandle &threadHandle) MRPT_NO_THROWS;
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  */
282  unsigned int BASE_IMPEXP getNumberOfProcessors();
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
TThreadPriority
The type for cross-platform thread priorities.
Definition: threads.h:80
unsigned long BASE_IMPEXP getCurrentThreadId() MRPT_NO_THROWS
Returns the ID of the current thread.
Definition: threads.cpp:211
void BASE_IMPEXP changeCurrentProcessPriority(TProcessPriority priority)
Change the priority of the given process (it applies to all the threads, plus independent modifiers f...
Definition: threads.cpp:303
void BASE_IMPEXP changeThreadPriority(const TThreadHandle &threadHandle, TThreadPriority priority)
Change the priority of the given thread - for Windows, see also changeCurrentProcessPriority() ...
Definition: threads.cpp:250
TThreadHandle BASE_IMPEXP getCurrentThreadHandle() MRPT_NO_THROWS
Returns a handle to the current thread.
Definition: threads.cpp:231
unsigned int BASE_IMPEXP getNumberOfProcessors()
Return the number of processors ("cores"), or 1 if it cannot be determined.
Definition: threads.cpp:486
#define MRPT_NO_THROWS
C++11 noexcept: Used after member declarations.
STL namespace.
static TThreadHandle createThread(CLASS *o, objectfunctor_t f, PARAM param)
Definition: threads.h:146
TProcessPriority
The type for cross-platform process (application) priorities.
Definition: threads.h:70
GLsizei GLsizei GLuint * obj
Definition: glext.h:3902
TThreadHandle createThreadRef(void(*func)(T &), T &param)
Definition: threads.h:185
static TThreadHandle createThread(void(*f)(void *), void *param)
Definition: threads.h:111
void clear()
Clear the contents of this container.
Definition: ts_hash_map.h:113
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
bool BASE_IMPEXP launchProcess(const std::string &command)
Executes the given command (which may contain a program + arguments), and waits until it finishes...
Definition: threads.cpp:454
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.
Definition: threads.cpp:339
static TThreadHandle createThread(void(*f)(T), T param)
Definition: threads.h:103
ThreadCreateObjectFunctor(CLASS *o, objectfunctor_t f, PARAM param)
Definition: threads.h:139
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...
Definition: threads.cpp:57
bool isClear() const
Returns true if the handle is uninitialized.
Definition: threads.h:64
static void createThreadAux(void *obj)
Definition: threads.h:98
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
TThreadHandle createThreadFromObjectMethodRef(CLASS *obj, void(CLASS::*func)(PARAM &), PARAM &param)
Definition: threads.h:221
This is the global namespace for all Mobile Robot Programming Toolkit (MRPT) libraries.
This structure contains the information needed to interface the threads API on each platform: ...
Definition: threads.h:25
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) ...
Definition: threads.cpp:538
typedef void(APIENTRYP PFNGLBLENDCOLORPROC)(GLclampf red
TThreadHandle BASE_IMPEXP createThreadImpl(void(*func)(void *), void *param)
Definition: threads.cpp:141
static TThreadHandle createThread(void(*f)(void))
Definition: threads.h:126
GLfloat param
Definition: glext.h:3705
GLfloat GLfloat p
Definition: glext.h:5587
void BASE_IMPEXP exitThread() MRPT_NO_THROWS
Explicit close of the current (running) thread.
Definition: threads.cpp:526
static TThreadHandle createThread(CLASS *o, objectfunctor_t f)
Definition: threads.h:165
void BASE_IMPEXP joinThread(const TThreadHandle &threadHandle)
Waits until the given thread ends.
Definition: threads.cpp:190



Page generated by Doxygen 1.8.14 for MRPT 1.5.5 Git: e06b63dbf Fri Dec 1 14:41:11 2017 +0100 at lun oct 28 01:31:35 CET 2019