如何：使用 WRL 完成异步操作

项目
04/03/2023

本文档演示如何使用 Windows 运行时 C++ 模板库 (WRL) 启动异步操作并在操作完成时执行工作。

本文档演示了两个示例。第一个示例启动异步计时器，并等待计时器过期。在此示例中，在创建计时器对象时指定异步操作。第二个示例运行后台工作线程。此示例演示如何使用返回 IAsyncInfo 接口的 Windows 运行时方法。 Callback 函数是这两个示例的重要组成部分，因为两个示例可以通过该函数指定事件处理程序来处理异步操作的结果。

有关创建该组件的实例并检索属性值的更基本示例，请参阅如何：激活和使用 Windows 运行时组件。

提示

这些示例使用 Lambda 表达式来定义回调。还可以使用函数对象（函子）、函数指针或 std::function 对象。若要详细了解 Lambda 表达式，请参阅 Lambda 表达式。

示例：使用计时器

以下步骤启动异步计时器并等待计时器过期。之后提供了完整示例。

警告

尽管通常在通用 Windows 平台 (UWP) 应用中使用 Windows 运行时 C++ 模板库，但此示例使用控制台应用进行演示。 UWP 应用不提供 wprintf_s 等函数。若要详细了解可在 UWP 应用中使用的类型和函数，请参阅通用 Windows 平台应用中不支持的 CRT 函数和适用于 UWP 应用的 Win32 和 COM。

包括 (#include) 任何所需的 Windows 运行时、Windows 运行时 C++ 模板库或 C++ 标准库标头。

#include <Windows.Foundation.h>
#include <Windows.System.Threading.h>
#include <wrl/event.h>
#include <stdio.h>
#include <Objbase.h>

using namespace ABI::Windows::Foundation;
using namespace ABI::Windows::System::Threading;
using namespace Microsoft::WRL;
using namespace Microsoft::WRL::Wrappers;

Windows.System.Threading.h 声明使用异步计时器所需的类型。

我们建议您在 .cpp 文件中使用 using namespace 指令使代码更具可读性。

初始化 Windows 运行时。

// Initialize the Windows Runtime.
RoInitializeWrapper initialize(RO_INIT_MULTITHREADED);
if (FAILED(initialize))
{
    return PrintError(__LINE__, initialize);
}

为 ABI::Windows::System::Threading::IThreadPoolTimer 接口创建激活工厂。

// Get the activation factory for the IThreadPoolTimer interface.
ComPtr<IThreadPoolTimerStatics> timerFactory;
HRESULT hr = GetActivationFactory(HStringReference(RuntimeClass_Windows_System_Threading_ThreadPoolTimer).Get(), &timerFactory);
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}

Windows 运行时使用完全限定名来标识类型。 RuntimeClass_Windows_System_Threading_ThreadPoolTimer 参数是 Windows 运行时提供的字符串，其中包含所需的运行时类名称。

创建一个将计时器回调同步到主应用的 Event 对象。

// Create an event that is set after the timer callback completes. We later use this event to wait for the timer to complete. 
// This event is for demonstration only in a console app. In most apps, you typically don't wait for async operations to complete.
Event timerCompleted(CreateEventEx(nullptr, nullptr, CREATE_EVENT_MANUAL_RESET, WRITE_OWNER | EVENT_ALL_ACCESS));
hr = timerCompleted.IsValid() ? S_OK : HRESULT_FROM_WIN32(GetLastError());
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}

注意

此事件仅作为控制台应用的一部分进行演示。此示例使用该事件确保退出应用之前完成异步操作。在大多数应用中，你通常不会等待异步操作完成。

创建一个在两秒后过期的 IThreadPoolTimer 对象。使用 Callback 函数创建事件处理程序（ABI::Windows::System::Threading::ITimerElapsedHandler 对象）。

// Create a timer that prints a message after 2 seconds.

TimeSpan delay;
delay.Duration = 20000000; // 2 seconds.

auto callback = Callback<ITimerElapsedHandler>([&timerCompleted](IThreadPoolTimer* timer) -> HRESULT
{
    wprintf_s(L"Timer fired.\n");

    TimeSpan delay;
    HRESULT hr = timer->get_Delay(&delay);
    if (SUCCEEDED(hr))
    {
        wprintf_s(L"Timer duration: %2.2f seconds.\n", delay.Duration / 10000000.0);
    }

    // Set the completion event and return.
    SetEvent(timerCompleted.Get());
    return hr;
});
hr = callback ? S_OK : E_OUTOFMEMORY;
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}

ComPtr<IThreadPoolTimer> timer;
hr = timerFactory->CreateTimer(callback.Get(), delay, &timer);
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}

将消息输出到控制台，并等待计时器回调完成。所有 ComPtr 和 RAII 对象都离开范围并自动释放。

// Print a message and wait for the timer callback to complete.
wprintf_s(L"Timer started.\nWaiting for timer...\n");

// Wait for the timer to complete.
WaitForSingleObjectEx(timerCompleted.Get(), INFINITE, FALSE);
// All smart pointers and RAII objects go out of scope here.

以下是完整示例：

// wrl-consume-async.cpp
// compile with: runtimeobject.lib
#include <Windows.Foundation.h>
#include <Windows.System.Threading.h>
#include <wrl/event.h>
#include <stdio.h>
#include <Objbase.h>

using namespace ABI::Windows::Foundation;
using namespace ABI::Windows::System::Threading;
using namespace Microsoft::WRL;
using namespace Microsoft::WRL::Wrappers;

// Prints an error string for the provided source code line and HRESULT
// value and returns the HRESULT value as an int.
int PrintError(unsigned int line, HRESULT hr)
{
    wprintf_s(L"ERROR: Line:%d HRESULT: 0x%X\n", line, hr);
    return hr;
}

int wmain()
{
    // Initialize the Windows Runtime.
    RoInitializeWrapper initialize(RO_INIT_MULTITHREADED);
    if (FAILED(initialize))
    {
        return PrintError(__LINE__, initialize);
    }

    // Get the activation factory for the IThreadPoolTimer interface.
    ComPtr<IThreadPoolTimerStatics> timerFactory;
    HRESULT hr = GetActivationFactory(HStringReference(RuntimeClass_Windows_System_Threading_ThreadPoolTimer).Get(), &timerFactory);
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    // Create an event that is set after the timer callback completes. We later use this event to wait for the timer to complete. 
    // This event is for demonstration only in a console app. In most apps, you typically don't wait for async operations to complete.
    Event timerCompleted(CreateEventEx(nullptr, nullptr, CREATE_EVENT_MANUAL_RESET, WRITE_OWNER | EVENT_ALL_ACCESS));
    hr = timerCompleted.IsValid() ? S_OK : HRESULT_FROM_WIN32(GetLastError());
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    // Create a timer that prints a message after 2 seconds.

    TimeSpan delay;
    delay.Duration = 20000000; // 2 seconds.

    auto callback = Callback<ITimerElapsedHandler>([&timerCompleted](IThreadPoolTimer* timer) -> HRESULT
    {
        wprintf_s(L"Timer fired.\n");

        TimeSpan delay;
        HRESULT hr = timer->get_Delay(&delay);
        if (SUCCEEDED(hr))
        {
            wprintf_s(L"Timer duration: %2.2f seconds.\n", delay.Duration / 10000000.0);
        }

        // Set the completion event and return.
        SetEvent(timerCompleted.Get());
        return hr;
    });
    hr = callback ? S_OK : E_OUTOFMEMORY;
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    ComPtr<IThreadPoolTimer> timer;
    hr = timerFactory->CreateTimer(callback.Get(), delay, &timer);
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    // Print a message and wait for the timer callback to complete.
    wprintf_s(L"Timer started.\nWaiting for timer...\n");

    // Wait for the timer to complete.
    WaitForSingleObjectEx(timerCompleted.Get(), INFINITE, FALSE);
    // All smart pointers and RAII objects go out of scope here.
}
/*
Output:
Timer started.
Waiting for timer...
Timer fired.
Timer duration: 2.00 seconds.
*/

编译代码

若要编译代码，请复制代码并将其粘贴到 Visual Studio 项目中，或粘贴到一个名为 wrl-consume-async.cpp 的文件中，然后在 Visual Studio 命令提示符窗口中运行以下命令。

cl.exe wrl-consume-async.cpp runtimeobject.lib

示例：使用后台线程

以下步骤启动工作线程并定义该线程执行的操作。之后提供了完整示例。

提示

此示例演示如何使用 ABI::Windows::Foundation::IAsyncAction 接口。可以将此模式应用于实现 IAsyncInfo 的任何接口：IAsyncAction、IAsyncActionWithProgress、IAsyncOperation 和 IAsyncOperationWithProgress。

包括 (#include) 任何所需的 Windows 运行时、Windows 运行时 C++ 模板库或 C++ 标准库标头。

#include <Windows.Foundation.h>
#include <Windows.System.Threading.h>
#include <wrl/event.h>
#include <stdio.h>
#include <Objbase.h>

using namespace ABI::Windows::Foundation;
using namespace ABI::Windows::System::Threading;
using namespace Microsoft::WRL;
using namespace Microsoft::WRL::Wrappers;

Windows.System.Threading.h 声明使用工作线程所需的类型。

建议在 .cpp 文件中使用 using namespace 指令使代码更具可读性。

初始化 Windows 运行时。

// Initialize the Windows Runtime.
RoInitializeWrapper initialize(RO_INIT_MULTITHREADED);
if (FAILED(initialize))
{
    return PrintError(__LINE__, initialize);
}

为 ABI::Windows::System::Threading::IThreadPoolStatics 接口创建激活工厂。

// Get the activation factory for the IThreadPoolStatics interface.
ComPtr<IThreadPoolStatics> threadPool;
HRESULT hr = GetActivationFactory(HStringReference(RuntimeClass_Windows_System_Threading_ThreadPool).Get(), &threadPool);
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}

创建一个将工作线程的完成情况同步到主应用的 Event 对象。

// Create an event that is set after the timer callback completes. We later use this event to wait for the timer to complete. 
// This event is for demonstration only in a console app. In most apps, you typically don't wait for async operations to complete.
Event threadCompleted(CreateEventEx(nullptr, nullptr, CREATE_EVENT_MANUAL_RESET, WRITE_OWNER | EVENT_ALL_ACCESS));
hr = threadCompleted.IsValid() ? S_OK : HRESULT_FROM_WIN32(GetLastError());
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}

注意

此事件仅作为控制台应用的一部分进行演示。此示例使用该事件确保退出应用之前完成异步操作。在大多数应用中，你通常不会等待异步操作完成。

调用 IThreadPoolStatics::RunAsync 方法以创建工作线程。使用 Callback 函数定义操作。

wprintf_s(L"Starting thread...\n");

// Create a thread that computes prime numbers.
ComPtr<IAsyncAction> asyncAction;
hr = threadPool->RunAsync(Callback<IWorkItemHandler>([&threadCompleted](IAsyncAction* asyncAction) -> HRESULT
{
    // Print a message.
    const unsigned int start = 0;
    const unsigned int end = 100000;
    unsigned int primeCount = 0;
    for (int n = start; n < end; n++)
    {
        if (IsPrime(n))
        {
            primeCount++;
        }
    }

    wprintf_s(L"There are %u prime numbers from %u to %u.\n", primeCount, start, end);

    // Set the completion event and return.
    SetEvent(threadCompleted.Get());
    return S_OK;

}).Get(), &asyncAction);
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}

IsPrime 函数在下面的完整示例中定义。

将消息输出到控制台，并等待线程完成。所有 ComPtr 和 RAII 对象都离开范围并自动释放。

// Print a message and wait for the thread to complete.
wprintf_s(L"Waiting for thread...\n");

// Wait for the thread to complete.
WaitForSingleObjectEx(threadCompleted.Get(), INFINITE, FALSE);

wprintf_s(L"Finished.\n");

// All smart pointers and RAII objects go out of scope here.

以下是完整示例：

// wrl-consume-asyncOp.cpp
// compile with: runtimeobject.lib 
#include <Windows.Foundation.h>
#include <Windows.System.Threading.h>
#include <wrl/event.h>
#include <stdio.h>
#include <Objbase.h>

using namespace ABI::Windows::Foundation;
using namespace ABI::Windows::System::Threading;
using namespace Microsoft::WRL;
using namespace Microsoft::WRL::Wrappers;

// Prints an error string for the provided source code line and HRESULT
// value and returns the HRESULT value as an int.
int PrintError(unsigned int line, HRESULT hr)
{
    wprintf_s(L"ERROR: Line:%d HRESULT: 0x%X\n", line, hr);
    return hr;
}

// Determines whether the input value is prime.
bool IsPrime(int n)
{
    if (n < 2)
    {
        return false;
    }
    for (int i = 2; i < n; ++i)
    {
        if ((n % i) == 0)
        {
            return false;
        }
    }
    return true;
}

int wmain()
{
    // Initialize the Windows Runtime.
    RoInitializeWrapper initialize(RO_INIT_MULTITHREADED);
    if (FAILED(initialize))
    {
        return PrintError(__LINE__, initialize);
    }

    // Get the activation factory for the IThreadPoolStatics interface.
    ComPtr<IThreadPoolStatics> threadPool;
    HRESULT hr = GetActivationFactory(HStringReference(RuntimeClass_Windows_System_Threading_ThreadPool).Get(), &threadPool);
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    // Create an event that is set after the timer callback completes. We later use this event to wait for the timer to complete. 
    // This event is for demonstration only in a console app. In most apps, you typically don't wait for async operations to complete.
    Event threadCompleted(CreateEventEx(nullptr, nullptr, CREATE_EVENT_MANUAL_RESET, WRITE_OWNER | EVENT_ALL_ACCESS));
    hr = threadCompleted.IsValid() ? S_OK : HRESULT_FROM_WIN32(GetLastError());
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }


    wprintf_s(L"Starting thread...\n");

    // Create a thread that computes prime numbers.
    ComPtr<IAsyncAction> asyncAction;
    hr = threadPool->RunAsync(Callback<IWorkItemHandler>([&threadCompleted](IAsyncAction* asyncAction) -> HRESULT
    {
        // Print a message.
        const unsigned int start = 0;
        const unsigned int end = 100000;
        unsigned int primeCount = 0;
        for (int n = start; n < end; n++)
        {
            if (IsPrime(n))
            {
                primeCount++;
            }
        }

        wprintf_s(L"There are %u prime numbers from %u to %u.\n", primeCount, start, end);

        // Set the completion event and return.
        SetEvent(threadCompleted.Get());
        return S_OK;

    }).Get(), &asyncAction);
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    // Print a message and wait for the thread to complete.
    wprintf_s(L"Waiting for thread...\n");

    // Wait for the thread to complete.
    WaitForSingleObjectEx(threadCompleted.Get(), INFINITE, FALSE);

    wprintf_s(L"Finished.\n");

    // All smart pointers and RAII objects go out of scope here.
}
/*
Output:
Starting thread...
Waiting for thread...
There are 9592 prime numbers from 0 to 100000.
Finished.
*/

编译代码

若要编译代码，请复制代码并将其粘贴到 Visual Studio 项目中，或粘贴到一个名为 wrl-consume-asyncOp.cpp 的文件中，然后在 Visual Studio 命令提示符窗口中运行以下命令。

cl.exe wrl-consume-asyncOp.cpp runtimeobject.lib

另请参阅

Windows 运行时 C++ 模板库 (WRL)

通过

如何：使用 WRL 完成异步操作

示例：使用计时器

编译代码

示例：使用后台线程

编译代码

另请参阅

反馈

其他资源