thread.h revision 8ddb51786b506ba3395546aa1af6cac6d3114e1c
* Get the thread handle of the current thread. * @returns Thread handle. * Get the native thread handle of the current thread. * @returns Native thread handle. * Millisecond granular sleep function. * @returns VINF_SUCCESS on success. * @returns VERR_INTERRUPTED if a signal or other asynchronous stuff happend * which interrupt the peaceful sleep. * @param cMillies Number of milliseconds to sleep. * 0 milliseconds means yielding the timeslice - deprecated! * @remark See RTThreadNanoSleep() for sleeping for smaller periods of time. * @returns true if we yielded. * @returns false if it's probable that we didn't yield. * @param ThreadSelf Thread handle to this thread. * @param pvUser User argument. /** Pointer to a FNRTTHREAD(). */ * Besides identifying the purpose of the thread, the thread type is * used to select the scheduling properties. * The types in are placed in a rough order of ascending priority. /** Infrequent poller thread. * This type of thread will sleep for the most of the time, and do * infrequent polls on resources at 0.5 sec or higher intervals. /** Main heavy worker thread. * Thread of this type is driving asynchronous tasks in the Main * API which takes a long time and might involve a bit of CPU. Like * for instance creating a fixed sized VDI. /** The emulation thread type. * While being a thread with very high workload it still is vital * that it gets scheduled frequently. When possible all other thread * types except DEFAULT and GUI should interrupt this one ASAP when /** The default thread type. * Since it doesn't say much about the purpose of the thread * nothing special is normally done to the scheduling. This type * The main thread is registered with default type during RTR3Init() * and that's what the default process priority is derived from. * The GUI normally have a low workload but is frequently scheduled * to handle events. When possible the scheduler should not leave * threads of this kind waiting for too long (~50ms). * Thread of this type is driving asynchronous tasks in the Main API. * In most cases this means little work an a lot of waiting. * These threads are I/O threads in the RDP server will hang around * waiting for data, process it and pass it on. * Threads involved in servicing the debugger. It must remain * responsive even when things are running wild in. * it's blocked waiting for messages to be procduced or processed. * This type of thread will be favored after I/O threads. * Doing I/O means shuffling data, waiting for request to arrive and * for them to complete. The thread should be favored when competing * with any other threads except timer threads. /** The timer thread type. * A timer thread is mostly waiting for the timer to tick * and then perform a little bit of work. Accuracy is important here, * so the thread should be favoured over all threads. If premention can * be configured at thread level, it could be made very short. /** Only used for validation. */ * This flag is used to keep the thread structure around so it can * be waited on after termination. /** The bit number corresponding to the RTTHREADFLAGS_WAITABLE mask. */ /** Mask of valid flags, use for validation. */ * @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 * @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. * Same as RTThreadCreate except the name is given in the RTStrPrintfV 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 va Format arguments. * 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. * Gets the native thread id of a IPRT thread. * @returns The native thread id. * @param Thread The IPRT 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. * 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(). * 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 * @param prc Where to store the return code of the thread. Optional. * 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 * @param prc Where to store the return code of the thread. Optional. * Gets the name of the current thread thread. * @returns Pointer to readonly name string. * @returns NULL on failure. * 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. * 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. * 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. * @returns iprt status code. * 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 * 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 * @returns iprt status code. * @param Thread The thread to reset. * 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 * 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. * Check if preemption is pending for the current thread. * This function should be called regularly when executing larger portions of * code with preemption disabled. * @returns true if pending, false if not. * @param hThread Must be NIL_RTTHREAD for now. * Is RTThreadPreemptIsPending reliable? * @returns true if pending, false if not. * Preemption state saved by RTThreadPreemptDisable and used by * RTThreadPreemptRestore to restore the previous state. /** The old IRQL. Don't touch. */ /** Dummy unused placeholder. */ /** Pointer to a preemption state. */ * A call to this function must be matched by exactly one call to * RTThreadPreemptRestore(). * @param pState Where to store the preemption state. * 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. * 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. * Gets the affinity mask of the current thread. * @returns The affinity mask (bit 0 = logical cpu 0). * Sets the affinity mask of the current thread. * @returns iprt status code. * @param u64Mask Affinity mask (bit 0 = logical cpu 0). * Gets the number of write locks and critical sections the specified * 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. * Works the THREADINT::cWriteLocks member, mostly internal. * @param Thread The current thread. * Works the THREADINT::cWriteLocks member, mostly internal. * @param Thread The current 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 * @returns Number of read locks on success (0+) and VERR_INVALID_HANDLER on failure * @param Thread The thread we're inquiring about. * Works the THREADINT::cReadLocks member. * @param Thread The current thread. * Works the THREADINT::cReadLocks member. * @param Thread The current thread. * This function is paired with rtThreadBlocking. * @param hThread The current thread. * @param enmCurState The current state, used to check for nested blocking. * The new state will be running. * Change the thread state to blocking and do deadlock detection. * This is a RT_STRICT method for debugging locks and detecting deadlocks. * @param hThread The current thread. * @param enmState The sleep state. * @param u64Block The block data. A pointer or handle. * @param pszFile Where we are blocking. * @param uLine Where we are blocking. * @param uId Where we are blocking. /** @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. /** Pointer to a FNRTTLSDTOR. */ * @returns the index of the allocated TLS entry. * @returns NIL_RTTLS on failure. * 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. * @returns IPRT status code. * @param iTls The index of the TLS entry. * 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. * 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. * Set the value stored in an allocated TLS entry. * @param iTls The index of the TLS entry. * @param pvValue The value to store. * @remarks Note that NULL is considered to special value.