VirtualBox

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

Last change on this file since 103224 was 99921, checked in by vboxsync, 17 months ago

iprt/thread.h: scm fixes

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 33.2 KB
Line 
1/** @file
2 * IPRT - Threads.
3 */
4
5/*
6 * Copyright (C) 2006-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_thread_h
37#define IPRT_INCLUDED_thread_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/cdefs.h>
43#include <iprt/types.h>
44#include <iprt/stdarg.h>
45
46
47RT_C_DECLS_BEGIN
48
49/** @defgroup grp_rt_thread RTThread - Thread Management
50 * @ingroup grp_rt
51 * @{
52 */
53
54/**
55 * The thread state.
56 */
57typedef enum RTTHREADSTATE
58{
59 /** The usual invalid 0 value. */
60 RTTHREADSTATE_INVALID = 0,
61 /** The thread is being initialized. */
62 RTTHREADSTATE_INITIALIZING,
63 /** The thread has terminated */
64 RTTHREADSTATE_TERMINATED,
65 /** Probably running. */
66 RTTHREADSTATE_RUNNING,
67
68 /** Waiting on a critical section. */
69 RTTHREADSTATE_CRITSECT,
70 /** Waiting on a event semaphore. */
71 RTTHREADSTATE_EVENT,
72 /** Waiting on a event multiple wakeup semaphore. */
73 RTTHREADSTATE_EVENT_MULTI,
74 /** Waiting on a fast mutex. */
75 RTTHREADSTATE_FAST_MUTEX,
76 /** Waiting on a mutex. */
77 RTTHREADSTATE_MUTEX,
78 /** Waiting on a read write semaphore, read (shared) access. */
79 RTTHREADSTATE_RW_READ,
80 /** Waiting on a read write semaphore, write (exclusive) access. */
81 RTTHREADSTATE_RW_WRITE,
82 /** The thread is sleeping. */
83 RTTHREADSTATE_SLEEP,
84 /** Waiting on a spin mutex. */
85 RTTHREADSTATE_SPIN_MUTEX,
86 /** End of the thread states. */
87 RTTHREADSTATE_END,
88
89 /** The usual 32-bit size hack. */
90 RTTHREADSTATE_32BIT_HACK = 0x7fffffff
91} RTTHREADSTATE;
92
93/** Checks if a thread state indicates that the thread is sleeping. */
94#define RTTHREAD_IS_SLEEPING(enmState) ((enmState) >= RTTHREADSTATE_CRITSECT)
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 produced 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#if !defined(IN_RC) || defined(DOXYGEN_RUNNING)
180
181/**
182 * Checks if the IPRT thread component has been initialized.
183 *
184 * This is used to avoid calling into RTThread before the runtime has been
185 * initialized.
186 *
187 * @returns @c true if it's initialized, @c false if not.
188 */
189RTDECL(bool) RTThreadIsInitialized(void);
190
191/**
192 * Get the thread handle of the current thread.
193 *
194 * @returns Thread handle.
195 */
196RTDECL(RTTHREAD) RTThreadSelf(void);
197
198/**
199 * Get the native thread handle of the current thread.
200 *
201 * @returns Native thread handle.
202 */
203RTDECL(RTNATIVETHREAD) RTThreadNativeSelf(void);
204
205/**
206 * Millisecond granular sleep function.
207 *
208 * @returns VINF_SUCCESS on success.
209 * @returns VERR_INTERRUPTED if a signal or other asynchronous stuff happened
210 * which interrupt the peaceful sleep.
211 * @param cMillies Number of milliseconds to sleep.
212 * 0 milliseconds means yielding the timeslice - deprecated!
213 * @remark See RTThreadNanoSleep() for sleeping for smaller periods of time.
214 */
215RTDECL(int) RTThreadSleep(RTMSINTERVAL cMillies);
216
217/**
218 * Millisecond granular sleep function, no logger calls.
219 *
220 * Same as RTThreadSleep, except it will never call into the IPRT logger. It
221 * can therefore safely be used in places where the logger is off limits, like
222 * at termination or init time. The electric fence heap is one consumer of
223 * this API.
224 *
225 * @returns VINF_SUCCESS on success.
226 * @returns VERR_INTERRUPTED if a signal or other asynchronous stuff happened
227 * which interrupt the peaceful sleep.
228 * @param cMillies Number of milliseconds to sleep.
229 * 0 milliseconds means yielding the timeslice - deprecated!
230 */
231RTDECL(int) RTThreadSleepNoLog(RTMSINTERVAL cMillies);
232
233/**
234 * Yields the CPU.
235 *
236 * @returns true if we yielded.
237 * @returns false if it's probable that we didn't yield.
238 */
239RTDECL(bool) RTThreadYield(void);
240
241
242
243/**
244 * Thread function.
245 *
246 * @returns 0 on success.
247 * @param ThreadSelf Thread handle to this thread.
248 * @param pvUser User argument.
249 */
250typedef DECLCALLBACKTYPE(int, FNRTTHREAD,(RTTHREAD ThreadSelf, void *pvUser));
251/** Pointer to a FNRTTHREAD(). */
252typedef FNRTTHREAD *PFNRTTHREAD;
253
254/**
255 * Thread creation flags.
256 */
257typedef enum RTTHREADFLAGS
258{
259 /** This flag is used to keep the thread structure around so it can
260 * be waited on after termination. @sa RTThreadWait and
261 * RTThreadWaitNoResume. Not required for RTThreadUserWait and friends!
262 */
263 RTTHREADFLAGS_WAITABLE = RT_BIT(0),
264 /** The bit number corresponding to the RTTHREADFLAGS_WAITABLE mask. */
265 RTTHREADFLAGS_WAITABLE_BIT = 0,
266
267 /** Call CoInitializeEx w/ COINIT_MULTITHREADED, COINIT_DISABLE_OLE1DDE and
268 * COINIT_SPEED_OVER_MEMORY. Ignored on non-windows platforms. */
269 RTTHREADFLAGS_COM_MTA = RT_BIT(1),
270 /** Call CoInitializeEx w/ COINIT_APARTMENTTHREADED and
271 * COINIT_SPEED_OVER_MEMORY. Ignored on non-windows platforms. */
272 RTTHREADFLAGS_COM_STA = RT_BIT(2),
273
274 /** Mask all signals that we can mask. Ignored on most non-posix platforms.
275 * @note RTThreadPoke() will not necessarily work for a thread create with
276 * this flag. */
277 RTTHREADFLAGS_NO_SIGNALS = RT_BIT(3),
278
279 /** Mask of valid flags, use for validation. */
280 RTTHREADFLAGS_MASK = UINT32_C(0xf)
281} RTTHREADFLAGS;
282
283/** Max thread name length (including zero terminator). */
284#define RTTHREAD_NAME_LEN 16
285
286/**
287 * Create a new thread.
288 *
289 * @returns iprt status code.
290 * @param pThread Where to store the thread handle to the new thread. (optional)
291 * @param pfnThread The thread function.
292 * @param pvUser User argument.
293 * @param cbStack The size of the stack for the new thread.
294 * Use 0 for the default stack size.
295 * @param enmType The thread type. Used for deciding scheduling attributes
296 * of the thread.
297 * @param fFlags Flags of the RTTHREADFLAGS type (ORed together).
298 * @param pszName Thread name.
299 *
300 * @remark When called in Ring-0, this API will create a new kernel thread and not a thread in
301 * the context of the calling process.
302 */
303RTDECL(int) RTThreadCreate(PRTTHREAD pThread, PFNRTTHREAD pfnThread, void *pvUser, size_t cbStack,
304 RTTHREADTYPE enmType, unsigned fFlags, const char *pszName);
305#ifndef RT_OS_LINUX /* XXX crashes genksyms at least on 32-bit Linux hosts */
306/** Pointer to a RTThreadCreate function. */
307typedef DECLCALLBACKPTR(int, PFNRTTHREADCREATE,(PRTTHREAD pThread, PFNRTTHREAD pfnThread, void *pvUser, size_t cbStack,
308 RTTHREADTYPE enmType, unsigned fFlags, const char *pszName));
309#endif
310
311
312/**
313 * Create a new thread.
314 *
315 * Same as RTThreadCreate except the name is given in the RTStrPrintfV form.
316 *
317 * @returns iprt status code.
318 * @param pThread See RTThreadCreate.
319 * @param pfnThread See RTThreadCreate.
320 * @param pvUser See RTThreadCreate.
321 * @param cbStack See RTThreadCreate.
322 * @param enmType See RTThreadCreate.
323 * @param fFlags See RTThreadCreate.
324 * @param pszNameFmt Thread name format.
325 * @param va Format arguments.
326 */
327RTDECL(int) RTThreadCreateV(PRTTHREAD pThread, PFNRTTHREAD pfnThread, void *pvUser, size_t cbStack,
328 RTTHREADTYPE enmType, uint32_t fFlags, const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(7, 0);
329
330/**
331 * Create a new thread.
332 *
333 * Same as RTThreadCreate except the name is given in the RTStrPrintf form.
334 *
335 * @returns iprt status code.
336 * @param pThread See RTThreadCreate.
337 * @param pfnThread See RTThreadCreate.
338 * @param pvUser See RTThreadCreate.
339 * @param cbStack See RTThreadCreate.
340 * @param enmType See RTThreadCreate.
341 * @param fFlags See RTThreadCreate.
342 * @param pszNameFmt Thread name format.
343 * @param ... Format arguments.
344 */
345RTDECL(int) RTThreadCreateF(PRTTHREAD pThread, PFNRTTHREAD pfnThread, void *pvUser, size_t cbStack,
346 RTTHREADTYPE enmType, uint32_t fFlags, const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(7, 8);
347
348/**
349 * Gets the native thread id of a IPRT thread.
350 *
351 * @returns The native thread id.
352 * @param Thread The IPRT thread.
353 */
354RTDECL(RTNATIVETHREAD) RTThreadGetNative(RTTHREAD Thread);
355
356/**
357 * Gets the native thread handle for a IPRT thread.
358 *
359 * @returns The thread handle. INVALID_HANDLE_VALUE on failure.
360 * @param hThread The IPRT thread handle.
361 *
362 * @note Windows only.
363 * @note Only valid after parent returns from the thread creation call.
364 */
365RTDECL(uintptr_t) RTThreadGetNativeHandle(RTTHREAD hThread);
366
367/**
368 * Gets the IPRT thread of a native thread.
369 *
370 * @returns The IPRT thread handle
371 * @returns NIL_RTTHREAD if not a thread known to IPRT.
372 * @param NativeThread The native thread handle/id.
373 */
374RTDECL(RTTHREAD) RTThreadFromNative(RTNATIVETHREAD NativeThread);
375
376/**
377 * Changes the type of the specified thread.
378 *
379 * @returns iprt status code.
380 * @param Thread The thread which type should be changed.
381 * @param enmType The new thread type.
382 * @remark In Ring-0 it only works if Thread == RTThreadSelf().
383 */
384RTDECL(int) RTThreadSetType(RTTHREAD Thread, RTTHREADTYPE enmType);
385
386/**
387 * Wait for the thread to terminate, resume on interruption.
388 *
389 * @returns iprt status code.
390 * Will not return VERR_INTERRUPTED.
391 * @param Thread The thread to wait for.
392 * @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for
393 * an indefinite wait.
394 * @param prc Where to store the return code of the thread. Optional.
395 */
396RTDECL(int) RTThreadWait(RTTHREAD Thread, RTMSINTERVAL cMillies, int *prc);
397
398/**
399 * Wait for the thread to terminate, return on interruption.
400 *
401 * @returns iprt status code.
402 * @param Thread The thread to wait for.
403 * @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for
404 * an indefinite wait.
405 * @param prc Where to store the return code of the thread. Optional.
406 */
407RTDECL(int) RTThreadWaitNoResume(RTTHREAD Thread, RTMSINTERVAL cMillies, int *prc);
408
409/**
410 * Gets the name of the current thread thread.
411 *
412 * @returns Pointer to readonly name string.
413 * @returns NULL on failure.
414 */
415RTDECL(const char *) RTThreadSelfName(void);
416
417/**
418 * Gets the name of a thread.
419 *
420 * @returns Pointer to readonly name string.
421 * @returns NULL on failure.
422 * @param Thread Thread handle of the thread to query the name of.
423 */
424RTDECL(const char *) RTThreadGetName(RTTHREAD Thread);
425
426/**
427 * Gets the type of the specified thread.
428 *
429 * @returns The thread type.
430 * @returns RTTHREADTYPE_INVALID if the thread handle is invalid.
431 * @param Thread The thread in question.
432 */
433RTDECL(RTTHREADTYPE) RTThreadGetType(RTTHREAD Thread);
434
435/**
436 * Sets the name of a thread.
437 *
438 * @returns iprt status code.
439 * @param Thread Thread handle of the thread to query the name of.
440 * @param pszName The thread name.
441 */
442RTDECL(int) RTThreadSetName(RTTHREAD Thread, const char *pszName);
443
444/**
445 * Checks if the specified thread is the main thread.
446 *
447 * @returns true if it is, false if it isn't.
448 *
449 * @param hThread The thread handle.
450 */
451RTDECL(bool) RTThreadIsMain(RTTHREAD hThread);
452
453/**
454 * Checks if the calling thread is known to IPRT.
455 *
456 * @returns @c true if it is, @c false if it isn't.
457 */
458RTDECL(bool) RTThreadIsSelfKnown(void);
459
460/**
461 * Checks if the calling thread is know to IPRT and is alive.
462 *
463 * @returns @c true if it is, @c false if it isn't.
464 */
465RTDECL(bool) RTThreadIsSelfAlive(void);
466
467#ifdef IN_RING0
468/**
469 * Checks whether the specified thread is terminating.
470 *
471 * @retval VINF_SUCCESS if not terminating.
472 * @retval VINF_THREAD_IS_TERMINATING if terminating.
473 * @retval VERR_INVALID_HANDLE if hThread is not NIL_RTTHREAD.
474 * @retval VERR_NOT_SUPPORTED if the OS doesn't provide ways to check.
475 *
476 * @param hThread The thread to query about, NIL_RTTHREAD is an alias for
477 * the calling thread. Must be NIL_RTTHREAD for now.
478 *
479 * @note Not suppored on all OSes, so check for VERR_NOT_SUPPORTED.
480 */
481RTDECL(int) RTThreadQueryTerminationStatus(RTTHREAD hThread);
482#endif
483
484/**
485 * Signal the user event.
486 *
487 * @returns iprt status code.
488 */
489RTDECL(int) RTThreadUserSignal(RTTHREAD Thread);
490
491/**
492 * Wait for the user event.
493 *
494 * @returns iprt status code.
495 * @param Thread The thread to wait for.
496 * @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for
497 * an indefinite wait.
498 */
499RTDECL(int) RTThreadUserWait(RTTHREAD Thread, RTMSINTERVAL cMillies);
500
501/**
502 * Wait for the user event, return on interruption.
503 *
504 * @returns iprt status code.
505 * @param Thread The thread to wait for.
506 * @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for
507 * an indefinite wait.
508 */
509RTDECL(int) RTThreadUserWaitNoResume(RTTHREAD Thread, RTMSINTERVAL cMillies);
510
511/**
512 * Reset the user event.
513 *
514 * @returns iprt status code.
515 * @param Thread The thread to reset.
516 */
517RTDECL(int) RTThreadUserReset(RTTHREAD Thread);
518
519/**
520 * Pokes the thread.
521 *
522 * This will wake up or/and signal the thread, attempting to interrupt whatever
523 * it's currently doing.
524 *
525 * The posixy version of this will send a signal to the thread, quite likely
526 * waking it up from normal sleeps, waits, and I/O. When IPRT is in
527 * non-obtrusive mode, the posixy version will definitely return
528 * VERR_NOT_IMPLEMENTED, and it may also do so if no usable signal was found.
529 *
530 * On Windows the thread will be alerted, waking it up from most sleeps and
531 * waits, but not probably very little in the I/O area (needs testing). On NT
532 * 3.50 and 3.1 VERR_NOT_IMPLEMENTED will be returned.
533 *
534 * @returns IPRT status code.
535 *
536 * @param hThread The thread to poke. This must not be the
537 * calling thread.
538 *
539 * @note This is *NOT* implemented on all platforms and may cause unresolved
540 * symbols during linking or VERR_NOT_IMPLEMENTED at runtime.
541 *
542 */
543RTDECL(int) RTThreadPoke(RTTHREAD hThread);
544
545/**
546 * Controls the masking of the signal used by RTThreadPoke on posix systems.
547 *
548 * This function is not available on non-posix systems.
549 *
550 * @returns IPRT status code.
551 *
552 * @param hThread The current thread.
553 * @param fEnable Whether to enable poking (unblock) or to disable it
554 * (block the signal).
555 */
556RTDECL(int) RTThreadControlPokeSignal(RTTHREAD hThread, bool fEnable);
557
558
559# ifdef IN_RING0
560
561/**
562 * Check if preemption is currently enabled or not for the current thread.
563 *
564 * @note This may return true even on systems where preemption isn't
565 * possible. In that case, it means no call to RTThreadPreemptDisable
566 * has been made and interrupts are still enabled.
567 *
568 * @returns true if preemption is enabled, false if preemetion is disabled.
569 * @param hThread Must be NIL_RTTHREAD for now.
570 */
571RTDECL(bool) RTThreadPreemptIsEnabled(RTTHREAD hThread);
572
573/**
574 * Check if preemption is pending for the current thread.
575 *
576 * This function should be called regularly when executing larger portions of
577 * code with preemption disabled.
578 *
579 * @returns true if pending, false if not.
580 * @param hThread Must be NIL_RTTHREAD for now.
581 *
582 * @note If called with interrupts disabled, the NT kernel may temporarily
583 * re-enable them while checking.
584 */
585RTDECL(bool) RTThreadPreemptIsPending(RTTHREAD hThread);
586
587/**
588 * Is RTThreadPreemptIsPending reliable?
589 *
590 * @returns true if reliable, false if not.
591 */
592RTDECL(bool) RTThreadPreemptIsPendingTrusty(void);
593
594/**
595 * Is preemption possible on this system.
596 *
597 * @returns true if possible, false if not.
598 */
599RTDECL(bool) RTThreadPreemptIsPossible(void);
600
601/**
602 * Preemption state saved by RTThreadPreemptDisable and used by
603 * RTThreadPreemptRestore to restore the previous state.
604 */
605typedef struct RTTHREADPREEMPTSTATE
606{
607 /** In debug builds this will be used to check for cpu migration. */
608 RTCPUID idCpu;
609# ifdef RT_OS_WINDOWS
610 /** The old IRQL. Don't touch! */
611 unsigned char uchOldIrql;
612 /** Reserved, MBZ. */
613 uint8_t bReserved1;
614 /** Reserved, MBZ. */
615 uint8_t bReserved2;
616 /** Reserved, MBZ. */
617 uint8_t bReserved3;
618# define RTTHREADPREEMPTSTATE_INITIALIZER { NIL_RTCPUID, 255, 0, 0, 0 }
619# elif defined(RT_OS_HAIKU)
620 /** The cpu_state. Don't touch! */
621 uint32_t uOldCpuState;
622# define RTTHREADPREEMPTSTATE_INITIALIZER { NIL_RTCPUID, 0 }
623# elif defined(RT_OS_SOLARIS)
624 /** The Old PIL. Don't touch! */
625 uint32_t uOldPil;
626# define RTTHREADPREEMPTSTATE_INITIALIZER { NIL_RTCPUID, UINT32_MAX }
627# else
628 /** Reserved, MBZ. */
629 uint32_t u32Reserved;
630# define RTTHREADPREEMPTSTATE_INITIALIZER { NIL_RTCPUID, 0 }
631# endif
632} RTTHREADPREEMPTSTATE;
633/** Pointer to a preemption state. */
634typedef RTTHREADPREEMPTSTATE *PRTTHREADPREEMPTSTATE;
635
636/**
637 * Disable preemption.
638 *
639 * A call to this function must be matched by exactly one call to
640 * RTThreadPreemptRestore().
641 *
642 * @param pState Where to store the preemption state.
643 */
644RTDECL(void) RTThreadPreemptDisable(PRTTHREADPREEMPTSTATE pState);
645
646/**
647 * Restores the preemption state, undoing a previous call to
648 * RTThreadPreemptDisable.
649 *
650 * A call to this function must be matching a previous call to
651 * RTThreadPreemptDisable.
652 *
653 * @param pState The state return by RTThreadPreemptDisable.
654 */
655RTDECL(void) RTThreadPreemptRestore(PRTTHREADPREEMPTSTATE pState);
656
657/**
658 * Check if the thread is executing in interrupt context.
659 *
660 * @returns true if in interrupt context, false if not.
661 * @param hThread Must be NIL_RTTHREAD for now.
662 */
663RTDECL(bool) RTThreadIsInInterrupt(RTTHREAD hThread);
664
665
666/**
667 * Thread context swithcing events.
668 */
669typedef enum RTTHREADCTXEVENT
670{
671 /** This thread is being scheduled out on the current CPU (includes preemption,
672 * waiting, sleep and whatever else may trigger scheduling). */
673 RTTHREADCTXEVENT_OUT = 0,
674 /** This thread is being scheduled in on the current CPU and will resume
675 * execution. */
676 RTTHREADCTXEVENT_IN,
677 /** The usual 32-bit size hack. */
678 RTTHREADCTXEVENT_32BIT_HACK = 0x7fffffff
679} RTTHREADCTXEVENT;
680
681/**
682 * Thread context switching hook callback.
683 *
684 * This hook function is called when a thread is scheduled and preempted. Check
685 * @a enmEvent to see which it is. Since the function is being called from
686 * hooks inside the scheduler, it is limited what you can do from this function.
687 * Do NOT acquire locks, sleep or yield the thread for instance. IRQ safe
688 * spinlocks are fine though.
689 *
690 * @param enmEvent The thread-context event. Please quitely ignore unknown
691 * events, we may add more (thread exit, ++) later.
692 * @param pvUser User argument.
693 */
694typedef DECLCALLBACKTYPE(void, FNRTTHREADCTXHOOK,(RTTHREADCTXEVENT enmEvent, void *pvUser));
695/** Pointer to a context switching hook. */
696typedef FNRTTHREADCTXHOOK *PFNRTTHREADCTXHOOK;
697
698/**
699 * Initializes a thread context switching hook for the current thread.
700 *
701 * The hook is created as disabled, use RTThreadCtxHookEnable to enable it.
702 *
703 * @returns IPRT status code.
704 * @param phCtxHook Where to store the hook handle.
705 * @param fFlags Reserved for future extensions, must be zero.
706 * @param pfnCallback Pointer to a the hook function (callback) that
707 * should be called for all context switching events
708 * involving the current thread.
709 * @param pvUser User argument that will be passed to @a pfnCallback.
710 * @remarks Preemption must be enabled.
711 */
712RTDECL(int) RTThreadCtxHookCreate(PRTTHREADCTXHOOK phCtxHook, uint32_t fFlags, PFNRTTHREADCTXHOOK pfnCallback, void *pvUser);
713
714/**
715 * Destroys a thread context switching hook.
716 *
717 * Caller must make sure the hook is disabled before the final reference is
718 * released. Recommended to call this on the owning thread, otherwise the
719 * memory backing it may on some systems only be released when the thread
720 * terminates.
721 *
722 * @returns IPRT status code.
723 *
724 * @param hCtxHook The context hook handle. NIL_RTTHREADCTXHOOK is
725 * ignored and the function will return VINF_SUCCESS.
726 * @remarks Preemption must be enabled.
727 * @remarks Do not call from FNRTTHREADCTXHOOK.
728 */
729RTDECL(int) RTThreadCtxHookDestroy(RTTHREADCTXHOOK hCtxHook);
730
731/**
732 * Enables the context switching hooks for the current thread.
733 *
734 * @returns IPRT status code.
735 * @param hCtxHook The context hook handle.
736 * @remarks Should be called with preemption disabled.
737 */
738RTDECL(int) RTThreadCtxHookEnable(RTTHREADCTXHOOK hCtxHook);
739
740/**
741 * Disables the thread context switching hook for the current thread.
742 *
743 * Will not assert or fail if called twice or with a NIL handle.
744 *
745 * @returns IPRT status code.
746 * @param hCtxHook The context hook handle. NIL_RTTHREADCTXHOOK is
747 * ignored and the function wil return VINF_SUCCESS.
748 * @remarks Should be called with preemption disabled.
749 * @remarks Do not call from FNRTTHREADCTXHOOK.
750 */
751RTDECL(int) RTThreadCtxHookDisable(RTTHREADCTXHOOK hCtxHook);
752
753/**
754 * Is the thread context switching hook enabled?
755 *
756 * @returns true if registered, false if not supported or not registered.
757 * @param hCtxHook The context hook handle. NIL_RTTHREADCTXHOOK is
758 * ignored and the function will return false.
759 *
760 * @remarks Can be called from any thread, though is naturally subject to races
761 * when not called from the thread associated with the hook.
762 */
763RTDECL(bool) RTThreadCtxHookIsEnabled(RTTHREADCTXHOOK hCtxHook);
764
765# endif /* IN_RING0 */
766
767
768# ifdef IN_RING3
769
770/**
771 * Adopts a non-IPRT thread.
772 *
773 * @returns IPRT status code.
774 * @param enmType The thread type.
775 * @param fFlags The thread flags. RTTHREADFLAGS_WAITABLE is not currently allowed.
776 * @param pszName The thread name. Optional
777 * @param pThread Where to store the thread handle. Optional.
778 */
779RTDECL(int) RTThreadAdopt(RTTHREADTYPE enmType, unsigned fFlags, const char *pszName, PRTTHREAD pThread);
780
781/**
782 * Get the thread handle of the current thread, automatically adopting alien
783 * threads.
784 *
785 * @returns Thread handle.
786 */
787RTDECL(RTTHREAD) RTThreadSelfAutoAdopt(void);
788
789/**
790 * Gets the affinity mask of the current thread.
791 *
792 * @returns IPRT status code.
793 * @param pCpuSet Where to return the CPU affienty set of the calling
794 * thread.
795 */
796RTR3DECL(int) RTThreadGetAffinity(PRTCPUSET pCpuSet);
797
798/**
799 * Sets the affinity mask of the current thread.
800 *
801 * @returns iprt status code.
802 * @param pCpuSet The set of CPUs this thread can run on. NULL means
803 * all CPUs.
804 */
805RTR3DECL(int) RTThreadSetAffinity(PCRTCPUSET pCpuSet);
806
807/**
808 * Binds the thread to one specific CPU.
809 *
810 * @returns iprt status code.
811 * @param idCpu The ID of the CPU to bind this thread to. Use
812 * NIL_RTCPUID to unbind it.
813 */
814RTR3DECL(int) RTThreadSetAffinityToCpu(RTCPUID idCpu);
815
816/**
817 * Unblocks a thread.
818 *
819 * This function is paired with RTThreadBlocking and RTThreadBlockingDebug.
820 *
821 * @param hThread The current thread.
822 * @param enmCurState The current state, used to check for nested blocking.
823 * The new state will be running.
824 */
825RTDECL(void) RTThreadUnblocked(RTTHREAD hThread, RTTHREADSTATE enmCurState);
826
827/**
828 * Change the thread state to blocking.
829 *
830 * @param hThread The current thread.
831 * @param enmState The sleep state.
832 * @param fReallySleeping Really going to sleep now. Use false before calls
833 * to other IPRT synchronization methods.
834 */
835RTDECL(void) RTThreadBlocking(RTTHREAD hThread, RTTHREADSTATE enmState, bool fReallySleeping);
836
837/**
838 * Get the current thread state.
839 *
840 * A thread that is reported as sleeping may actually still be running inside
841 * the lock validator or/and in the code of some other IPRT synchronization
842 * primitive. Use RTThreadGetReallySleeping
843 *
844 * @returns The thread state.
845 * @param hThread The thread.
846 */
847RTDECL(RTTHREADSTATE) RTThreadGetState(RTTHREAD hThread);
848
849/**
850 * Checks if the thread is really sleeping or not.
851 *
852 * @returns RTTHREADSTATE_RUNNING if not really sleeping, otherwise the state it
853 * is sleeping in.
854 * @param hThread The thread.
855 */
856RTDECL(RTTHREADSTATE) RTThreadGetReallySleeping(RTTHREAD hThread);
857
858/**
859 * Translate a thread state into a string.
860 *
861 * @returns Pointer to a read-only string containing the state name.
862 * @param enmState The state.
863 */
864RTDECL(const char *) RTThreadStateName(RTTHREADSTATE enmState);
865
866/**
867 * Native thread states returned by RTThreadNativeState.
868 */
869typedef enum RTTHREADNATIVESTATE
870{
871 /** Invalid thread handle. */
872 RTTHREADNATIVESTATE_INVALID = 0,
873 /** Unable to determine the thread state. */
874 RTTHREADNATIVESTATE_UNKNOWN,
875 /** The thread is running. */
876 RTTHREADNATIVESTATE_RUNNING,
877 /** The thread is blocked. */
878 RTTHREADNATIVESTATE_BLOCKED,
879 /** The thread is suspended / stopped. */
880 RTTHREADNATIVESTATE_SUSPENDED,
881 /** The thread has terminated. */
882 RTTHREADNATIVESTATE_TERMINATED,
883 /** Make sure it's a 32-bit type. */
884 RTTHREADNATIVESTATE_32BIT_HACK = 0x7fffffff
885} RTTHREADNATIVESTATE;
886
887/**
888 * Get the native state of a thread.
889 *
890 * @returns Native state.
891 * @param hThread The thread handle.
892 *
893 * @remarks Not yet implemented on all systems, so have a backup plan for
894 * RTTHREADNATIVESTATE_UNKNOWN.
895 */
896RTDECL(RTTHREADNATIVESTATE) RTThreadGetNativeState(RTTHREAD hThread);
897
898/**
899 * Get the execution times of the calling thread.
900 *
901 * @returns IPRT status code.
902 * @retval VERR_NOT_IMPLEMENTED if not implemented/supported.
903 *
904 * @param[out] pcMsKernelTime Kernel execution time in ms (out).
905 * @param[out] pcMsUserTime User execution time in ms (out).
906 *
907 * @remarks Linux and FreeBSD is currently reporting both kernel and user time
908 * together via @a *pcMsUserTime and @a *pcMsKernelTime will always be
909 * set to zero.
910 */
911RTR3DECL(int) RTThreadGetExecutionTimeMilli(uint64_t *pcMsKernelTime, uint64_t *pcMsUserTime);
912
913
914/** @name Thread Local Storage
915 * @{
916 */
917/**
918 * Thread termination callback for destroying a non-zero TLS entry.
919 *
920 * @remarks It is not permitable to use any RTTls APIs at this time. Doing so
921 * may lead to endless loops, crashes, and other bad stuff.
922 *
923 * @param pvValue The current value.
924 */
925typedef DECLCALLBACKTYPE(void, FNRTTLSDTOR,(void *pvValue));
926/** Pointer to a FNRTTLSDTOR. */
927typedef FNRTTLSDTOR *PFNRTTLSDTOR;
928
929/**
930 * Allocates a TLS entry (index).
931 *
932 * Example code:
933 * @code
934 RTTLS g_iTls = NIL_RTTLS;
935
936 ...
937
938 // once for the process, allocate the TLS index
939 if (g_iTls == NIL_RTTLS)
940 g_iTls = RTTlsAlloc();
941
942 // set the thread-local value.
943 RTTlsSet(g_iTls, pMyData);
944
945 ...
946
947 // get the thread-local value
948 PMYDATA pMyData = (PMYDATA)RTTlsGet(g_iTls);
949
950 @endcode
951 *
952 * @returns the index of the allocated TLS entry.
953 * @returns NIL_RTTLS on failure.
954 */
955RTR3DECL(RTTLS) RTTlsAlloc(void);
956
957/**
958 * Variant of RTTlsAlloc that returns a status code.
959 *
960 * @returns IPRT status code.
961 * @retval VERR_NOT_SUPPORTED if pfnDestructor is non-NULL and the platform
962 * doesn't support this feature.
963 *
964 * @param piTls Where to store the index of the allocated TLS entry.
965 * This is set to NIL_RTTLS on failure.
966 * @param pfnDestructor Optional callback function for cleaning up on
967 * thread termination.
968 * @note In static builds on windows, the destructor will only be invoked for
969 * IPRT threads.
970 * @note There are probably OS specific restrictions on what operations you
971 * are allowed to perform from a TLS destructor, so keep it simple.
972 */
973RTR3DECL(int) RTTlsAllocEx(PRTTLS piTls, PFNRTTLSDTOR pfnDestructor);
974
975/**
976 * Frees a TLS entry.
977 *
978 * @returns IPRT status code.
979 * @param iTls The index of the TLS entry.
980 */
981RTR3DECL(int) RTTlsFree(RTTLS iTls);
982
983/**
984 * Get the (thread-local) value stored in a TLS entry.
985 *
986 * @returns value in given TLS entry.
987 * @retval NULL if RTTlsSet() has not yet been called on this thread, or if the
988 * TLS index is invalid.
989 *
990 * @param iTls The index of the TLS entry.
991 */
992RTR3DECL(void *) RTTlsGet(RTTLS iTls);
993
994/**
995 * Get the value stored in a TLS entry.
996 *
997 * @returns IPRT status code.
998 * @param iTls The index of the TLS entry.
999 * @param ppvValue Where to store the value. The value will be NULL if
1000 * RTTlsSet has not yet been called on this thread.
1001 */
1002RTR3DECL(int) RTTlsGetEx(RTTLS iTls, void **ppvValue);
1003
1004/**
1005 * Set the value stored in an allocated TLS entry.
1006 *
1007 * @returns IPRT status.
1008 * @param iTls The index of the TLS entry.
1009 * @param pvValue The value to store.
1010 *
1011 * @remarks Note that NULL is considered a special value.
1012 */
1013RTR3DECL(int) RTTlsSet(RTTLS iTls, void *pvValue);
1014
1015/** @} */
1016
1017# endif /* IN_RING3 */
1018#endif /* !IN_RC || defined(DOXYGEN_RUNNING) */
1019
1020/** @} */
1021
1022RT_C_DECLS_END
1023
1024#endif /* !IPRT_INCLUDED_thread_h */
1025
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