1 | /** @file
|
---|
2 | * Incredibly Portable Runtime - Threads.
|
---|
3 | */
|
---|
4 |
|
---|
5 | /*
|
---|
6 | * Copyright (C) 2006-2007 Sun Microsystems, Inc.
|
---|
7 | *
|
---|
8 | * This file is part of VirtualBox Open Source Edition (OSE), as
|
---|
9 | * available from http://www.virtualbox.org. This file is free software;
|
---|
10 | * you can redistribute it and/or modify it under the terms of the GNU
|
---|
11 | * General Public License (GPL) as published by the Free Software
|
---|
12 | * Foundation, in version 2 as it comes in the "COPYING" file of the
|
---|
13 | * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
|
---|
14 | * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
|
---|
15 | *
|
---|
16 | * The contents of this file may alternatively be used under the terms
|
---|
17 | * of the Common Development and Distribution License Version 1.0
|
---|
18 | * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
|
---|
19 | * VirtualBox OSE distribution, in which case the provisions of the
|
---|
20 | * CDDL are applicable instead of those of the GPL.
|
---|
21 | *
|
---|
22 | * You may elect to license modified versions of this file under the
|
---|
23 | * terms and conditions of either the GPL or the CDDL or both.
|
---|
24 | *
|
---|
25 | * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
|
---|
26 | * Clara, CA 95054 USA or visit http://www.sun.com if you need
|
---|
27 | * additional information or have any questions.
|
---|
28 | */
|
---|
29 |
|
---|
30 | #ifndef ___iprt_thread_h
|
---|
31 | #define ___iprt_thread_h
|
---|
32 |
|
---|
33 | #include <iprt/cdefs.h>
|
---|
34 | #include <iprt/types.h>
|
---|
35 |
|
---|
36 | #ifdef IN_GC
|
---|
37 | # error "There are no threading APIs available Guest Context!"
|
---|
38 | #endif
|
---|
39 |
|
---|
40 |
|
---|
41 |
|
---|
42 | __BEGIN_DECLS
|
---|
43 |
|
---|
44 | /** @defgroup grp_rt_thread RTThread - Thread Management
|
---|
45 | * @ingroup grp_rt
|
---|
46 | * @{
|
---|
47 | */
|
---|
48 |
|
---|
49 | /**
|
---|
50 | * Get the thread handle of the current thread.
|
---|
51 | *
|
---|
52 | * @returns Thread handle.
|
---|
53 | */
|
---|
54 | RTDECL(RTTHREAD) RTThreadSelf(void);
|
---|
55 |
|
---|
56 | /**
|
---|
57 | * Get the native thread handle of the current thread.
|
---|
58 | *
|
---|
59 | * @returns Native thread handle.
|
---|
60 | */
|
---|
61 | RTDECL(RTNATIVETHREAD) RTThreadNativeSelf(void);
|
---|
62 |
|
---|
63 | /**
|
---|
64 | * Millisecond granular sleep function.
|
---|
65 | *
|
---|
66 | * @returns VINF_SUCCESS on success.
|
---|
67 | * @returns VERR_INTERRUPTED if a signal or other asynchronous stuff happend
|
---|
68 | * which interrupt the peaceful sleep.
|
---|
69 | * @param cMillies Number of milliseconds to sleep.
|
---|
70 | * 0 milliseconds means yielding the timeslice - deprecated!
|
---|
71 | * @remark See RTThreadNanoSleep() for sleeping for smaller periods of time.
|
---|
72 | */
|
---|
73 | RTDECL(int) RTThreadSleep(unsigned cMillies);
|
---|
74 |
|
---|
75 | /**
|
---|
76 | * Yields the CPU.
|
---|
77 | *
|
---|
78 | * @returns true if we yielded.
|
---|
79 | * @returns false if it's probable that we didn't yield.
|
---|
80 | */
|
---|
81 | RTDECL(bool) RTThreadYield(void);
|
---|
82 |
|
---|
83 |
|
---|
84 |
|
---|
85 | /**
|
---|
86 | * Thread function.
|
---|
87 | *
|
---|
88 | * @returns 0 on success.
|
---|
89 | * @param ThreadSelf Thread handle to this thread.
|
---|
90 | * @param pvUser User argument.
|
---|
91 | */
|
---|
92 | typedef DECLCALLBACK(int) FNRTTHREAD(RTTHREAD ThreadSelf, void *pvUser);
|
---|
93 | /** Pointer to a FNRTTHREAD(). */
|
---|
94 | typedef FNRTTHREAD *PFNRTTHREAD;
|
---|
95 |
|
---|
96 | /**
|
---|
97 | * Thread types.
|
---|
98 | * Besides identifying the purpose of the thread, the thread type is
|
---|
99 | * used to select the scheduling properties.
|
---|
100 | *
|
---|
101 | * The types in are placed in a rough order of ascending priority.
|
---|
102 | */
|
---|
103 | typedef enum RTTHREADTYPE
|
---|
104 | {
|
---|
105 | /** Invalid type. */
|
---|
106 | RTTHREADTYPE_INVALID = 0,
|
---|
107 | /** Infrequent poller thread.
|
---|
108 | * This type of thread will sleep for the most of the time, and do
|
---|
109 | * infrequent polls on resources at 0.5 sec or higher intervals.
|
---|
110 | */
|
---|
111 | RTTHREADTYPE_INFREQUENT_POLLER,
|
---|
112 | /** Main heavy worker thread.
|
---|
113 | * Thread of this type is driving asynchronous tasks in the Main
|
---|
114 | * API which takes a long time and might involve a bit of CPU. Like
|
---|
115 | * for instance creating a fixed sized VDI.
|
---|
116 | */
|
---|
117 | RTTHREADTYPE_MAIN_HEAVY_WORKER,
|
---|
118 | /** The emulation thread type.
|
---|
119 | * While being a thread with very high workload it still is vital
|
---|
120 | * that it gets scheduled frequently. When possible all other thread
|
---|
121 | * types except DEFAULT and GUI should interrupt this one ASAP when
|
---|
122 | * they become ready.
|
---|
123 | */
|
---|
124 | RTTHREADTYPE_EMULATION,
|
---|
125 | /** The default thread type.
|
---|
126 | * Since it doesn't say much about the purpose of the thread
|
---|
127 | * nothing special is normally done to the scheduling. This type
|
---|
128 | * should be avoided.
|
---|
129 | * The main thread is registered with default type during RTR3Init()
|
---|
130 | * and that's what the default process priority is derived from.
|
---|
131 | */
|
---|
132 | RTTHREADTYPE_DEFAULT,
|
---|
133 | /** The GUI thread type
|
---|
134 | * The GUI normally have a low workload but is frequently scheduled
|
---|
135 | * to handle events. When possible the scheduler should not leave
|
---|
136 | * threads of this kind waiting for too long (~50ms).
|
---|
137 | */
|
---|
138 | RTTHREADTYPE_GUI,
|
---|
139 | /** Main worker thread.
|
---|
140 | * Thread of this type is driving asynchronous tasks in the Main API.
|
---|
141 | * In most cases this means little work an a lot of waiting.
|
---|
142 | */
|
---|
143 | RTTHREADTYPE_MAIN_WORKER,
|
---|
144 | /** VRDP I/O thread.
|
---|
145 | * These threads are I/O threads in the RDP server will hang around
|
---|
146 | * waiting for data, process it and pass it on.
|
---|
147 | */
|
---|
148 | RTTHREADTYPE_VRDP_IO,
|
---|
149 | /** The debugger type.
|
---|
150 | * Threads involved in servicing the debugger. It must remain
|
---|
151 | * responsive even when things are running wild in.
|
---|
152 | */
|
---|
153 | RTTHREADTYPE_DEBUGGER,
|
---|
154 | /** Message pump thread.
|
---|
155 | * Thread pumping messages from one thread/process to another
|
---|
156 | * thread/process. The workload is very small, most of the time
|
---|
157 | * it's blocked waiting for messages to be procduced or processed.
|
---|
158 | * This type of thread will be favored after I/O threads.
|
---|
159 | */
|
---|
160 | RTTHREADTYPE_MSG_PUMP,
|
---|
161 | /** The I/O thread type.
|
---|
162 | * Doing I/O means shuffling data, waiting for request to arrive and
|
---|
163 | * for them to complete. The thread should be favored when competing
|
---|
164 | * with any other threads except timer threads.
|
---|
165 | */
|
---|
166 | RTTHREADTYPE_IO,
|
---|
167 | /** The timer thread type.
|
---|
168 | * A timer thread is mostly waiting for the timer to tick
|
---|
169 | * and then perform a little bit of work. Accuracy is important here,
|
---|
170 | * so the thread should be favoured over all threads. If premention can
|
---|
171 | * be configured at thread level, it could be made very short.
|
---|
172 | */
|
---|
173 | RTTHREADTYPE_TIMER,
|
---|
174 | /** Only used for validation. */
|
---|
175 | RTTHREADTYPE_END
|
---|
176 | } RTTHREADTYPE;
|
---|
177 |
|
---|
178 |
|
---|
179 | /**
|
---|
180 | * Thread creation flags.
|
---|
181 | */
|
---|
182 | typedef enum RTTHREADFLAGS
|
---|
183 | {
|
---|
184 | /**
|
---|
185 | * This flag is used to keep the thread structure around so it can
|
---|
186 | * be waited on after termination.
|
---|
187 | */
|
---|
188 | RTTHREADFLAGS_WAITABLE = RT_BIT(0),
|
---|
189 | /** The bit number corresponding to the RTTHREADFLAGS_WAITABLE mask. */
|
---|
190 | RTTHREADFLAGS_WAITABLE_BIT = 0,
|
---|
191 |
|
---|
192 | /** Mask of valid flags, use for validation. */
|
---|
193 | RTTHREADFLAGS_MASK = RT_BIT(0)
|
---|
194 | } RTTHREADFLAGS;
|
---|
195 |
|
---|
196 |
|
---|
197 | /**
|
---|
198 | * Create a new thread.
|
---|
199 | *
|
---|
200 | * @returns iprt status code.
|
---|
201 | * @param pThread Where to store the thread handle to the new thread. (optional)
|
---|
202 | * @param pfnThread The thread function.
|
---|
203 | * @param pvUser User argument.
|
---|
204 | * @param cbStack The size of the stack for the new thread.
|
---|
205 | * Use 0 for the default stack size.
|
---|
206 | * @param enmType The thread type. Used for deciding scheduling attributes
|
---|
207 | * of the thread.
|
---|
208 | * @param fFlags Flags of the RTTHREADFLAGS type (ORed together).
|
---|
209 | * @param pszName Thread name.
|
---|
210 | *
|
---|
211 | * @remark When called in Ring-0, this API will create a new kernel thread and not a thread in
|
---|
212 | * the context of the calling process.
|
---|
213 | */
|
---|
214 | RTDECL(int) RTThreadCreate(PRTTHREAD pThread, PFNRTTHREAD pfnThread, void *pvUser, size_t cbStack,
|
---|
215 | RTTHREADTYPE enmType, unsigned fFlags, const char *pszName);
|
---|
216 |
|
---|
217 | /**
|
---|
218 | * Gets the native thread id of a IPRT thread.
|
---|
219 | *
|
---|
220 | * @returns The native thread id.
|
---|
221 | * @param Thread The IPRT thread.
|
---|
222 | */
|
---|
223 | RTDECL(RTNATIVETHREAD) RTThreadGetNative(RTTHREAD Thread);
|
---|
224 |
|
---|
225 | /**
|
---|
226 | * Gets the IPRT thread of a native thread.
|
---|
227 | *
|
---|
228 | * @returns The IPRT thread handle
|
---|
229 | * @returns NIL_RTTHREAD if not a thread known to IPRT.
|
---|
230 | * @param NativeThread The native thread handle/id.
|
---|
231 | */
|
---|
232 | RTDECL(RTTHREAD) RTThreadFromNative(RTNATIVETHREAD NativeThread);
|
---|
233 |
|
---|
234 | /**
|
---|
235 | * Changes the type of the specified thread.
|
---|
236 | *
|
---|
237 | * @returns iprt status code.
|
---|
238 | * @param Thread The thread which type should be changed.
|
---|
239 | * @param enmType The new thread type.
|
---|
240 | * @remark In Ring-0 it only works if Thread == RTThreadSelf().
|
---|
241 | */
|
---|
242 | RTDECL(int) RTThreadSetType(RTTHREAD Thread, RTTHREADTYPE enmType);
|
---|
243 |
|
---|
244 | /**
|
---|
245 | * Wait for the thread to terminate, resume on interruption.
|
---|
246 | *
|
---|
247 | * @returns iprt status code.
|
---|
248 | * Will not return VERR_INTERRUPTED.
|
---|
249 | * @param Thread The thread to wait for.
|
---|
250 | * @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for
|
---|
251 | * an indefinite wait.
|
---|
252 | * @param prc Where to store the return code of the thread. Optional.
|
---|
253 | */
|
---|
254 | RTDECL(int) RTThreadWait(RTTHREAD Thread, unsigned cMillies, int *prc);
|
---|
255 |
|
---|
256 | /**
|
---|
257 | * Wait for the thread to terminate, return on interruption.
|
---|
258 | *
|
---|
259 | * @returns iprt status code.
|
---|
260 | * @param Thread The thread to wait for.
|
---|
261 | * @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for
|
---|
262 | * an indefinite wait.
|
---|
263 | * @param prc Where to store the return code of the thread. Optional.
|
---|
264 | */
|
---|
265 | RTDECL(int) RTThreadWaitNoResume(RTTHREAD Thread, unsigned cMillies, int *prc);
|
---|
266 |
|
---|
267 | /**
|
---|
268 | * Gets the name of the current thread thread.
|
---|
269 | *
|
---|
270 | * @returns Pointer to readonly name string.
|
---|
271 | * @returns NULL on failure.
|
---|
272 | */
|
---|
273 | RTDECL(const char *) RTThreadSelfName(void);
|
---|
274 |
|
---|
275 | /**
|
---|
276 | * Gets the name of a thread.
|
---|
277 | *
|
---|
278 | * @returns Pointer to readonly name string.
|
---|
279 | * @returns NULL on failure.
|
---|
280 | * @param Thread Thread handle of the thread to query the name of.
|
---|
281 | */
|
---|
282 | RTDECL(const char *) RTThreadGetName(RTTHREAD Thread);
|
---|
283 |
|
---|
284 | /**
|
---|
285 | * Gets the type of the specified thread.
|
---|
286 | *
|
---|
287 | * @returns The thread type.
|
---|
288 | * @returns RTTHREADTYPE_INVALID if the thread handle is invalid.
|
---|
289 | * @param Thread The thread in question.
|
---|
290 | */
|
---|
291 | RTDECL(RTTHREADTYPE) RTThreadGetType(RTTHREAD Thread);
|
---|
292 |
|
---|
293 | /**
|
---|
294 | * Sets the name of a thread.
|
---|
295 | *
|
---|
296 | * @returns iprt status code.
|
---|
297 | * @param Thread Thread handle of the thread to query the name of.
|
---|
298 | * @param pszName The thread name.
|
---|
299 | */
|
---|
300 | RTDECL(int) RTThreadSetName(RTTHREAD Thread, const char *pszName);
|
---|
301 |
|
---|
302 | /**
|
---|
303 | * Signal the user event.
|
---|
304 | *
|
---|
305 | * @returns iprt status code.
|
---|
306 | */
|
---|
307 | RTDECL(int) RTThreadUserSignal(RTTHREAD Thread);
|
---|
308 |
|
---|
309 | /**
|
---|
310 | * Wait for the user event.
|
---|
311 | *
|
---|
312 | * @returns iprt status code.
|
---|
313 | * @param Thread The thread to wait for.
|
---|
314 | * @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for
|
---|
315 | * an indefinite wait.
|
---|
316 | */
|
---|
317 | RTDECL(int) RTThreadUserWait(RTTHREAD Thread, unsigned cMillies);
|
---|
318 |
|
---|
319 | /**
|
---|
320 | * Wait for the user event, return on interruption.
|
---|
321 | *
|
---|
322 | * @returns iprt status code.
|
---|
323 | * @param Thread The thread to wait for.
|
---|
324 | * @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for
|
---|
325 | * an indefinite wait.
|
---|
326 | */
|
---|
327 | RTDECL(int) RTThreadUserWaitNoResume(RTTHREAD Thread, unsigned cMillies);
|
---|
328 |
|
---|
329 | /**
|
---|
330 | * Reset the user event.
|
---|
331 | *
|
---|
332 | * @returns iprt status code.
|
---|
333 | * @param Thread The thread to reset.
|
---|
334 | */
|
---|
335 | RTDECL(int) RTThreadUserReset(RTTHREAD Thread);
|
---|
336 |
|
---|
337 |
|
---|
338 | #ifdef IN_RING3
|
---|
339 |
|
---|
340 | /**
|
---|
341 | * Adopts a non-IPRT thread.
|
---|
342 | *
|
---|
343 | * @returns IPRT status code.
|
---|
344 | * @param enmType The thread type.
|
---|
345 | * @param fFlags The thread flags. RTTHREADFLAGS_WAITABLE is not currently allowed.
|
---|
346 | * @param pszName The thread name. Optional
|
---|
347 | * @param pThread Where to store the thread handle. Optional.
|
---|
348 | */
|
---|
349 | RTDECL(int) RTThreadAdopt(RTTHREADTYPE enmType, unsigned fFlags, const char *pszName, PRTTHREAD pThread);
|
---|
350 |
|
---|
351 | /**
|
---|
352 | * Gets the affinity mask of the current thread.
|
---|
353 | *
|
---|
354 | * @returns The affinity mask (bit 0 = logical cpu 0).
|
---|
355 | */
|
---|
356 | RTR3DECL(uint64_t) RTThreadGetAffinity(void);
|
---|
357 |
|
---|
358 | /**
|
---|
359 | * Sets the affinity mask of the current thread.
|
---|
360 | *
|
---|
361 | * @returns iprt status code.
|
---|
362 | * @param u64Mask Affinity mask (bit 0 = logical cpu 0).
|
---|
363 | */
|
---|
364 | RTR3DECL(int) RTThreadSetAffinity(uint64_t u64Mask);
|
---|
365 |
|
---|
366 |
|
---|
367 | /** @name Thread Local Storage
|
---|
368 | * @{
|
---|
369 | */
|
---|
370 | /**
|
---|
371 | * Thread termination callback for destroying a non-zero TLS entry.
|
---|
372 | *
|
---|
373 | * @remarks It is not permittable to use any RTTls APIs at this time. Doing so
|
---|
374 | * may lead to endless loops, crashes, and other bad stuff.
|
---|
375 | *
|
---|
376 | * @param pvValue The current value.
|
---|
377 | */
|
---|
378 | typedef DECLCALLBACK(void) FNRTTLSDTOR(void *pvValue);
|
---|
379 | /** Pointer to a FNRTTLSDTOR. */
|
---|
380 | typedef FNRTTLSDTOR *PFNRTTLSDTOR;
|
---|
381 |
|
---|
382 | /**
|
---|
383 | * Allocates a TLS entry.
|
---|
384 | *
|
---|
385 | * @returns the index of the allocated TLS entry.
|
---|
386 | * @returns NIL_RTTLS on failure.
|
---|
387 | */
|
---|
388 | RTR3DECL(RTTLS) RTTlsAlloc(void);
|
---|
389 |
|
---|
390 | /**
|
---|
391 | * Allocates a TLS entry (with status code).
|
---|
392 | *
|
---|
393 | * @returns IPRT status code.
|
---|
394 | * @retval VERR_NOT_SUPPORTED if pfnDestructor is non-NULL and the platform
|
---|
395 | * doesn't support this feature.
|
---|
396 | *
|
---|
397 | * @param piTls Where to store the index of the allocated TLS entry.
|
---|
398 | * This is set to NIL_RTTLS on failure.
|
---|
399 | * @param pfnDestructor Optional callback function for cleaning up on
|
---|
400 | * thread termination. WARNING! This feature may not
|
---|
401 | * be implemented everywhere.
|
---|
402 | */
|
---|
403 | RTR3DECL(int) RTTlsAllocEx(PRTTLS piTls, PFNRTTLSDTOR pfnDestructor);
|
---|
404 |
|
---|
405 | /**
|
---|
406 | * Frees a TLS entry.
|
---|
407 | *
|
---|
408 | * @returns IPRT status code.
|
---|
409 | * @param iTls The index of the TLS entry.
|
---|
410 | */
|
---|
411 | RTR3DECL(int) RTTlsFree(RTTLS iTls);
|
---|
412 |
|
---|
413 | /**
|
---|
414 | * Get the value stored in a TLS entry.
|
---|
415 | *
|
---|
416 | * @returns value in given TLS entry.
|
---|
417 | * @returns NULL on failure.
|
---|
418 | * @param iTls The index of the TLS entry.
|
---|
419 | */
|
---|
420 | RTR3DECL(void *) RTTlsGet(RTTLS iTls);
|
---|
421 |
|
---|
422 | /**
|
---|
423 | * Get the value stored in a TLS entry.
|
---|
424 | *
|
---|
425 | * @returns IPRT status code.
|
---|
426 | * @param iTls The index of the TLS entry.
|
---|
427 | * @param ppvValue Where to store the value.
|
---|
428 | */
|
---|
429 | RTR3DECL(int) RTTlsGetEx(RTTLS iTls, void **ppvValue);
|
---|
430 |
|
---|
431 | /**
|
---|
432 | * Set the value stored in an allocated TLS entry.
|
---|
433 | *
|
---|
434 | * @returns IPRT status.
|
---|
435 | * @param iTls The index of the TLS entry.
|
---|
436 | * @param pvValue The value to store.
|
---|
437 | *
|
---|
438 | * @remarks Note that NULL is considered to special value.
|
---|
439 | */
|
---|
440 | RTR3DECL(int) RTTlsSet(RTTLS iTls, void *pvValue);
|
---|
441 |
|
---|
442 | /** @} */
|
---|
443 |
|
---|
444 | #endif /* IN_RING3 */
|
---|
445 |
|
---|
446 | /** @} */
|
---|
447 |
|
---|
448 | __END_DECLS
|
---|
449 |
|
---|
450 | #endif
|
---|
451 |
|
---|