VirtualBox

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

Last change on this file since 27345 was 25724, checked in by vboxsync, 15 years ago

iprt: Use RTMSINTERVAL for timeouts. Fixed missing timeout underflow checks in two RTFileAioCtxWait implementations.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 23.3 KB
Line 
1/** @file
2 * IPRT - 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#include <iprt/stdarg.h>
36
37
38RT_C_DECLS_BEGIN
39
40/** @defgroup grp_rt_thread RTThread - Thread Management
41 * @ingroup grp_rt
42 * @{
43 */
44
45/**
46 * The thread state.
47 */
48typedef enum RTTHREADSTATE
49{
50 /** The usual invalid 0 value. */
51 RTTHREADSTATE_INVALID = 0,
52 /** The thread is being initialized. */
53 RTTHREADSTATE_INITIALIZING,
54 /** The thread has terminated */
55 RTTHREADSTATE_TERMINATED,
56 /** Probably running. */
57 RTTHREADSTATE_RUNNING,
58
59 /** Waiting on a critical section. */
60 RTTHREADSTATE_CRITSECT,
61 /** Waiting on a event semaphore. */
62 RTTHREADSTATE_EVENT,
63 /** Waiting on a event multiple wakeup semaphore. */
64 RTTHREADSTATE_EVENT_MULTI,
65 /** Waiting on a fast mutex. */
66 RTTHREADSTATE_FAST_MUTEX,
67 /** Waiting on a mutex. */
68 RTTHREADSTATE_MUTEX,
69 /** Waiting on a read write semaphore, read (shared) access. */
70 RTTHREADSTATE_RW_READ,
71 /** Waiting on a read write semaphore, write (exclusive) access. */
72 RTTHREADSTATE_RW_WRITE,
73 /** The thread is sleeping. */
74 RTTHREADSTATE_SLEEP,
75 /** Waiting on a spin mutex. */
76 RTTHREADSTATE_SPIN_MUTEX,
77
78 /** The usual 32-bit size hack. */
79 RTTHREADSTATE_32BIT_HACK = 0x7fffffff
80} RTTHREADSTATE;
81
82/** Checks if a thread state indicates that the thread is sleeping. */
83#define RTTHREAD_IS_SLEEPING(enmState) ((enmState) >= RTTHREADSTATE_CRITSECT)
84
85/**
86 * Thread types.
87 * Besides identifying the purpose of the thread, the thread type is
88 * used to select the scheduling properties.
89 *
90 * The types in are placed in a rough order of ascending priority.
91 */
92typedef enum RTTHREADTYPE
93{
94 /** Invalid type. */
95 RTTHREADTYPE_INVALID = 0,
96 /** Infrequent poller thread.
97 * This type of thread will sleep for the most of the time, and do
98 * infrequent polls on resources at 0.5 sec or higher intervals.
99 */
100 RTTHREADTYPE_INFREQUENT_POLLER,
101 /** Main heavy worker thread.
102 * Thread of this type is driving asynchronous tasks in the Main
103 * API which takes a long time and might involve a bit of CPU. Like
104 * for instance creating a fixed sized VDI.
105 */
106 RTTHREADTYPE_MAIN_HEAVY_WORKER,
107 /** The emulation thread type.
108 * While being a thread with very high workload it still is vital
109 * that it gets scheduled frequently. When possible all other thread
110 * types except DEFAULT and GUI should interrupt this one ASAP when
111 * they become ready.
112 */
113 RTTHREADTYPE_EMULATION,
114 /** The default thread type.
115 * Since it doesn't say much about the purpose of the thread
116 * nothing special is normally done to the scheduling. This type
117 * should be avoided.
118 * The main thread is registered with default type during RTR3Init()
119 * and that's what the default process priority is derived from.
120 */
121 RTTHREADTYPE_DEFAULT,
122 /** The GUI thread type
123 * The GUI normally have a low workload but is frequently scheduled
124 * to handle events. When possible the scheduler should not leave
125 * threads of this kind waiting for too long (~50ms).
126 */
127 RTTHREADTYPE_GUI,
128 /** Main worker thread.
129 * Thread of this type is driving asynchronous tasks in the Main API.
130 * In most cases this means little work an a lot of waiting.
131 */
132 RTTHREADTYPE_MAIN_WORKER,
133 /** VRDP I/O thread.
134 * These threads are I/O threads in the RDP server will hang around
135 * waiting for data, process it and pass it on.
136 */
137 RTTHREADTYPE_VRDP_IO,
138 /** The debugger type.
139 * Threads involved in servicing the debugger. It must remain
140 * responsive even when things are running wild in.
141 */
142 RTTHREADTYPE_DEBUGGER,
143 /** Message pump thread.
144 * Thread pumping messages from one thread/process to another
145 * thread/process. The workload is very small, most of the time
146 * it's blocked waiting for messages to be procduced or processed.
147 * This type of thread will be favored after I/O threads.
148 */
149 RTTHREADTYPE_MSG_PUMP,
150 /** The I/O thread type.
151 * Doing I/O means shuffling data, waiting for request to arrive and
152 * for them to complete. The thread should be favored when competing
153 * with any other threads except timer threads.
154 */
155 RTTHREADTYPE_IO,
156 /** The timer thread type.
157 * A timer thread is mostly waiting for the timer to tick
158 * and then perform a little bit of work. Accuracy is important here,
159 * so the thread should be favoured over all threads. If premention can
160 * be configured at thread level, it could be made very short.
161 */
162 RTTHREADTYPE_TIMER,
163 /** Only used for validation. */
164 RTTHREADTYPE_END
165} RTTHREADTYPE;
166
167
168#ifndef IN_RC
169
170/**
171 * Get the thread handle of the current thread.
172 *
173 * @returns Thread handle.
174 */
175RTDECL(RTTHREAD) RTThreadSelf(void);
176
177/**
178 * Get the thread handle of the current thread, automatically adopting alien
179 * threads.
180 *
181 * @returns Thread handle.
182 */
183RTDECL(RTTHREAD) RTThreadSelfAutoAdopt(void);
184
185/**
186 * Get the native thread handle of the current thread.
187 *
188 * @returns Native thread handle.
189 */
190RTDECL(RTNATIVETHREAD) RTThreadNativeSelf(void);
191
192/**
193 * Millisecond granular sleep function.
194 *
195 * @returns VINF_SUCCESS on success.
196 * @returns VERR_INTERRUPTED if a signal or other asynchronous stuff happend
197 * which interrupt the peaceful sleep.
198 * @param cMillies Number of milliseconds to sleep.
199 * 0 milliseconds means yielding the timeslice - deprecated!
200 * @remark See RTThreadNanoSleep() for sleeping for smaller periods of time.
201 */
202RTDECL(int) RTThreadSleep(RTMSINTERVAL cMillies);
203
204/**
205 * Yields the CPU.
206 *
207 * @returns true if we yielded.
208 * @returns false if it's probable that we didn't yield.
209 */
210RTDECL(bool) RTThreadYield(void);
211
212
213
214/**
215 * Thread function.
216 *
217 * @returns 0 on success.
218 * @param ThreadSelf Thread handle to this thread.
219 * @param pvUser User argument.
220 */
221typedef DECLCALLBACK(int) FNRTTHREAD(RTTHREAD ThreadSelf, void *pvUser);
222/** Pointer to a FNRTTHREAD(). */
223typedef FNRTTHREAD *PFNRTTHREAD;
224
225/**
226 * Thread creation flags.
227 */
228typedef enum RTTHREADFLAGS
229{
230 /**
231 * This flag is used to keep the thread structure around so it can
232 * be waited on after termination.
233 */
234 RTTHREADFLAGS_WAITABLE = RT_BIT(0),
235 /** The bit number corresponding to the RTTHREADFLAGS_WAITABLE mask. */
236 RTTHREADFLAGS_WAITABLE_BIT = 0,
237
238 /** Mask of valid flags, use for validation. */
239 RTTHREADFLAGS_MASK = RT_BIT(0)
240} RTTHREADFLAGS;
241
242
243/**
244 * Create a new thread.
245 *
246 * @returns iprt status code.
247 * @param pThread Where to store the thread handle to the new thread. (optional)
248 * @param pfnThread The thread function.
249 * @param pvUser User argument.
250 * @param cbStack The size of the stack for the new thread.
251 * Use 0 for the default stack size.
252 * @param enmType The thread type. Used for deciding scheduling attributes
253 * of the thread.
254 * @param fFlags Flags of the RTTHREADFLAGS type (ORed together).
255 * @param pszName Thread name.
256 *
257 * @remark When called in Ring-0, this API will create a new kernel thread and not a thread in
258 * the context of the calling process.
259 */
260RTDECL(int) RTThreadCreate(PRTTHREAD pThread, PFNRTTHREAD pfnThread, void *pvUser, size_t cbStack,
261 RTTHREADTYPE enmType, unsigned fFlags, const char *pszName);
262
263/**
264 * Create a new thread.
265 *
266 * Same as RTThreadCreate except the name is given in the RTStrPrintfV form.
267 *
268 * @returns iprt status code.
269 * @param pThread See RTThreadCreate.
270 * @param pfnThread See RTThreadCreate.
271 * @param pvUser See RTThreadCreate.
272 * @param cbStack See RTThreadCreate.
273 * @param enmType See RTThreadCreate.
274 * @param fFlags See RTThreadCreate.
275 * @param pszName Thread name format.
276 * @param va Format arguments.
277 */
278RTDECL(int) RTThreadCreateV(PRTTHREAD pThread, PFNRTTHREAD pfnThread, void *pvUser, size_t cbStack,
279 RTTHREADTYPE enmType, uint32_t fFlags, const char *pszNameFmt, va_list va);
280
281/**
282 * Create a new thread.
283 *
284 * Same as RTThreadCreate except the name is given in the RTStrPrintf form.
285 *
286 * @returns iprt status code.
287 * @param pThread See RTThreadCreate.
288 * @param pfnThread See RTThreadCreate.
289 * @param pvUser See RTThreadCreate.
290 * @param cbStack See RTThreadCreate.
291 * @param enmType See RTThreadCreate.
292 * @param fFlags See RTThreadCreate.
293 * @param pszName Thread name format.
294 * @param ... Format arguments.
295 */
296RTDECL(int) RTThreadCreateF(PRTTHREAD pThread, PFNRTTHREAD pfnThread, void *pvUser, size_t cbStack,
297 RTTHREADTYPE enmType, uint32_t fFlags, const char *pszNameFmt, ...);
298
299/**
300 * Gets the native thread id of a IPRT thread.
301 *
302 * @returns The native thread id.
303 * @param Thread The IPRT thread.
304 */
305RTDECL(RTNATIVETHREAD) RTThreadGetNative(RTTHREAD Thread);
306
307/**
308 * Gets the IPRT thread of a native thread.
309 *
310 * @returns The IPRT thread handle
311 * @returns NIL_RTTHREAD if not a thread known to IPRT.
312 * @param NativeThread The native thread handle/id.
313 */
314RTDECL(RTTHREAD) RTThreadFromNative(RTNATIVETHREAD NativeThread);
315
316/**
317 * Changes the type of the specified thread.
318 *
319 * @returns iprt status code.
320 * @param Thread The thread which type should be changed.
321 * @param enmType The new thread type.
322 * @remark In Ring-0 it only works if Thread == RTThreadSelf().
323 */
324RTDECL(int) RTThreadSetType(RTTHREAD Thread, RTTHREADTYPE enmType);
325
326/**
327 * Wait for the thread to terminate, resume on interruption.
328 *
329 * @returns iprt status code.
330 * Will not return VERR_INTERRUPTED.
331 * @param Thread The thread to wait for.
332 * @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for
333 * an indefinite wait.
334 * @param prc Where to store the return code of the thread. Optional.
335 */
336RTDECL(int) RTThreadWait(RTTHREAD Thread, RTMSINTERVAL cMillies, int *prc);
337
338/**
339 * Wait for the thread to terminate, return on interruption.
340 *
341 * @returns iprt status code.
342 * @param Thread The thread to wait for.
343 * @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for
344 * an indefinite wait.
345 * @param prc Where to store the return code of the thread. Optional.
346 */
347RTDECL(int) RTThreadWaitNoResume(RTTHREAD Thread, RTMSINTERVAL cMillies, int *prc);
348
349/**
350 * Gets the name of the current thread thread.
351 *
352 * @returns Pointer to readonly name string.
353 * @returns NULL on failure.
354 */
355RTDECL(const char *) RTThreadSelfName(void);
356
357/**
358 * Gets the name of a thread.
359 *
360 * @returns Pointer to readonly name string.
361 * @returns NULL on failure.
362 * @param Thread Thread handle of the thread to query the name of.
363 */
364RTDECL(const char *) RTThreadGetName(RTTHREAD Thread);
365
366/**
367 * Gets the type of the specified thread.
368 *
369 * @returns The thread type.
370 * @returns RTTHREADTYPE_INVALID if the thread handle is invalid.
371 * @param Thread The thread in question.
372 */
373RTDECL(RTTHREADTYPE) RTThreadGetType(RTTHREAD Thread);
374
375/**
376 * Sets the name of a thread.
377 *
378 * @returns iprt status code.
379 * @param Thread Thread handle of the thread to query the name of.
380 * @param pszName The thread name.
381 */
382RTDECL(int) RTThreadSetName(RTTHREAD Thread, const char *pszName);
383
384/**
385 * Checks if the specified thread is the main thread.
386 *
387 * @returns true if it is, false if it isn't.
388 *
389 * @param hThread The thread handle.
390 */
391RTDECL(bool) RTThreadIsMain(RTTHREAD hThread);
392
393/**
394 * Signal the user event.
395 *
396 * @returns iprt status code.
397 */
398RTDECL(int) RTThreadUserSignal(RTTHREAD Thread);
399
400/**
401 * Wait for the user event.
402 *
403 * @returns iprt status code.
404 * @param Thread The thread to wait for.
405 * @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for
406 * an indefinite wait.
407 */
408RTDECL(int) RTThreadUserWait(RTTHREAD Thread, RTMSINTERVAL cMillies);
409
410/**
411 * Wait for the user event, return on interruption.
412 *
413 * @returns iprt status code.
414 * @param Thread The thread to wait for.
415 * @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for
416 * an indefinite wait.
417 */
418RTDECL(int) RTThreadUserWaitNoResume(RTTHREAD Thread, RTMSINTERVAL cMillies);
419
420/**
421 * Reset the user event.
422 *
423 * @returns iprt status code.
424 * @param Thread The thread to reset.
425 */
426RTDECL(int) RTThreadUserReset(RTTHREAD Thread);
427
428/**
429 * Pokes the thread.
430 *
431 * This will signal the thread, attempting to interrupt whatever it's currently
432 * doing. This is *NOT* implemented on all platforms and may cause unresolved
433 * symbols during linking or VERR_NOT_IMPLEMENTED at runtime.
434 *
435 * @returns IPRT status code.
436 *
437 * @param hThread The thread to poke. This must not be the
438 * calling thread.
439 */
440RTDECL(int) RTThreadPoke(RTTHREAD hThread);
441
442# ifdef IN_RING0
443
444/**
445 * Check if preemption is currently enabled or not for the current thread.
446 *
447 * @note This may return true even on systems where preemption isn't
448 * possible. In that case, it means no call to RTThreadPreemptDisable
449 * has been made and interrupts are still enabled.
450 *
451 * @returns true if preemtion is enabled, false if preemetion is disabled.
452 * @param hThread Must be NIL_RTTHREAD for now.
453 */
454RTDECL(bool) RTThreadPreemptIsEnabled(RTTHREAD hThread);
455
456/**
457 * Check if preemption is pending for the current thread.
458 *
459 * This function should be called regularly when executing larger portions of
460 * code with preemption disabled.
461 *
462 * @returns true if pending, false if not.
463 * @param hThread Must be NIL_RTTHREAD for now.
464 */
465RTDECL(bool) RTThreadPreemptIsPending(RTTHREAD hThread);
466
467/**
468 * Is RTThreadPreemptIsPending reliable?
469 *
470 * @returns true if reliable, false if not.
471 */
472RTDECL(bool) RTThreadPreemptIsPendingTrusty(void);
473
474/**
475 * Is preemption possible on this system.
476 *
477 * @returns true if possible, false if not.
478 */
479RTDECL(bool) RTThreadPreemptIsPossible(void);
480
481/**
482 * Preemption state saved by RTThreadPreemptDisable and used by
483 * RTThreadPreemptRestore to restore the previous state.
484 */
485typedef struct RTTHREADPREEMPTSTATE
486{
487 /** In debug builds this will be used to check for cpu migration. */
488 RTCPUID idCpu;
489# ifdef RT_OS_WINDOWS
490 /** The old IRQL. Don't touch! */
491 unsigned char uchOldIrql;
492 /** Reserved, MBZ. */
493 uint8_t bReserved1;
494 /** Reserved, MBZ. */
495 uint8_t bReserved2;
496 /** Reserved, MBZ. */
497 uint8_t bReserved3;
498# define RTTHREADPREEMPTSTATE_INITIALIZER { NIL_RTCPUID, 255, 0, 0, 0 }
499# elif defined(RT_OS_SOLARIS)
500 /** The Old PIL. Don't touch! */
501 uint32_t uOldPil;
502# define RTTHREADPREEMPTSTATE_INITIALIZER { NIL_RTCPUID, UINT32_MAX }
503# else
504 /** Reserved, MBZ. */
505 uint32_t u32Reserved;
506# define RTTHREADPREEMPTSTATE_INITIALIZER { NIL_RTCPUID, 0 }
507# endif
508} RTTHREADPREEMPTSTATE;
509/** Pointer to a preemption state. */
510typedef RTTHREADPREEMPTSTATE *PRTTHREADPREEMPTSTATE;
511
512/**
513 * Disable preemption.
514 *
515 * A call to this function must be matched by exactly one call to
516 * RTThreadPreemptRestore().
517 *
518 * @param pState Where to store the preemption state.
519 */
520RTDECL(void) RTThreadPreemptDisable(PRTTHREADPREEMPTSTATE pState);
521
522/**
523 * Restores the preemption state, undoing a previous call to
524 * RTThreadPreemptDisable.
525 *
526 * A call to this function must be matching a previous call to
527 * RTThreadPreemptDisable.
528 *
529 * @param pState The state return by RTThreadPreemptDisable.
530 */
531RTDECL(void) RTThreadPreemptRestore(PRTTHREADPREEMPTSTATE pState);
532
533/**
534 * Check if the thread is executing in interrupt context.
535 *
536 * @returns true if in interrupt context, false if not.
537 * @param hThread Must be NIL_RTTHREAD for now.
538 */
539RTDECL(bool) RTThreadIsInInterrupt(RTTHREAD hThread);
540
541# endif /* IN_RING0 */
542
543
544# ifdef IN_RING3
545
546/**
547 * Adopts a non-IPRT thread.
548 *
549 * @returns IPRT status code.
550 * @param enmType The thread type.
551 * @param fFlags The thread flags. RTTHREADFLAGS_WAITABLE is not currently allowed.
552 * @param pszName The thread name. Optional
553 * @param pThread Where to store the thread handle. Optional.
554 */
555RTDECL(int) RTThreadAdopt(RTTHREADTYPE enmType, unsigned fFlags, const char *pszName, PRTTHREAD pThread);
556
557/**
558 * Gets the affinity mask of the current thread.
559 *
560 * @returns The affinity mask (bit 0 = logical cpu 0).
561 */
562RTR3DECL(uint64_t) RTThreadGetAffinity(void);
563
564/**
565 * Sets the affinity mask of the current thread.
566 *
567 * @returns iprt status code.
568 * @param u64Mask Affinity mask (bit 0 = logical cpu 0).
569 */
570RTR3DECL(int) RTThreadSetAffinity(uint64_t u64Mask);
571
572/**
573 * Unblocks a thread.
574 *
575 * This function is paired with RTThreadBlocking and RTThreadBlockingDebug.
576 *
577 * @param hThread The current thread.
578 * @param enmCurState The current state, used to check for nested blocking.
579 * The new state will be running.
580 */
581RTDECL(void) RTThreadUnblocked(RTTHREAD hThread, RTTHREADSTATE enmCurState);
582
583/**
584 * Change the thread state to blocking.
585 *
586 * @param hThread The current thread.
587 * @param enmState The sleep state.
588 * @param fReallySleeping Really going to sleep now. Use false before calls
589 * to other IPRT synchronization methods.
590 */
591RTDECL(void) RTThreadBlocking(RTTHREAD hThread, RTTHREADSTATE enmState, bool fReallySleeping);
592
593/**
594 * Get the current thread state.
595 *
596 * A thread that is reported as sleeping may actually still be running inside
597 * the lock validator or/and in the code of some other IPRT synchronization
598 * primitive. Use RTThreadGetReallySleeping
599 *
600 * @returns The thread state.
601 * @param hThread The thread.
602 */
603RTDECL(RTTHREADSTATE) RTThreadGetState(RTTHREAD hThread);
604
605/**
606 * Checks if the thread is really sleeping or not.
607 *
608 * @returns RTTHREADSTATE_RUNNING if not really sleeping, otherwise the state it
609 * is sleeping in.
610 * @param hThread The thread.
611 */
612RTDECL(RTTHREADSTATE) RTThreadGetReallySleeping(RTTHREAD hThread);
613
614/**
615 * Translate a thread state into a string.
616 *
617 * @returns Pointer to a read-only string containing the state name.
618 * @param enmState The state.
619 */
620RTDECL(const char *) RTThreadStateName(RTTHREADSTATE enmState);
621
622
623/**
624 * Native thread states returned by RTThreadNativeState.
625 */
626typedef enum RTTHREADNATIVESTATE
627{
628 /** Invalid thread handle. */
629 RTTHREADNATIVESTATE_INVALID = 0,
630 /** Unable to determine the thread state. */
631 RTTHREADNATIVESTATE_UNKNOWN,
632 /** The thread is running. */
633 RTTHREADNATIVESTATE_RUNNING,
634 /** The thread is blocked. */
635 RTTHREADNATIVESTATE_BLOCKED,
636 /** The thread is suspended / stopped. */
637 RTTHREADNATIVESTATE_SUSPENDED,
638 /** The thread has terminated. */
639 RTTHREADNATIVESTATE_TERMINATED,
640 /** Make sure it's a 32-bit type. */
641 RTTHREADNATIVESTATE_32BIT_HACK = 0x7fffffff
642} RTTHREADNATIVESTATE;
643
644
645/**
646 * Get the native state of a thread.
647 *
648 * @returns Native state.
649 * @param hThread The thread handle.
650 *
651 * @remarks Not yet implemented on all systems, so have a backup plan for
652 * RTTHREADNATIVESTATE_UNKNOWN.
653 */
654RTDECL(RTTHREADNATIVESTATE) RTThreadGetNativeState(RTTHREAD hThread);
655
656
657
658/** @name Thread Local Storage
659 * @{
660 */
661/**
662 * Thread termination callback for destroying a non-zero TLS entry.
663 *
664 * @remarks It is not permittable to use any RTTls APIs at this time. Doing so
665 * may lead to endless loops, crashes, and other bad stuff.
666 *
667 * @param pvValue The current value.
668 */
669typedef DECLCALLBACK(void) FNRTTLSDTOR(void *pvValue);
670/** Pointer to a FNRTTLSDTOR. */
671typedef FNRTTLSDTOR *PFNRTTLSDTOR;
672
673/**
674 * Allocates a TLS entry (index).
675 *
676 * Example code:
677 * @code
678 RTTLS g_iTls = NIL_RTTLS;
679
680 ...
681
682 // once for the process, allocate the TLS index
683 if (g_iTls == NIL_RTTLS)
684 g_iTls = RTTlsAlloc();
685
686 // set the thread-local value.
687 RTTlsSet(g_iTls, pMyData);
688
689 ...
690
691 // get the thread-local value
692 PMYDATA pMyData = (PMYDATA)RTTlsGet(g_iTls);
693
694 @endcode
695 *
696 * @returns the index of the allocated TLS entry.
697 * @returns NIL_RTTLS on failure.
698 */
699RTR3DECL(RTTLS) RTTlsAlloc(void);
700
701/**
702 * Variant of RTTlsAlloc that returns a status code.
703 *
704 * @returns IPRT status code.
705 * @retval VERR_NOT_SUPPORTED if pfnDestructor is non-NULL and the platform
706 * doesn't support this feature.
707 *
708 * @param piTls Where to store the index of the allocated TLS entry.
709 * This is set to NIL_RTTLS on failure.
710 * @param pfnDestructor Optional callback function for cleaning up on
711 * thread termination. WARNING! This feature may not
712 * be implemented everywhere.
713 */
714RTR3DECL(int) RTTlsAllocEx(PRTTLS piTls, PFNRTTLSDTOR pfnDestructor);
715
716/**
717 * Frees a TLS entry.
718 *
719 * @returns IPRT status code.
720 * @param iTls The index of the TLS entry.
721 */
722RTR3DECL(int) RTTlsFree(RTTLS iTls);
723
724/**
725 * Get the (thread-local) value stored in a TLS entry.
726 *
727 * @returns value in given TLS entry.
728 * @retval NULL if RTTlsSet() has not yet been called on this thread, or if the
729 * TLS index is invalid.
730 *
731 * @param iTls The index of the TLS entry.
732 */
733RTR3DECL(void *) RTTlsGet(RTTLS iTls);
734
735/**
736 * Get the value stored in a TLS entry.
737 *
738 * @returns IPRT status code.
739 * @param iTls The index of the TLS entry.
740 * @param ppvValue Where to store the value. The value will be NULL if
741 * RTTlsSet has not yet been called on this thread.
742 */
743RTR3DECL(int) RTTlsGetEx(RTTLS iTls, void **ppvValue);
744
745/**
746 * Set the value stored in an allocated TLS entry.
747 *
748 * @returns IPRT status.
749 * @param iTls The index of the TLS entry.
750 * @param pvValue The value to store.
751 *
752 * @remarks Note that NULL is considered a special value.
753 */
754RTR3DECL(int) RTTlsSet(RTTLS iTls, void *pvValue);
755
756/** @} */
757
758# endif /* IN_RING3 */
759# endif /* !IN_RC */
760
761/** @} */
762
763RT_C_DECLS_END
764
765#endif
766
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