Win32 API Reference
Documentation Home API Index Search

SuspendThread

Suspends a thread. (Process and Thread Functions)

Function Declaration

DWORD SuspendThread(
    HANDLE hThread
);

Parameters

Parameter Type and Description
hThread A handle to the thread to be suspended.
The handle must have the THREAD_SUSPEND_RESUME access right.
For more information, see Thread Security and Access Rights.

Return Value

If the function succeeds, the return value is the thread's previous suspend count.
If the function fails, the return value is (DWORD) 0xFFFFFFFF. To get extended error information, call GetLastError.

Remarks

A thread is suspended when its suspend count is greater than zero. A suspended thread cannot enter the executable state.

The system increments a thread's suspend count each time SuspendThread is called for that thread. The system decrements the suspend count each time ResumeThread is called for that thread.

A thread cannot execute code or enter the ready state if its suspend count is greater than zero. If a thread's suspend count is greater than one, it must be resumed that many times before it can execute code.

It is generally recommended that you use synchronization primitives such as events or mutexes instead of SuspendThread to control thread execution. This is because a thread that is suspended by SuspendThread might not be able to execute critical cleanup code in its exception handlers.

The SuspendThread function can cause a deadlock. For example, if a thread tries to suspend a thread that is waiting for a resource that the calling thread owns, the system will deadlock.

A thread can suspend itself by calling SuspendThread with its own thread handle. This is often done to synchronize with other threads or to perform operations that require the thread to be in a suspended state.

If the specified thread is currently executing, SuspendThread will not return until the thread has been suspended. This means that if the thread is executing a long operation, SuspendThread may block for a significant amount of time.

Example

#include <windows.h>
#include <iostream>

int main() {
    HANDLE hThread = NULL;
    DWORD dwThreadId = 0;

    // Assume hThread is a valid handle to a thread that you want to suspend.
    // For demonstration, let's assume we have a thread already running.
    // In a real scenario, you would get this handle via CreateThread or OpenThread.

    // Example: Creating a dummy thread to suspend (not fully functional here)
    auto thread_func = []() {
        // This thread would do some work
        Sleep(INFINITE);
    };
    hThread = CreateThread(
        NULL,       // default security attributes
        0,          // default stack size
        (LPTHREAD_START_ROUTINE)thread_func, // thread function
        NULL,       // parameter for thread function
        0,          // default creation flags
        &dwThreadId); // returns the thread identifier

    if (hThread == NULL) {
        std::cerr << "Failed to create thread. Error: " << GetLastError() << std::endl;
        return 1;
    }

    std::cout << "Thread created. Suspending thread..." << std::endl;

    DWORD dwPreviousSuspendCount = SuspendThread(hThread);

    if (dwPreviousSuspendCount == (DWORD)0xFFFFFFFF) {
        std::cerr << "Failed to suspend thread. Error: " << GetLastError() << std::endl;
        CloseHandle(hThread);
        return 1;
    }

    std::cout << "Thread suspended. Previous suspend count: " << dwPreviousSuspendCount << std::endl;

    // The thread is now suspended. You can perform other operations.
    // For demonstration, we'll resume it immediately.

    std::cout << "Resuming thread..." << std::endl;
    DWORD dwResumeCount = ResumeThread(hThread);

    if (dwResumeCount == (DWORD)0xFFFFFFFF) {
        std::cerr << "Failed to resume thread. Error: " << GetLastError() << std::endl;
    } else {
        std::cout << "Thread resumed. Previous suspend count for resume: " << dwResumeCount << std::endl;
    }

    CloseHandle(hThread); // Close the thread handle

    return 0;
}

See Also