thread.h revision 7e960d3a0a8a3a84d7aba2cca45d72b1c31cc97b
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync/** @file
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * IPRT - Threads.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync */
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync
1c898140fdfb6f3d207b0066f4fc8988226da7d4vboxsync/*
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * Copyright (C) 2006-2007 Sun Microsystems, Inc.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync *
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
1c898140fdfb6f3d207b0066f4fc8988226da7d4vboxsync * available from http://www.virtualbox.org. This file is free software;
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * you can redistribute it and/or modify it under the terms of the GNU
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * General Public License (GPL) as published by the Free Software
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync *
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * The contents of this file may alternatively be used under the terms
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * of the Common Development and Distribution License Version 1.0
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * VirtualBox OSE distribution, in which case the provisions of the
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * CDDL are applicable instead of those of the GPL.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync *
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * You may elect to license modified versions of this file under the
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * terms and conditions of either the GPL or the CDDL or both.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync *
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * additional information or have any questions.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync */
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync#ifndef ___iprt_thread_h
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync#define ___iprt_thread_h
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync#include <iprt/cdefs.h>
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync#include <iprt/types.h>
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync#include <iprt/stdarg.h>
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync
1c898140fdfb6f3d207b0066f4fc8988226da7d4vboxsync#ifdef IN_RC
1c898140fdfb6f3d207b0066f4fc8988226da7d4vboxsync# error "There are no threading APIs available Guest Context!"
1c898140fdfb6f3d207b0066f4fc8988226da7d4vboxsync#endif
1c898140fdfb6f3d207b0066f4fc8988226da7d4vboxsync
1c898140fdfb6f3d207b0066f4fc8988226da7d4vboxsync
1c898140fdfb6f3d207b0066f4fc8988226da7d4vboxsync
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync__BEGIN_DECLS
5ff3fa0492332325f57e80636321619e2224027evboxsync
5ff3fa0492332325f57e80636321619e2224027evboxsync/** @defgroup grp_rt_thread RTThread - Thread Management
5ff3fa0492332325f57e80636321619e2224027evboxsync * @ingroup grp_rt
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * @{
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync */
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync/**
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * Get the thread handle of the current thread.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync *
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * @returns Thread handle.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync */
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsyncRTDECL(RTTHREAD) RTThreadSelf(void);
0ce6ae9d6efed5d54222a13bbdabce9e688e4447vboxsync
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync/**
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * Get the native thread handle of the current thread.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync *
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * @returns Native thread handle.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync */
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsyncRTDECL(RTNATIVETHREAD) RTThreadNativeSelf(void);
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync/**
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * Millisecond granular sleep function.
57b49c1557a310ee615bc0ee79dd2a2e92319a1bvboxsync *
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * @returns VINF_SUCCESS on success.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * @returns VERR_INTERRUPTED if a signal or other asynchronous stuff happend
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * which interrupt the peaceful sleep.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * @param cMillies Number of milliseconds to sleep.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * 0 milliseconds means yielding the timeslice - deprecated!
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * @remark See RTThreadNanoSleep() for sleeping for smaller periods of time.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync */
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsyncRTDECL(int) RTThreadSleep(unsigned cMillies);
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync/**
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * Yields the CPU.
df4af4b66b5f26c3c06ae1592ec2e67afd82dd0cvboxsync *
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * @returns true if we yielded.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * @returns false if it's probable that we didn't yield.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync */
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsyncRTDECL(bool) RTThreadYield(void);
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync
83c86878d483df62ca8db465c671995984838338vboxsync
30f7bd6bf198ae0489df375e5a17cb086acb30fbvboxsync
30f7bd6bf198ae0489df375e5a17cb086acb30fbvboxsync/**
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * Thread function.
30f7bd6bf198ae0489df375e5a17cb086acb30fbvboxsync *
30f7bd6bf198ae0489df375e5a17cb086acb30fbvboxsync * @returns 0 on success.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * @param ThreadSelf Thread handle to this thread.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * @param pvUser User argument.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync */
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsynctypedef DECLCALLBACK(int) FNRTTHREAD(RTTHREAD ThreadSelf, void *pvUser);
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync/** Pointer to a FNRTTHREAD(). */
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsynctypedef FNRTTHREAD *PFNRTTHREAD;
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync/**
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * Thread types.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * Besides identifying the purpose of the thread, the thread type is
5a6bbb9c0d896e804f267c6919f52158a420b998vboxsync * used to select the scheduling properties.
5a6bbb9c0d896e804f267c6919f52158a420b998vboxsync *
5a6bbb9c0d896e804f267c6919f52158a420b998vboxsync * The types in are placed in a rough order of ascending priority.
5ff3fa0492332325f57e80636321619e2224027evboxsync */
5ff3fa0492332325f57e80636321619e2224027evboxsynctypedef enum RTTHREADTYPE
5ff3fa0492332325f57e80636321619e2224027evboxsync{
5ff3fa0492332325f57e80636321619e2224027evboxsync /** Invalid type. */
5a6bbb9c0d896e804f267c6919f52158a420b998vboxsync RTTHREADTYPE_INVALID = 0,
5a6bbb9c0d896e804f267c6919f52158a420b998vboxsync /** Infrequent poller thread.
5a6bbb9c0d896e804f267c6919f52158a420b998vboxsync * This type of thread will sleep for the most of the time, and do
83c86878d483df62ca8db465c671995984838338vboxsync * infrequent polls on resources at 0.5 sec or higher intervals.
5a6bbb9c0d896e804f267c6919f52158a420b998vboxsync */
5a6bbb9c0d896e804f267c6919f52158a420b998vboxsync RTTHREADTYPE_INFREQUENT_POLLER,
5a6bbb9c0d896e804f267c6919f52158a420b998vboxsync /** Main heavy worker thread.
5a6bbb9c0d896e804f267c6919f52158a420b998vboxsync * Thread of this type is driving asynchronous tasks in the Main
5a6bbb9c0d896e804f267c6919f52158a420b998vboxsync * API which takes a long time and might involve a bit of CPU. Like
5a6bbb9c0d896e804f267c6919f52158a420b998vboxsync * for instance creating a fixed sized VDI.
5a6bbb9c0d896e804f267c6919f52158a420b998vboxsync */
5a6bbb9c0d896e804f267c6919f52158a420b998vboxsync RTTHREADTYPE_MAIN_HEAVY_WORKER,
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync /** The emulation thread type.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * While being a thread with very high workload it still is vital
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * that it gets scheduled frequently. When possible all other thread
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * types except DEFAULT and GUI should interrupt this one ASAP when
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * they become ready.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync */
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync RTTHREADTYPE_EMULATION,
0ce6ae9d6efed5d54222a13bbdabce9e688e4447vboxsync /** The default thread type.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * Since it doesn't say much about the purpose of the thread
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * nothing special is normally done to the scheduling. This type
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * should be avoided.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * The main thread is registered with default type during RTR3Init()
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * and that's what the default process priority is derived from.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync */
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync RTTHREADTYPE_DEFAULT,
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync /** The GUI thread type
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * The GUI normally have a low workload but is frequently scheduled
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * to handle events. When possible the scheduler should not leave
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * threads of this kind waiting for too long (~50ms).
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync */
57b49c1557a310ee615bc0ee79dd2a2e92319a1bvboxsync RTTHREADTYPE_GUI,
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync /** Main worker thread.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * Thread of this type is driving asynchronous tasks in the Main API.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * In most cases this means little work an a lot of waiting.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync */
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync RTTHREADTYPE_MAIN_WORKER,
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync /** VRDP I/O thread.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * These threads are I/O threads in the RDP server will hang around
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * waiting for data, process it and pass it on.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync */
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync RTTHREADTYPE_VRDP_IO,
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync /** The debugger type.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * Threads involved in servicing the debugger. It must remain
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * responsive even when things are running wild in.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync */
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync RTTHREADTYPE_DEBUGGER,
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync /** Message pump thread.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * Thread pumping messages from one thread/process to another
f72cbd6a549c34992fa79cce84600fe2b92b3299vboxsync * thread/process. The workload is very small, most of the time
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * it's blocked waiting for messages to be procduced or processed.
30f7bd6bf198ae0489df375e5a17cb086acb30fbvboxsync * This type of thread will be favored after I/O threads.
f72cbd6a549c34992fa79cce84600fe2b92b3299vboxsync */
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync RTTHREADTYPE_MSG_PUMP,
4fd4258d68911eacb0b3d1f096b778d19da4e55avboxsync /** The I/O thread type.
4fd4258d68911eacb0b3d1f096b778d19da4e55avboxsync * Doing I/O means shuffling data, waiting for request to arrive and
4fd4258d68911eacb0b3d1f096b778d19da4e55avboxsync * for them to complete. The thread should be favored when competing
f72cbd6a549c34992fa79cce84600fe2b92b3299vboxsync * with any other threads except timer threads.
4fd4258d68911eacb0b3d1f096b778d19da4e55avboxsync */
4fd4258d68911eacb0b3d1f096b778d19da4e55avboxsync RTTHREADTYPE_IO,
4fd4258d68911eacb0b3d1f096b778d19da4e55avboxsync /** The timer thread type.
f72cbd6a549c34992fa79cce84600fe2b92b3299vboxsync * A timer thread is mostly waiting for the timer to tick
4fd4258d68911eacb0b3d1f096b778d19da4e55avboxsync * and then perform a little bit of work. Accuracy is important here,
4fd4258d68911eacb0b3d1f096b778d19da4e55avboxsync * so the thread should be favoured over all threads. If premention can
4fd4258d68911eacb0b3d1f096b778d19da4e55avboxsync * be configured at thread level, it could be made very short.
f72cbd6a549c34992fa79cce84600fe2b92b3299vboxsync */
49207a1552ff3752904e36b9269f08fe643ba871vboxsync RTTHREADTYPE_TIMER,
49207a1552ff3752904e36b9269f08fe643ba871vboxsync /** Only used for validation. */
49207a1552ff3752904e36b9269f08fe643ba871vboxsync RTTHREADTYPE_END
4fd4258d68911eacb0b3d1f096b778d19da4e55avboxsync} RTTHREADTYPE;
4fd4258d68911eacb0b3d1f096b778d19da4e55avboxsync
4fd4258d68911eacb0b3d1f096b778d19da4e55avboxsync
49207a1552ff3752904e36b9269f08fe643ba871vboxsync/**
49207a1552ff3752904e36b9269f08fe643ba871vboxsync * Thread creation flags.
49207a1552ff3752904e36b9269f08fe643ba871vboxsync */
49207a1552ff3752904e36b9269f08fe643ba871vboxsynctypedef enum RTTHREADFLAGS
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync{
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync /**
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * This flag is used to keep the thread structure around so it can
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * be waited on after termination.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync */
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync RTTHREADFLAGS_WAITABLE = RT_BIT(0),
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync /** The bit number corresponding to the RTTHREADFLAGS_WAITABLE mask. */
9c3f21ab6ba51a44403b662e1691293ab266e5e3vboxsync RTTHREADFLAGS_WAITABLE_BIT = 0,
9c3f21ab6ba51a44403b662e1691293ab266e5e3vboxsync
9c3f21ab6ba51a44403b662e1691293ab266e5e3vboxsync /** Mask of valid flags, use for validation. */
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync RTTHREADFLAGS_MASK = RT_BIT(0)
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync} RTTHREADFLAGS;
615105a2b89b7dd89a76504e6a9b8e099704c0d9vboxsync
1f277e5b999f572b1ef1fe4ef593c603ea463be3vboxsync
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync/**
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * Create a new thread.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync *
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * @returns iprt status code.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * @param pThread Where to store the thread handle to the new thread. (optional)
df4af4b66b5f26c3c06ae1592ec2e67afd82dd0cvboxsync * @param pfnThread The thread function.
df4af4b66b5f26c3c06ae1592ec2e67afd82dd0cvboxsync * @param pvUser User argument.
d3361a18160600d3ba74c8dab5bbef532883826avboxsync * @param cbStack The size of the stack for the new thread.
e6a899848410114df5f1db88a025d0843a98112cvboxsync * Use 0 for the default stack size.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * @param enmType The thread type. Used for deciding scheduling attributes
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * of the thread.
f2fedb6cbb946e9dd6d418b1472373395e2ac34fvboxsync * @param fFlags Flags of the RTTHREADFLAGS type (ORed together).
f2fedb6cbb946e9dd6d418b1472373395e2ac34fvboxsync * @param pszName Thread name.
f2fedb6cbb946e9dd6d418b1472373395e2ac34fvboxsync *
6c5e2fff0e3fdfc7c3f3fb2e7b7ec8ebb2223cecvboxsync * @remark When called in Ring-0, this API will create a new kernel thread and not a thread in
6c5e2fff0e3fdfc7c3f3fb2e7b7ec8ebb2223cecvboxsync * the context of the calling process.
6c5e2fff0e3fdfc7c3f3fb2e7b7ec8ebb2223cecvboxsync */
6c5e2fff0e3fdfc7c3f3fb2e7b7ec8ebb2223cecvboxsyncRTDECL(int) RTThreadCreate(PRTTHREAD pThread, PFNRTTHREAD pfnThread, void *pvUser, size_t cbStack,
6c5e2fff0e3fdfc7c3f3fb2e7b7ec8ebb2223cecvboxsync RTTHREADTYPE enmType, unsigned fFlags, const char *pszName);
6c5e2fff0e3fdfc7c3f3fb2e7b7ec8ebb2223cecvboxsync
6c5e2fff0e3fdfc7c3f3fb2e7b7ec8ebb2223cecvboxsync/**
615105a2b89b7dd89a76504e6a9b8e099704c0d9vboxsync * Create a new thread.
615105a2b89b7dd89a76504e6a9b8e099704c0d9vboxsync *
1f277e5b999f572b1ef1fe4ef593c603ea463be3vboxsync * Same as RTThreadCreate except the name is given in the RTStrPrintfV form.
615105a2b89b7dd89a76504e6a9b8e099704c0d9vboxsync *
615105a2b89b7dd89a76504e6a9b8e099704c0d9vboxsync * @returns iprt status code.
615105a2b89b7dd89a76504e6a9b8e099704c0d9vboxsync * @param pThread See RTThreadCreate.
e6a899848410114df5f1db88a025d0843a98112cvboxsync * @param pfnThread See RTThreadCreate.
1f277e5b999f572b1ef1fe4ef593c603ea463be3vboxsync * @param pvUser See RTThreadCreate.
615105a2b89b7dd89a76504e6a9b8e099704c0d9vboxsync * @param cbStack See RTThreadCreate.
f2fedb6cbb946e9dd6d418b1472373395e2ac34fvboxsync * @param enmType See RTThreadCreate.
615105a2b89b7dd89a76504e6a9b8e099704c0d9vboxsync * @param fFlags See RTThreadCreate.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * @param pszName Thread name format.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync * @param va Format arguments.
05c28d9d4557bed6e320dfee1acca69408bc3c15vboxsync */
f6adf1a86574758258baa232172c965aed0d848dvboxsyncRTDECL(int) RTThreadCreateV(PRTTHREAD pThread, PFNRTTHREAD pfnThread, void *pvUser, size_t cbStack,
RTTHREADTYPE enmType, uint32_t fFlags, const char *pszNameFmt, va_list va);
/**
* Create a new thread.
*
* Same as RTThreadCreate except the name is given in the RTStrPrintf form.
*
* @returns iprt status code.
* @param pThread See RTThreadCreate.
* @param pfnThread See RTThreadCreate.
* @param pvUser See RTThreadCreate.
* @param cbStack See RTThreadCreate.
* @param enmType See RTThreadCreate.
* @param fFlags See RTThreadCreate.
* @param pszName Thread name format.
* @param ... Format arguments.
*/
RTDECL(int) RTThreadCreateF(PRTTHREAD pThread, PFNRTTHREAD pfnThread, void *pvUser, size_t cbStack,
RTTHREADTYPE enmType, uint32_t fFlags, const char *pszNameFmt, ...);
/**
* Gets the native thread id of a IPRT thread.
*
* @returns The native thread id.
* @param Thread The IPRT thread.
*/
RTDECL(RTNATIVETHREAD) RTThreadGetNative(RTTHREAD Thread);
/**
* Gets the IPRT thread of a native thread.
*
* @returns The IPRT thread handle
* @returns NIL_RTTHREAD if not a thread known to IPRT.
* @param NativeThread The native thread handle/id.
*/
RTDECL(RTTHREAD) RTThreadFromNative(RTNATIVETHREAD NativeThread);
/**
* Changes the type of the specified thread.
*
* @returns iprt status code.
* @param Thread The thread which type should be changed.
* @param enmType The new thread type.
* @remark In Ring-0 it only works if Thread == RTThreadSelf().
*/
RTDECL(int) RTThreadSetType(RTTHREAD Thread, RTTHREADTYPE enmType);
/**
* Wait for the thread to terminate, resume on interruption.
*
* @returns iprt status code.
* Will not return VERR_INTERRUPTED.
* @param Thread The thread to wait for.
* @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for
* an indefinite wait.
* @param prc Where to store the return code of the thread. Optional.
*/
RTDECL(int) RTThreadWait(RTTHREAD Thread, unsigned cMillies, int *prc);
/**
* Wait for the thread to terminate, return on interruption.
*
* @returns iprt status code.
* @param Thread The thread to wait for.
* @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for
* an indefinite wait.
* @param prc Where to store the return code of the thread. Optional.
*/
RTDECL(int) RTThreadWaitNoResume(RTTHREAD Thread, unsigned cMillies, int *prc);
/**
* Gets the name of the current thread thread.
*
* @returns Pointer to readonly name string.
* @returns NULL on failure.
*/
RTDECL(const char *) RTThreadSelfName(void);
/**
* Gets the name of a thread.
*
* @returns Pointer to readonly name string.
* @returns NULL on failure.
* @param Thread Thread handle of the thread to query the name of.
*/
RTDECL(const char *) RTThreadGetName(RTTHREAD Thread);
/**
* Gets the type of the specified thread.
*
* @returns The thread type.
* @returns RTTHREADTYPE_INVALID if the thread handle is invalid.
* @param Thread The thread in question.
*/
RTDECL(RTTHREADTYPE) RTThreadGetType(RTTHREAD Thread);
/**
* Sets the name of a thread.
*
* @returns iprt status code.
* @param Thread Thread handle of the thread to query the name of.
* @param pszName The thread name.
*/
RTDECL(int) RTThreadSetName(RTTHREAD Thread, const char *pszName);
/**
* Signal the user event.
*
* @returns iprt status code.
*/
RTDECL(int) RTThreadUserSignal(RTTHREAD Thread);
/**
* Wait for the user event.
*
* @returns iprt status code.
* @param Thread The thread to wait for.
* @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for
* an indefinite wait.
*/
RTDECL(int) RTThreadUserWait(RTTHREAD Thread, unsigned cMillies);
/**
* Wait for the user event, return on interruption.
*
* @returns iprt status code.
* @param Thread The thread to wait for.
* @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for
* an indefinite wait.
*/
RTDECL(int) RTThreadUserWaitNoResume(RTTHREAD Thread, unsigned cMillies);
/**
* Reset the user event.
*
* @returns iprt status code.
* @param Thread The thread to reset.
*/
RTDECL(int) RTThreadUserReset(RTTHREAD Thread);
/**
* Pokes the thread.
*
* This will signal the thread, attempting to interrupt whatever it's currently
* doing. This is *NOT* implemented on all platforms and may cause unresolved
* symbols during linking or VERR_NOT_IMPLEMENTED at runtime.
*
* @returns IPRT status code.
*
* @param hThread The thread to poke. This must not be the
* calling thread.
*/
RTDECL(int) RTThreadPoke(RTTHREAD hThread);
#ifdef IN_RING0
/**
* Check if preemption is currently enabled or not for the current thread.
*
* @returns true if preemtion is enabled, false if preemetion is disabled.
* @param hThread Must be NIL_RTTHREAD for now.
*/
RTDECL(bool) RTThreadPreemptIsEnabled(RTTHREAD hThread);
/**
* Preemption state saved by RTThreadPreemptDisable and used by
* RTThreadPreemptRestore to restore the previous state.
*/
typedef struct RTTHREADPREEMPTSTATE
{
#ifdef RT_OS_WINDOWS
/** The old IRQL. Don't touch. */
unsigned char uchOldIrql;
# define RTTHREADPREEMPTSTATE_INITIALIZER { 255 }
#else
/** Dummy unused placeholder. */
unsigned char uchDummy;
# define RTTHREADPREEMPTSTATE_INITIALIZER { 0 }
#endif
} RTTHREADPREEMPTSTATE;
/** Pointer to a preemption state. */
typedef RTTHREADPREEMPTSTATE *PRTTHREADPREEMPTSTATE;
/**
* Disable preemption.
*
* A call to this function must be matched by exactly one call to
* RTThreadPreemptRestore().
*
* @param pState Where to store the preemption state.
*/
RTDECL(void) RTThreadPreemptDisable(PRTTHREADPREEMPTSTATE pState);
/**
* Restores the preemption state, undoing a previous call to
* RTThreadPreemptDisable.
*
* A call to this function must be matching a previous call to
* RTThreadPreemptDisable.
*
* @param pState The state return by RTThreadPreemptDisable.
*/
RTDECL(void) RTThreadPreemptRestore(PRTTHREADPREEMPTSTATE pState);
#endif /* IN_RING0 */
#ifdef IN_RING3
/**
* Adopts a non-IPRT thread.
*
* @returns IPRT status code.
* @param enmType The thread type.
* @param fFlags The thread flags. RTTHREADFLAGS_WAITABLE is not currently allowed.
* @param pszName The thread name. Optional
* @param pThread Where to store the thread handle. Optional.
*/
RTDECL(int) RTThreadAdopt(RTTHREADTYPE enmType, unsigned fFlags, const char *pszName, PRTTHREAD pThread);
/**
* Gets the affinity mask of the current thread.
*
* @returns The affinity mask (bit 0 = logical cpu 0).
*/
RTR3DECL(uint64_t) RTThreadGetAffinity(void);
/**
* Sets the affinity mask of the current thread.
*
* @returns iprt status code.
* @param u64Mask Affinity mask (bit 0 = logical cpu 0).
*/
RTR3DECL(int) RTThreadSetAffinity(uint64_t u64Mask);
/**
* Gets the number of write locks and critical sections the specified
* thread owns.
*
* This number does not include any nested lock/critect entries.
*
* Note that it probably will return 0 for non-strict builds since
* release builds doesn't do unnecessary diagnostic counting like this.
*
* @returns Number of locks on success (0+) and VERR_INVALID_HANDLER on failure
* @param Thread The thread we're inquiring about.
* @remarks Will only work for strict builds.
*/
RTDECL(int32_t) RTThreadGetWriteLockCount(RTTHREAD Thread);
/**
* Works the THREADINT::cWriteLocks member, mostly internal.
*
* @param Thread The current thread.
*/
RTDECL(void) RTThreadWriteLockInc(RTTHREAD Thread);
/**
* Works the THREADINT::cWriteLocks member, mostly internal.
*
* @param Thread The current thread.
*/
RTDECL(void) RTThreadWriteLockDec(RTTHREAD Thread);
/**
* Gets the number of read locks the specified thread owns.
*
* Note that nesting read lock entry will be included in the
* total sum. And that it probably will return 0 for non-strict
* builds since release builds doesn't do unnecessary diagnostic
* counting like this.
*
* @returns Number of read locks on success (0+) and VERR_INVALID_HANDLER on failure
* @param Thread The thread we're inquiring about.
*/
RTDECL(int32_t) RTThreadGetReadLockCount(RTTHREAD Thread);
/**
* Works the THREADINT::cReadLocks member.
*
* @param Thread The current thread.
*/
RTDECL(void) RTThreadReadLockInc(RTTHREAD Thread);
/**
* Works the THREADINT::cReadLocks member.
*
* @param Thread The current thread.
*/
RTDECL(void) RTThreadReadLockDec(RTTHREAD Thread);
/** @name Thread Local Storage
* @{
*/
/**
* Thread termination callback for destroying a non-zero TLS entry.
*
* @remarks It is not permittable to use any RTTls APIs at this time. Doing so
* may lead to endless loops, crashes, and other bad stuff.
*
* @param pvValue The current value.
*/
typedef DECLCALLBACK(void) FNRTTLSDTOR(void *pvValue);
/** Pointer to a FNRTTLSDTOR. */
typedef FNRTTLSDTOR *PFNRTTLSDTOR;
/**
* Allocates a TLS entry.
*
* @returns the index of the allocated TLS entry.
* @returns NIL_RTTLS on failure.
*/
RTR3DECL(RTTLS) RTTlsAlloc(void);
/**
* Allocates a TLS entry (with status code).
*
* @returns IPRT status code.
* @retval VERR_NOT_SUPPORTED if pfnDestructor is non-NULL and the platform
* doesn't support this feature.
*
* @param piTls Where to store the index of the allocated TLS entry.
* This is set to NIL_RTTLS on failure.
* @param pfnDestructor Optional callback function for cleaning up on
* thread termination. WARNING! This feature may not
* be implemented everywhere.
*/
RTR3DECL(int) RTTlsAllocEx(PRTTLS piTls, PFNRTTLSDTOR pfnDestructor);
/**
* Frees a TLS entry.
*
* @returns IPRT status code.
* @param iTls The index of the TLS entry.
*/
RTR3DECL(int) RTTlsFree(RTTLS iTls);
/**
* Get the value stored in a TLS entry.
*
* @returns value in given TLS entry.
* @returns NULL on failure.
* @param iTls The index of the TLS entry.
*/
RTR3DECL(void *) RTTlsGet(RTTLS iTls);
/**
* Get the value stored in a TLS entry.
*
* @returns IPRT status code.
* @param iTls The index of the TLS entry.
* @param ppvValue Where to store the value.
*/
RTR3DECL(int) RTTlsGetEx(RTTLS iTls, void **ppvValue);
/**
* Set the value stored in an allocated TLS entry.
*
* @returns IPRT status.
* @param iTls The index of the TLS entry.
* @param pvValue The value to store.
*
* @remarks Note that NULL is considered to special value.
*/
RTR3DECL(int) RTTlsSet(RTTLS iTls, void *pvValue);
/** @} */
#endif /* IN_RING3 */
/** @} */
__END_DECLS
#endif