Main MRPT website > C++ reference for MRPT 1.5.7
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 #include <thread>
14 #include <memory>
15 
16 namespace mrpt
17 {
18  namespace system
19  {
20  /** \addtogroup mrpt_thread Threads (in #include <mrpt/system/threads.h>)
21  * \ingroup mrpt_base_grp
22  * @{ */
23 
24  /** A MRPT thread handle. Like std::thread, but have copy semantics, via
25  * an internal std::shared_ptr<std::thread> object.
26  * \sa createThread
27  */
29  {
30  std::shared_ptr<std::thread> m_thread;
31 
32  TThreadHandle() : m_thread(std::make_shared<std::thread>()) {}
34 
35  /** Mark the handle as invalid.
36  * \sa isClear
37  */
38  void clear()
39  {
40  if (m_thread && m_thread->joinable())
41  m_thread->detach();
42  m_thread = std::make_shared<std::thread>();
43  }
44  /** Returns true if the handle is uninitialized */
45  bool isClear() const { return !m_thread || !m_thread->joinable(); }
46  };
47 
48  /** The type for cross-platform process (application) priorities.
49  * \sa changeCurrentProcessPriority
50  */
52  ppIdle = 0,
56  };
57 
58  /** The type for cross-platform thread priorities.
59  * \sa changeThreadPriority
60  */
62  tpLowests =-15, // Win32: THREAD_PRIORITY_IDLE
63  tpLower = -2, // Win32: THREAD_PRIORITY_LOWEST
64  tpLow = -1, // Win32: THREAD_PRIORITY_BELOW_NORMAL
65  tpNormal = 0, // Win32: THREAD_PRIORITY_NORMAL
66  tpHigh = 1, // Win32: THREAD_PRIORITY_ABOVE_NORMAL
67  tpHigher = 2, // Win32: THREAD_PRIORITY_HIGHEST
68  tpHighest = 15 // Win32: THREAD_PRIORITY_TIME_CRITICAL
69  };
70 
71  /** Creates a new thread from a function (or static method) with one generic parameter.
72  * This function creates, and starts a new thread running some code given by a function.
73  * The thread function should end by returning as normal.
74  * \param func The function with the code to run in the thread.
75  * \param param The parameter to be passed to the new thread function.
76  * \return A structure that represents the thread (it contains its ID and, in Windows, its HANDLE).
77  * \exception std::exception If the operation fails
78  * \sa createThreadFromObjectMethod, joinThread, changeThreadPriority
79  */
80  template<typename T> inline TThreadHandle createThread(void (*func)(T),T param) {
81  TThreadHandle h;
82  h.m_thread = std::make_shared<std::thread>(func, param);
83  return h;
84  }
85  //! \overload
86  template<typename T> inline TThreadHandle createThreadRef(void (*func)(T&),T& param) {
87  TThreadHandle h;
88  h.m_thread = std::make_shared<std::thread>(func, std::ref<T>(param));
89  return h;
90  }
91  //! \overload
92  inline TThreadHandle createThread(void (*func)(void)) {
93  TThreadHandle h;
94  h.m_thread = std::make_shared<std::thread>(func);
95  return h;
96  }
97 
98  /** 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.
99  * This function creates, and starts a new thread running some code given by a function.
100  * The thread function should end by returning as normal.
101  * Example of usage:
102  *
103  * \code
104  * class MyClass {
105  * public:
106  * void myThread(int n);
107  * void someMethod() {
108  * createThreadFromObjectMethod(this, &MyClass::myThread, 123 );
109  * ....
110  * }
111  * };
112  * \endcode
113  *
114  * \param func The function with the code to run in the thread.
115  * \param param The parameter to be passed to the new thread function.
116  * \return A structure that represents the thread (it contains its ID and, in Windows, its HANDLE).
117  * \exception std::exception If the operation fails
118  * \sa createThread, joinThread, changeThreadPriority
119  */
120  template <typename CLASS,typename PARAM>
121  inline TThreadHandle createThreadFromObjectMethod(CLASS *obj, void (CLASS::*func)(PARAM), PARAM param) {
122  TThreadHandle h;
123  h.m_thread = std::make_shared<std::thread>(func, obj,param);
124  return h;
125  }
126  //! \overload
127  template <typename CLASS,typename PARAM>
128  inline TThreadHandle createThreadFromObjectMethodRef(CLASS *obj, void (CLASS::*func)(PARAM&), PARAM &param) {
129  TThreadHandle h;
130  h.m_thread = std::make_shared<std::thread>(func, obj, param);
131  return h;
132  }
133  //! \overload
134  template <typename CLASS>
135  inline TThreadHandle createThreadFromObjectMethod(CLASS *obj, void (CLASS::*func)(void)) {
136  TThreadHandle h;
137  h.m_thread = std::make_shared<std::thread>(func, obj);
138  return h;
139  }
140 
141 
142  /** Waits until the given thread ends.
143  * \sa createThread
144  */
145  void BASE_IMPEXP joinThread( TThreadHandle &threadHandle );
146 
147  /** Returns the ID of the current thread.
148  */
150 
151  /** Explicit close of the current (running) thread.
152  * Do not use normally, it's better just to return from the running thread function.
153  * \sa createThread
154  */
156 
157  /** Returns the creation and exit times of the current thread and its CPU time consumed.
158  * \param creationTime The creation time of the thread.
159  * \param exitTime The exit time of the thread, or undefined if it is still running.
160  * \param cpuTime The CPU time consumed by the thread, in seconds.
161  * \exception std::exception If the operation fails
162  * \sa getCurrentThreadId, createThread
163  */
165  time_t &creationTime,
166  time_t &exitTime,
167  double &cpuTime );
168 
169  /** Change the priority of the current thread - for Windows, see also changeCurrentProcessPriority()
170  * - Windows: This is equivalent to [SetThreadPriority()](https://msdn.microsoft.com/en-us/library/windows/desktop/ms686277(v=vs.85).aspx) (read the docs there)
171  * - 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).
172  * \sa createThread, changeCurrentProcessPriority, changeCurrentThreadPriority
173  */
175 
176  /** Terminate a thread, giving it no choice to delete objects, etc (use only as a last resource) */
177  void BASE_IMPEXP terminateThread( TThreadHandle &threadHandle) MRPT_NO_THROWS;
178 
179  /** Change the priority of the given process (it applies to all the threads, plus independent modifiers for each thread).
180  * - Windows: See [SetPriorityClass](https://msdn.microsoft.com/es-es/library/windows/desktop/ms686219(v=vs.85).aspx)
181  * - 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
182  () was called and a SCHED_RR is already active.
183  * \sa createThread, changeThreadPriority
184  */
186 
187  /** Return the number of processors ("cores"), or 1 if it cannot be determined.
188  */
189  unsigned int BASE_IMPEXP getNumberOfProcessors();
190 
191  /** An OS-independent method for sending the current thread to "sleep" for a given period of time.
192  * \param time_ms The sleep period, in miliseconds.
193  */
194  void BASE_IMPEXP sleep( int time_ms ) MRPT_NO_THROWS;
195 
196  /** Executes the given command (which may contain a program + arguments), and waits until it finishes.
197  * \return false on any error, true otherwise
198  */
199  bool BASE_IMPEXP launchProcess( const std::string & command );
200 
201  /** @} */
202 
203  } // End of namespace
204 
205 } // End of namespace
206 
207 #endif
TThreadPriority
The type for cross-platform thread priorities.
Definition: threads.h:61
unsigned long BASE_IMPEXP getCurrentThreadId() MRPT_NO_THROWS
Returns the ID of the current thread.
Definition: threads.cpp:83
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:144
unsigned int BASE_IMPEXP getNumberOfProcessors()
Return the number of processors ("cores"), or 1 if it cannot be determined.
Definition: threads.cpp:327
#define MRPT_NO_THROWS
C++11 noexcept: Used after member declarations.
STL namespace.
TProcessPriority
The type for cross-platform process (application) priorities.
Definition: threads.h:51
GLsizei GLsizei GLuint * obj
Definition: glext.h:3902
TThreadHandle createThreadRef(void(*func)(T &), T &param)
Definition: threads.h:86
TThreadHandle createThread(void(*func)(T), T param)
Creates a new thread from a function (or static method) with one generic parameter.
Definition: threads.h:80
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:295
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:180
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:45
void clear()
Mark the handle as invalid.
Definition: threads.h:38
void BASE_IMPEXP joinThread(TThreadHandle &threadHandle)
Waits until the given thread ends.
Definition: threads.cpp:74
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:121
TThreadHandle createThreadFromObjectMethodRef(CLASS *obj, void(CLASS::*func)(PARAM &), PARAM &param)
Definition: threads.h:128
This is the global namespace for all Mobile Robot Programming Toolkit (MRPT) libraries.
std::shared_ptr< std::thread > m_thread
Definition: threads.h:30
A MRPT thread handle.
Definition: threads.h:28
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:379
void BASE_IMPEXP changeCurrentThreadPriority(TThreadPriority priority)
Change the priority of the current thread - for Windows, see also changeCurrentProcessPriority() ...
Definition: threads.cpp:94
GLfloat param
Definition: glext.h:3705
void BASE_IMPEXP exitThread() MRPT_NO_THROWS
Explicit close of the current (running) thread.
Definition: threads.cpp:367



Page generated by Doxygen 1.8.14 for MRPT 1.5.7 Git: 5902e14cc Wed Apr 24 15:04:01 2019 +0200 at lun oct 28 01:39:17 CET 2019