thread.h revision c98fb3e16fcd571a790eab772c0c66173d225205
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync/** @file
7eaaa8a4480370b82ef3735994f986f338fb4df2vboxsync * innotek Portable Runtime - Threads.
7eaaa8a4480370b82ef3735994f986f338fb4df2vboxsync */
7eaaa8a4480370b82ef3735994f986f338fb4df2vboxsync
7eaaa8a4480370b82ef3735994f986f338fb4df2vboxsync/*
7eaaa8a4480370b82ef3735994f986f338fb4df2vboxsync * Copyright (C) 2006-2007 innotek GmbH
c58f1213e628a545081c70e26c6b67a841cff880vboxsync *
7eaaa8a4480370b82ef3735994f986f338fb4df2vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
7eaaa8a4480370b82ef3735994f986f338fb4df2vboxsync * available from http://www.virtualbox.org. This file is free software;
7eaaa8a4480370b82ef3735994f986f338fb4df2vboxsync * you can redistribute it and/or modify it under the terms of the GNU
7eaaa8a4480370b82ef3735994f986f338fb4df2vboxsync * General Public License as published by the Free Software Foundation,
7eaaa8a4480370b82ef3735994f986f338fb4df2vboxsync * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
7eaaa8a4480370b82ef3735994f986f338fb4df2vboxsync * distribution. VirtualBox OSE is distributed in the hope that it will
7eaaa8a4480370b82ef3735994f986f338fb4df2vboxsync * be useful, but WITHOUT ANY WARRANTY of any kind.
7eaaa8a4480370b82ef3735994f986f338fb4df2vboxsync */
7eaaa8a4480370b82ef3735994f986f338fb4df2vboxsync
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync#ifndef ___iprt_thread_h
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync#define ___iprt_thread_h
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync#include <iprt/cdefs.h>
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync#include <iprt/types.h>
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync#ifdef IN_GC
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync# error "There are no threading APIs available Guest Context!"
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync#endif
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync__BEGIN_DECLS
f40255ebb8e145bc49daa701edf16f1596cc93cevboxsync
f40255ebb8e145bc49daa701edf16f1596cc93cevboxsync/** @defgroup grp_rt_thread RTThread - Thread Management
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * @ingroup grp_rt
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * @{
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync */
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync/**
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * Get the thread handle of the current thread.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync *
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * @returns Thread handle.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync */
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsyncRTDECL(RTTHREAD) RTThreadSelf(void);
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync/**
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * Get the native thread handle of the current thread.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync *
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * @returns Native thread handle.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync */
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsyncRTDECL(RTNATIVETHREAD) RTThreadNativeSelf(void);
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync
f05c9726893158b78436cc78907835367d922de9vboxsync/**
f05c9726893158b78436cc78907835367d922de9vboxsync * Millisecond granular sleep function.
ebd3c63c626c8039fdb7b95570390699333a7072vboxsync *
ebd3c63c626c8039fdb7b95570390699333a7072vboxsync * @returns VINF_SUCCESS on success.
0a249d1fff442e1f0f29959e2a0da91d024554fcvboxsync * @returns VERR_INTERRUPTED if a signal or other asynchronous stuff happend
0a249d1fff442e1f0f29959e2a0da91d024554fcvboxsync * which interrupt the peaceful sleep.
f40255ebb8e145bc49daa701edf16f1596cc93cevboxsync * @param cMillies Number of milliseconds to sleep.
f40255ebb8e145bc49daa701edf16f1596cc93cevboxsync * 0 milliseconds means yielding the timeslice - deprecated!
f40255ebb8e145bc49daa701edf16f1596cc93cevboxsync * @remark See RTThreadNanoSleep() for sleeping for smaller periods of time.
f40255ebb8e145bc49daa701edf16f1596cc93cevboxsync */
f05c9726893158b78436cc78907835367d922de9vboxsyncRTDECL(int) RTThreadSleep(unsigned cMillies);
f05c9726893158b78436cc78907835367d922de9vboxsync
ebd3c63c626c8039fdb7b95570390699333a7072vboxsync/**
ebd3c63c626c8039fdb7b95570390699333a7072vboxsync * Yields the CPU.
0a249d1fff442e1f0f29959e2a0da91d024554fcvboxsync *
0a249d1fff442e1f0f29959e2a0da91d024554fcvboxsync * @returns true if we yielded.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * @returns false if it's probable that we didn't yield.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync */
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsyncRTDECL(bool) RTThreadYield(void);
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync
0a249d1fff442e1f0f29959e2a0da91d024554fcvboxsync
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync/**
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * Thread function.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync *
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * @returns 0 on success.
7eaaa8a4480370b82ef3735994f986f338fb4df2vboxsync * @param ThreadSelf Thread handle to this thread.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * @param pvUser User argument.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync */
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsynctypedef DECLCALLBACK(int) FNRTTHREAD(RTTHREAD ThreadSelf, void *pvUser);
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync/** Pointer to a FNRTTHREAD(). */
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsynctypedef FNRTTHREAD *PFNRTTHREAD;
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync/**
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * Thread types.
7eaaa8a4480370b82ef3735994f986f338fb4df2vboxsync * Besides identifying the purpose of the thread, the thread type is
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * used to select the scheduling properties.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync *
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * The types in are placed in a rough order of ascending priority.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync */
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsynctypedef enum RTTHREADTYPE
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync{
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync /** Invalid type. */
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync RTTHREADTYPE_INVALID = 0,
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync /** Infrequent poller thread.
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync * This type of thread will sleep for the most of the time, and do
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync * infrequent polls on resources at 0.5 sec or higher intervals.
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync */
1ab75e3bb644b29eb1cadd4f6075147012c22757vboxsync RTTHREADTYPE_INFREQUENT_POLLER,
ebd3c63c626c8039fdb7b95570390699333a7072vboxsync /** Main heavy worker thread.
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync * Thread of this type is driving asynchronous tasks in the Main
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync * API which takes a long time and might involve a bit of CPU. Like
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync * for instance creating a fixed sized VDI.
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync */
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync RTTHREADTYPE_MAIN_HEAVY_WORKER,
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync /** The emulation thread type.
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync * While being a thread with very high workload it still is vital
78d5c1f3e0c4c4dce02baa0be07e616bc212f441vboxsync * that it gets scheduled frequently. When possible all other thread
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync * types except DEFAULT and GUI should interrupt this one ASAP when
38e7976384c17215607055e2574ae71d386ba7bbvboxsync * they become ready.
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync */
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync RTTHREADTYPE_EMULATION,
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync /** The default thread type.
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync * Since it doesn't say much about the purpose of the thread
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync * nothing special is normally done to the scheduling. This type
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync * should be avoided.
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync * The main thread is registered with default type during RTR3Init()
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync * and that's what the default process priority is derived from.
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync */
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync RTTHREADTYPE_DEFAULT,
be75da5235e6ed26c171a06f0a7d0e718bd7f60bvboxsync /** The GUI thread type
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * The GUI normally have a low workload but is frequently scheduled
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * to handle events. When possible the scheduler should not leave
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * threads of this kind waiting for too long (~50ms).
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync */
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync RTTHREADTYPE_GUI,
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync /** Main worker thread.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * Thread of this type is driving asynchronous tasks in the Main API.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * In most cases this means little work an a lot of waiting.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync */
f55e40eab578fb43357fe057f8088cc16bb1a9e9vboxsync RTTHREADTYPE_MAIN_WORKER,
f55e40eab578fb43357fe057f8088cc16bb1a9e9vboxsync /** VRDP I/O thread.
f55e40eab578fb43357fe057f8088cc16bb1a9e9vboxsync * These threads are I/O threads in the RDP server will hang around
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * waiting for data, process it and pass it on.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync */
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync RTTHREADTYPE_VRDP_IO,
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync /** The debugger type.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * Threads involved in servicing the debugger. It must remain
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * responsive even when things are running wild in.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync */
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync RTTHREADTYPE_DEBUGGER,
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync /** Message pump thread.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * Thread pumping messages from one thread/process to another
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * thread/process. The workload is very small, most of the time
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * it's blocked waiting for messages to be procduced or processed.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * This type of thread will be favored after I/O threads.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync */
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync RTTHREADTYPE_MSG_PUMP,
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync /** The I/O thread type.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * Doing I/O means shuffling data, waiting for request to arrive and
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * for them to complete. The thread should be favored when competing
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * with any other threads except timer threads.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync */
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync RTTHREADTYPE_IO,
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync /** The timer thread type.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * A timer thread is mostly waiting for the timer to tick
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * and then perform a little bit of work. Accuracy is important here,
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * so the thread should be favoured over all threads. If premention can
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * be configured at thread level, it could be made very short.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync */
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync RTTHREADTYPE_TIMER,
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync /** Only used for validation. */
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync RTTHREADTYPE_END
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync} RTTHREADTYPE;
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync/**
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * Thread creation flags.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync */
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsynctypedef enum RTTHREADFLAGS
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync{
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync /**
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * This flag is used to keep the thread structure around so it can
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync * be waited on after termination.
320484435d67c1fb90dca3e8836d81bf939c8ba2vboxsync */
38e7976384c17215607055e2574ae71d386ba7bbvboxsync RTTHREADFLAGS_WAITABLE = BIT(0),
/** The bit number corresponding to the RTTHREADFLAGS_WAITABLE mask. */
RTTHREADFLAGS_WAITABLE_BIT = 0,
/** Mask of valid flags, use for validation. */
RTTHREADFLAGS_MASK = BIT(0)
} RTTHREADFLAGS;
/**
* Create a new thread.
*
* @returns iprt status code.
* @param pThread Where to store the thread handle to the new thread. (optional)
* @param pfnThread The thread function.
* @param pvUser User argument.
* @param cbStack The size of the stack for the new thread.
* Use 0 for the default stack size.
* @param enmType The thread type. Used for deciding scheduling attributes
* of the thread.
* @param fFlags Flags of the RTTHREADFLAGS type (ORed together).
* @param pszName Thread name.
*
* @remark When called in Ring-0, this API will create a new kernel thread and not a thread in
* the context of the calling process.
*/
RTDECL(int) RTThreadCreate(PRTTHREAD pThread, PFNRTTHREAD pfnThread, void *pvUser, size_t cbStack,
RTTHREADTYPE enmType, unsigned fFlags, const char *pszName);
/**
* 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);
#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);
#endif /* IN_RING3 */
/** @} */
__END_DECLS
#endif