Windows API Reference

Topics

Key Functions

Process and Thread Management

This section provides comprehensive documentation on managing processes and threads within the Windows operating system using the Win32 API. Understanding these concepts is crucial for developing efficient, robust, and responsive applications.

Introduction

A process is an instance of a running program. It contains the program code, data, and its own address space. Each process has at least one thread of execution.

A thread is the basic unit of CPU utilization; it’s a sequence of instructions within a process that can be executed independently. Threads share the process's resources, such as memory and open files.

Processes

Processes provide an environment for threads to execute. They offer memory isolation, preventing one process from interfering with another's data. Key aspects of process management include creation, termination, and querying process information.

Core Process Creation Function: CreateProcess

The CreateProcess function creates a new process and its primary thread. It allows for detailed control over the new process's environment, including the working directory, security attributes, and startup information.

BOOL CreateProcess(
  LPCTSTR               lpApplicationName,
  LPTSTR                lpCommandLine,
  LPSECURITY_ATTRIBUTES lpProcessAttributes,
  LPSECURITY_ATTRIBUTES lpThreadAttributes,
  BOOL                  bInheritHandles,
  DWORD                 dwCreationFlags,
  LPVOID                lpEnvironment,
  LPCTSTR               lpCurrentDirectory,
  LPSTARTUPINFO         lpStartupInfo,
  LPPROCESS_INFORMATION lpProcessInformation
);

There are also ANSI (CreateProcessA) and Unicode (CreateProcessW) versions of this function. It's generally recommended to use the Unicode version (CreateProcessW) for modern Windows development.

Terminating a Process: ExitProcess

ExitProcess terminates the calling process and all of its threads.

VOID ExitProcess(UINT uExitCode);

Other Important Process Functions:

  • CreateProcessAsUserW: Creates a process associated with the user account specified by the token.
  • CreateProcessWithTokenW: Creates a process and its primary thread. The new process uses the specified access token.
  • OpenProcess: Opens an existing local process object.
  • GetCurrentProcess: Retrieves a pseudo-handle for the current process.
  • GetCurrentProcessId: Retrieves the identifier of the current process.
  • CreateJobObject: Creates a job object. A job object can be used to manage a group of processes.

Threads

Threads are the units of execution within a process. They allow a single application to perform multiple tasks concurrently, improving responsiveness and performance.

Core Thread Creation Function: CreateThread

CreateThread creates a new thread to execute within the virtual address space of the calling process.

HANDLE CreateThread(
  LPSECURITY_ATTRIBUTES lpThreadAttributes,
  SIZE_T                dwStackSize,
  LPTHREAD_START_ROUTINE lpStartAddress,
  LPVOID                lpParameter,
  DWORD                 dwCreationFlags,
  LPDWORD               lpThreadId
);

Terminating a Thread: ExitThread

ExitThread terminates the calling thread and provides an exit code for the thread.

VOID ExitThread(DWORD dwExitCode);

Other Important Thread Functions:

  • OpenThread: Opens an existing thread object.
  • GetCurrentThread: Retrieves a pseudo-handle for the current thread.
  • GetCurrentThreadId: Retrieves the identifier of the current thread.
  • Sleep: Suspends the current thread for a specified interval.

Scheduling

Windows uses a preemptive multitasking scheduler to manage CPU time for threads. You can influence thread scheduling using priority levels and affinity settings.

  • SetThreadPriority: Sets the priority of the specified thread.
  • GetThreadPriority: Retrieves the priority of the specified thread.
  • SetThreadAffinityMask: Sets the processor affinity mask of the specified thread.

Synchronization

When multiple threads access shared resources, synchronization mechanisms are essential to prevent race conditions and data corruption.

Synchronization Primitives:

  • CreateMutex: Creates or opens a mutex object. Mutexes provide exclusive access to a resource.
  • ReleaseMutex: Releases ownership of a mutex object.
  • CreateSemaphore: Creates a semaphore object. Semaphores limit the number of threads that can access a resource concurrently.
  • ReleaseSemaphore: Increments the count of a semaphore object, potentially releasing waiting threads.
  • CreateEvent: Creates a named or unnamed event object. Events are signaling mechanisms used to notify threads of specific occurrences.
  • SetEvent: Sets the specified event object to the signaled state.
  • ResetEvent: Sets the specified event object to the non-signaled state.
  • PulseEvent: Sets a specified event object to the signaled state, releasing all threads that are waiting for the event object to be set.
  • CreateCriticalSection: Initializes a critical-section object. Critical sections provide mutually exclusive access to a resource.
  • EnterCriticalSection: Waits to acquire ownership of a critical section.
  • LeaveCriticalSection: Releases ownership of a critical section.

Waiting for Objects: WaitForSingleObject

WaitForSingleObject waits until the specified object is in the signaled state or the time-out interval elapses.

DWORD WaitForSingleObject(
  HANDLE hHandle,
  DWORD  dwMilliseconds
);

WaitForSingleObjectEx provides more control over alertable waits.

Interprocess Communication (IPC)

While threads share memory, processes typically communicate using IPC mechanisms.

Common IPC Mechanisms:

  • Pipes (Anonymous and Named Pipes)
  • Memory-Mapped Files
  • Sockets (including Winsock)
  • COM (Component Object Model)
  • Windows Messages

This section serves as a starting point. Refer to individual function documentation for detailed parameter descriptions, return values, and usage examples.