Windows Process, thread and synchronization: Functions used in program examples of ModuleR, ModuleS, ModuleT, ModuleU, ModuleV and ModuleAA, wherever applicable.

To learn about function you can jump to Module 4.

Index

WaitForSingleObject()

WaitForMultipleObjects()

CloseHandle()

GetPriorityClass()

SetPriorityClass()

CreateToolhelp32Snapshot()

Process32First()

Process32Next()

CreateThread()

ThreadProc()

ResumeThread()

SuspendThread()

ExitThread()

GetExitCodeThread()

TerminateThread()

GetThreadPriority()

SetThreadPriority()

ExitProcess()

CreateRemoteThread()

GetCurrentThread()

GetCurrentThreadId()

TlsAlloc()

TlsSetValue()

TlsGetValue()

TlsFree()

ImpersonateNamedPipeClient()

OpenThreadToken()

MapGenericMask()

AccessCheck()

AccessCheckAndAuditAlarm()

WaitForSingleObject()

Item	Description
Function	WaitForSingleObject().
Use	The function returns when the specified object is in the signaled state or the time-out interval elapses. To enter an alertable wait state, use the WaitForSingleObjectEx() function. To wait for multiple objects, use the WaitForMultipleObjects().
Prototype	DWORD WaitForSingleObject(HANDLE hHandle, DWORD dwMilliseconds);
Parameters	hHandle [in] Handle to the object. For a list of the object types whose handles can be specified, see the following Remarks section. If this handle is closed while the wait is still pending, the function's behavior is undefined. The handle must have the SYNCHRONIZE access right. dwMilliseconds [in] Time-out interval, in milliseconds. The function returns if the interval elapses, even if the object's state is non-signaled. If dwMilliseconds is zero, the function tests the object's state and returns immediately. If dwMilliseconds is INFINITE, the function's time-out interval never elapses.
Return value	See below.
Include file	<windows.h>
Remark	See below.
Table 1.

Return Values

If the function succeeds, the return value indicates the event that caused the function to return. It can be one of the following values.

Return code	Description
WAIT_ABANDONED	The specified object is a mutex object that was not released by the thread that owned the mutex object before the owning thread terminated. Ownership of the mutex object is granted to the calling thread, and the mutex is set to non-signaled.
WAIT_OBJECT_0	The state of the specified object is signaled.
WAIT_TIMEOUT	The time-out interval elapsed, and the object's state is non-signaled.
Table 2

If the function fails, the return value is WAIT_FAILED. To get extended error information, call GetLastError().

Remarks

The WaitForSingleObject() function checks the current state of the specified object. If the object's state is non-signaled, the calling thread enters the wait state. It uses no processor time while waiting for the object state to become signaled or the time-out interval to elapse. The function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the function to return. For example, the count of a semaphore object is decreased by one. The WaitForSingleObject() function can wait for the following objects:

▪ Change notification.

▪ Console input.

▪ Event.

▪ Job.

▪ Memory resource notification.

▪ Mutex.

▪ Process.

▪ Semaphore.

▪ Thread.

▪ Waitable timer.

Use caution when calling the wait functions and code that directly or indirectly creates windows. If a thread creates any windows, it must process messages. Message broadcasts are sent to all windows in the system. A thread that uses a wait function with no time-out interval may cause the system to become deadlocked. Two examples of code that indirectly creates windows are DDE and the CoInitialize() function. Therefore, if you have a thread that creates windows, use MsgWaitForMultipleObjects() or MsgWaitForMultipleObjectsEx(), rather than WaitForSingleObject().

WaitForMultipleObjects()

Item	Description
Function	WaitForMultipleObjects().
Use	Returns when any one or all of the specified objects are in the signaled state or the time-out interval elapses. To enter an alertable wait state, use the WaitForMultipleObjectsEx() function.
Prototype	DWORD WaitForMultipleObjects( DWORD nCount, const HANDLE* lpHandles, BOOL bWaitAll, DWORD dwMilliseconds);
Parameters	See below.
Return value	See below.
Include file	<windows.h>
Remark	See below.
Table 3.

Parameters

nCount

[in] Number of object handles in the array pointed to by lpHandles. The maximum number of object handles is MAXIMUM_WAIT_OBJECTS.

lpHandles

[in] Pointer to an array of object handles. For a list of the object types whose handles can be specified, see the following Remarks section. The array can contain handles to objects of different types. It may not contain the multiple copies of the same handle.

If one of these handles is closed while the wait is still pending, the function's behavior is undefined.

The handles must have the SYNCHRONIZE access right. For Windows Me/98/95: No handle may be a duplicate of another handle created using DuplicateHandle().

bWaitAll

[in] If this parameter is TRUE, the function returns when the state of all objects in the lpHandles array is signaled. If FALSE, the function returns when the state of any one of the objects is set to signaled. In the latter case, the return value indicates the object whose state caused the function to return.

dwMilliseconds

[in] Time-out interval, in milliseconds. The function returns if the interval elapses, even if the conditions specified by the bWaitAll parameter are not met. If dwMilliseconds is zero, the function tests the states of the specified objects and returns immediately. If dwMilliseconds is INFINITE, the function's time-out interval never elapses.

Return Values

If the function succeeds, the return value indicates the event that caused the function to return. It can be one of the following values.

Return code	Description
WAIT_OBJECT_0 to (WAIT_OBJECT_0 + nCount – 1)	If bWaitAll is TRUE, the return value indicates that the state of all specified objects is signaled. If bWaitAll is FALSE, the return value minus WAIT_OBJECT_0 indicates the lpHandles array index of the object that satisfied the wait. If more than one object became signaled during the call, this is the array index of the signaled object with the smallest index value of all the signaled objects.
WAIT_ABANDONED_0 to (WAIT_ABANDONED_0 + nCount – 1)	If bWaitAll is TRUE, the return value indicates that the state of all specified objects is signaled and at least one of the objects is an abandoned mutex object. If bWaitAll is FALSE, the return value minus WAIT_ABANDONED_0 indicates the lpHandles array index of an abandoned mutex object that satisfied the wait.
WAIT_TIMEOUT	The time-out interval elapsed and the conditions specified by the bWaitAll parameter are not satisfied.
Table 4

If the function fails, the return value is WAIT_FAILED. To get extended error information, call GetLastError().

Remarks

The WaitForMultipleObjects function determines whether the wait criteria have been met. If the criteria have not been met, the calling thread enters the wait state. It uses no processor time while waiting for the criteria to be met.

When bWaitAll is TRUE, the function's wait operation is completed only when the states of all objects have been set to signaled. The function does not modify the states of the specified objects until the states of all objects have been set to signaled. For example, a mutex can be signaled, but the thread does not get ownership until the states of the other objects are also set to signaled. In the meantime, some other thread may get ownership of the mutex, thereby setting its state to non-signaled.

The function modifies the state of some types of synchronization objects. Modification occurs only for the object or objects whose signaled state caused the function to return. For example, the count of a semaphore object is decreased by one. When bWaitAll is FALSE, and multiple objects are in the signaled state, the function chooses one of the objects to satisfy the wait; the states of the objects not selected are unaffected.

The WaitForMultipleObjects() function can specify handles of any of the following object types in the lpHandles array:

▪ Change notification.

▪ Console input.

▪ Event.

▪ Job.

▪ Memory resource notification.

▪ Mutex.

▪ Process.

▪ Semaphore.

▪ Thread.

▪ Waitable timer.

CloseHandle()

Item	Description
Function	CloseHandle().
Use	To close an open object handle.
Prototype	BOOL CloseHandle(HANDLE hObject);
Parameters	hObject [in, out] Handle to an open object.
Return value	See below.
Include file	<windows.h>
Remark	See below.
Table 5.

Return Values

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError().

Because pseudo-handle values are accepted as valid by GetCurrentHandle(), they (or -1) can be specified as the value of hObject. This function will throw an exception if either a handle value that is not valid (or 0) or pseudo-handle value is specified as the value of hObject and the application is running under a debugger. This includes closing a handle twice, and using CloseHandle() on a handle returned by the FindFirstFile() function. Note that this function will not throw an exception when a handle value that is not valid or pseudo-handle value is specified and the application is not running under a debugger.

Remarks

The CloseHandle() function closes handles to the following objects:

▪ Access token.

▪ Communications device.

▪ Console input.

▪ Console screen buffer.

▪ Event.

▪ File.

▪ File mapping.

▪ Job.

▪ Mailslot.

▪ Mutex.

▪ Named pipe.

▪ Process.

▪ Semaphore.

▪ Socket.

▪ Thread.

CloseHandle() invalidates the specified object handle, decrements the object's handle count, and performs object retention checks. After the last handle to an object is closed, the object is removed from the system.

Closing a thread handle does not terminate the associated thread. To remove a thread object, you must terminate the thread, then close all handles to the thread.

Use CloseHandle() to close handles returned by calls to the CreateFile() function. Use FindClose() to close handles returned by calls to FindFirstFile().

To use operating system resources efficiently, an application should close files when they are no longer needed by using the CloseHandle() function. If a file is open when an application terminates, the system closes it automatically. Note that closing a file does not delete the file from disk.

GetPriorityClass()

Item	Description
Function	GetPriorityClass().
Use	Retrieves the priority class for the specified process. This value, together with the priority value of each thread of the process, determines each thread's base priority level.
Prototype	DWORD GetPriorityClass(HANDLE hProcess);
Parameters	hProcess [in] Handle to the process. The handle must have the PROCESS_QUERY_INFORMATION access right.
Return value	See below.
Include file	<windows.h>
Remark	See below.
Table 6.

Return Values

If the function succeeds, the return value is the priority class of the specified process. If the function fails, the return value is zero. To get extended error information, call GetLastError(). The process's priority class is one of the following values.

Return code	Description
ABOVE_NORMAL_PRIORITY_CLASS	Process that has priority above NORMAL_PRIORITY_CLASS but below HIGH_PRIORITY_CLASS. Windows NT and Windows Me/98/95: This value is not supported.
BELOW_NORMAL_PRIORITY_CLASS	Process that has priority above IDLE_PRIORITY_CLASS but below NORMAL_PRIORITY_CLASS. For Windows NT and Windows Me/98/95: This value is not supported.
HIGH_PRIORITY_CLASS	Process that performs time-critical tasks that must be executed immediately for it to run correctly. The threads of a high-priority class process preempt the threads of normal or idle priority class processes. An example is the Task List, which must respond quickly when called by the user, regardless of the load on the operating system. Use extreme care when using the high-priority class, because a high-priority class CPU-bound application can use nearly all available cycles.
IDLE_PRIORITY_CLASS	Process whose threads run only when the system is idle and are preempted by the threads of any process running in a higher priority class. An example is a screen saver. The idle priority class is inherited by child processes.
NORMAL_PRIORITY_CLASS	Process with no special scheduling needs.
REALTIME_PRIORITY_CLASS	Process that has the highest possible priority. The threads of a real-time priority class process preempt the threads of all other processes, including operating system processes performing important tasks. For example, a real-time process that executes for more than a very brief interval can cause disk caches not to flush or cause the mouse to be unresponsive.
Table 7

Remarks

Every thread has a base priority level determined by the thread's priority value and the priority class of its process. The operating system uses the base priority level of all executable threads to determine which thread gets the next slice of CPU time. Threads are scheduled in a round-robin fashion at each priority level, and only when there are no executable threads at a higher level will scheduling of threads at a lower level take place.

Priority class is maintained by the executive, so all processes have a priority class that can be queried.

For Windows NT: Priority class is maintained by the Windows subsystem (csrss), so only Windows-based application have a priority class that can be queried.

SetPriorityClass()

Item	Description
Function	SetPriorityClass().
Use	Sets the priority class for the specified process. This value together with the priority value of each thread of the process determines each thread's base priority level.
Prototype	BOOL SetPriorityClass(HANDLE hProcess, DWORD dwPriorityClass);
Parameters	See below.
Return value	If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError().
Include file	<windows.h>
Remark	See below.
Table 8.

Parameters

hProcess

[in] Handle to the process.

The handle must have the PROCESS_SET_INFORMATION access right.

dwPriorityClass

[in] Priority class for the process. This parameter can be one of the following values.

Priority	Meaning
ABOVE_NORMAL_PRIORITY_CLASS	Process that has priority above NORMAL_PRIORITY_CLASS but below HIGH_PRIORITY_CLASS. Windows NT and Windows Me/98/95: This value is not supported.
BELOW_NORMAL_PRIORITY_CLASS	Process that has priority above IDLE_PRIORITY_CLASS but below NORMAL_PRIORITY_CLASS. Windows NT and Windows Me/98/95: This value is not supported.
HIGH_PRIORITY_CLASS	Process that performs time-critical tasks that must be executed immediately. The threads of the process preempt the threads of normal or idle priority class processes. An example is the Task List, which must respond quickly when called by the user, regardless of the load on the operating system. Use extreme care when using the high-priority class, because a high-priority class application can use nearly all available CPU time.
IDLE_PRIORITY_CLASS	Process whose threads run only when the system is idle. The threads of the process are preempted by the threads of any process running in a higher priority class. An example is a screen saver. The idle-priority class is inherited by child processes.
NORMAL_PRIORITY_CLASS	Process with no special scheduling needs.
REALTIME_PRIORITY_CLASS	Process that has the highest possible priority. The threads of the process preempt the threads of all other processes, including operating system processes performing important tasks. For example, a real-time process that executes for more than a very brief interval can cause disk caches not to flush or cause the mouse to be unresponsive.
Table 9

Remarks

Every thread has a base priority level determined by the thread's priority value and the priority class of its process. The system uses the base priority level of all executable threads to determine which thread gets the next slice of CPU time. The SetThreadPriority() function enables setting the base priority level of a thread relative to the priority class of its process.

CreateToolhelp32Snapshot()

Item	Description
Function	CreateToolhelp32Snapshot().
Use	To take a snapshot of the specified processes in the system, as well as the heaps, modules, and threads used by these processes.
Prototype	HANDLE WINAPI CreateToolhelp32Snapshot(DWORD dwFlags, DWORD th32ProcessID);
Parameters	See below.
Return value	If the function succeeds, it returns an open handle to the specified snapshot. If the function fails, it returns INVALID_HANDLE_VALUE. To get extended error information, call GetLastError().
Include file	<tlhelp32.h>
Remark	See below.
Table.

Parameters

dwFlags

[in] Portions of the system to include in the snapshot. This parameter can be one of the following values.

Value	Meaning
TH32CS_INHERIT	Indicates that the snapshot handle is to be inheritable.
TH32CS_SNAPALL	Includes all processes and threads in the system, plus the heaps and modules of the process specified in th32ProcessID. Equivalent to specifying the TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPPROCESS, and TH32CS_SNAPTHREAD values.
TH32CS_SNAPHEAPLIST	Includes all heaps of the process specified in th32ProcessID in the snapshot. To enumerate the heaps, see Heap32ListFirst().
TH32CS_SNAPMODULE	Includes all modules of the process specified in th32ProcessID in the snapshot. To enumerate the modules, see Module32First().
TH32CS_SNAPPROCESS	Includes all processes in the system in the snapshot. To enumerate the processes, see Process32First().
TH32CS_SNAPTHREAD	Includes all threads in the system in the snapshot. To enumerate the threads, see Thread32First(). To identify the threads that belong to a specific process, compare its process identifier to the th32OwnerProcessID member of the THREADENTRY32 structure when enumerating the threads.
Table 10

th32ProcessID

[in] Process identifier of the process to be included in the snapshot. This parameter can be zero to indicate the current process. This parameter is used when the TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, or TH32CS_SNAPALL value is specified. Otherwise, it is ignored and all processes are included in the snapshot.

Remarks

The snapshot taken by this function is examined by the other tool help functions to provide their results. Access to the snapshot is read only. The snapshot handle acts as an object handle and is subject to the same rules regarding which processes and threads it is valid in. To enumerate the heap or module states for all processes, specify TH32CS_SNAPALL and set th32ProcessID to zero. Then, for each additional process in the snapshot, call CreateToolhelp32Snapshot() again, specifying its process identifier and the TH32CS_SNAPHEAPLIST or TH32_SNAPMODULE value.

To destroy the snapshot, use the CloseHandle() function.

Process32First()

Item	Description
Function	Process32First().
Use	To retrieve information about the first process encountered in a system snapshot.
Prototype	BOOL WINAPI Process32First(HANDLE hSnapshot, LPPROCESSENTRY32 lppe);
Parameters	hSnapshot [in] Handle to the snapshot returned from a previous call to the CreateToolhelp32Snapshot() function. lppe [in, out] Pointer to a PROCESSENTRY32 structure. It contains process information such as the name of the executable file, the process identifier, and the process identifier of the parent process.
Return value	Returns TRUE if the first entry of the process list has been copied to the buffer or FALSE otherwise. The ERROR_NO_MORE_FILES error value is returned by the GetLastError() function if no processes exist or the snapshot does not contain process information.
Include file	<tlhelp32.h>
Remark