thread.h revision e823cc58066c955961f56ff2864b3708b9c5f9fd
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * IPRT - Threads.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * Copyright (C) 2006-2007 Oracle Corporation
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * available from http://www.virtualbox.org. This file is free software;
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * you can redistribute it and/or modify it under the terms of the GNU
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * General Public License (GPL) as published by the Free Software
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * The contents of this file may alternatively be used under the terms
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * of the Common Development and Distribution License Version 1.0
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * VirtualBox OSE distribution, in which case the provisions of the
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * CDDL are applicable instead of those of the GPL.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * You may elect to license modified versions of this file under the
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * terms and conditions of either the GPL or the CDDL or both.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync/** @defgroup grp_rt_thread RTThread - Thread Management
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * @ingroup grp_rt
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * The thread state.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** The usual invalid 0 value. */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** The thread is being initialized. */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** The thread has terminated */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** Probably running. */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** Waiting on a critical section. */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** Waiting on a event semaphore. */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** Waiting on a event multiple wakeup semaphore. */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** Waiting on a fast mutex. */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** Waiting on a mutex. */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** Waiting on a read write semaphore, read (shared) access. */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** Waiting on a read write semaphore, write (exclusive) access. */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** The thread is sleeping. */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** Waiting on a spin mutex. */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** The usual 32-bit size hack. */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync/** Checks if a thread state indicates that the thread is sleeping. */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync#define RTTHREAD_IS_SLEEPING(enmState) ((enmState) >= RTTHREADSTATE_CRITSECT)
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * Thread types.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * Besides identifying the purpose of the thread, the thread type is
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * used to select the scheduling properties.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * The types in are placed in a rough order of ascending priority.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** Invalid type. */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** Infrequent poller thread.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * This type of thread will sleep for the most of the time, and do
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * infrequent polls on resources at 0.5 sec or higher intervals.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** Main heavy worker thread.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * Thread of this type is driving asynchronous tasks in the Main
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * API which takes a long time and might involve a bit of CPU. Like
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * for instance creating a fixed sized VDI.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** The emulation thread type.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * While being a thread with very high workload it still is vital
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * that it gets scheduled frequently. When possible all other thread
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * types except DEFAULT and GUI should interrupt this one ASAP when
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * they become ready.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** The default thread type.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * Since it doesn't say much about the purpose of the thread
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * nothing special is normally done to the scheduling. This type
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * should be avoided.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * The main thread is registered with default type during RTR3Init()
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * and that's what the default process priority is derived from.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** The GUI thread type
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * The GUI normally have a low workload but is frequently scheduled
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * to handle events. When possible the scheduler should not leave
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * threads of this kind waiting for too long (~50ms).
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** Main worker thread.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * Thread of this type is driving asynchronous tasks in the Main API.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * In most cases this means little work an a lot of waiting.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** VRDP I/O thread.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * These threads are I/O threads in the RDP server will hang around
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * waiting for data, process it and pass it on.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** The debugger type.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * Threads involved in servicing the debugger. It must remain
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * responsive even when things are running wild in.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** Message pump thread.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * Thread pumping messages from one thread/process to another
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * thread/process. The workload is very small, most of the time
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * it's blocked waiting for messages to be procduced or processed.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * This type of thread will be favored after I/O threads.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** The I/O thread type.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * Doing I/O means shuffling data, waiting for request to arrive and
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * for them to complete. The thread should be favored when competing
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * with any other threads except timer threads.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** The timer thread type.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * A timer thread is mostly waiting for the timer to tick
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * and then perform a little bit of work. Accuracy is important here,
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * so the thread should be favoured over all threads. If premention can
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * be configured at thread level, it could be made very short.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync /** Only used for validation. */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * Get the thread handle of the current thread.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * @returns Thread handle.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * Get the thread handle of the current thread, automatically adopting alien
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync * @returns Thread handle.
typedef enum RTTHREADFLAGS
# ifdef IN_RING0
typedef struct RTTHREADPREEMPTSTATE
# ifdef RT_OS_WINDOWS
unsigned char uchOldIrql;
# ifdef IN_RING3
RTDECL(int) RTThreadAdopt(RTTHREADTYPE enmType, unsigned fFlags, const char *pszName, PRTTHREAD pThread);
typedef enum RTTHREADNATIVESTATE