VirtualBox

source: vbox/trunk/include/iprt/thread.h@ 8163

Last change on this file since 8163 was 8163, checked in by vboxsync, 17 years ago

rebrand IPRT

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 13.8 KB
Line 
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 */
54RTDECL(RTTHREAD) RTThreadSelf(void);
55
56/**
57 * Get the native thread handle of the current thread.
58 *
59 * @returns Native thread handle.
60 */
61RTDECL(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 */
73RTDECL(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 */
81RTDECL(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 */
92typedef DECLCALLBACK(int) FNRTTHREAD(RTTHREAD ThreadSelf, void *pvUser);
93/** Pointer to a FNRTTHREAD(). */
94typedef 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 */
103typedef 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 */
182typedef 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 */
214RTDECL(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 */
223RTDECL(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 */
232RTDECL(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 */
242RTDECL(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 */
254RTDECL(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 */
265RTDECL(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 */
273RTDECL(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 */
282RTDECL(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 */
291RTDECL(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 */
300RTDECL(int) RTThreadSetName(RTTHREAD Thread, const char *pszName);
301
302/**
303 * Signal the user event.
304 *
305 * @returns iprt status code.
306 */
307RTDECL(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 */
317RTDECL(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 */
327RTDECL(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 */
335RTDECL(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 */
349RTDECL(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 */
356RTR3DECL(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 */
364RTR3DECL(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 */
378typedef DECLCALLBACK(void) FNRTTLSDTOR(void *pvValue);
379/** Pointer to a FNRTTLSDTOR. */
380typedef 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 */
388RTR3DECL(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 */
403RTR3DECL(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 */
411RTR3DECL(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 */
420RTR3DECL(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 */
429RTR3DECL(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 */
440RTR3DECL(int) RTTlsSet(RTTLS iTls, void *pvValue);
441
442/** @} */
443
444#endif /* IN_RING3 */
445
446/** @} */
447
448__END_DECLS
449
450#endif
451
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette