[Copilot] Add wil::batched_range and wil::already_complete / already_failed C++/WinRT helpers

[Jon Wiswall (jonwis)]

What this adds

Two C++/WinRT helpers in wil/cppwinrt_helpers.h, spun out of the review discussion on microsoft/cppwinrt#1608 — C++/WinRT stays projection-only, so these interop conveniences live in WIL. Resolves #663 and #664.

wil::already_complete / wil::already_failed (#663)

Return an IAsyncAction / IAsyncOperation<T> that is already settled, with no coroutine frame — co_await, .get(), and a Completed handler all complete synchronously.

IAsyncOperation<int32_t> GetCachedValue()
{
    if (m_haveValue)
        return wil::already_complete(m_value);   // no coroutine frame for the already-known answer
    return ComputeValueAsync();
}

wil::already_complete();          // completed IAsyncAction
wil::already_failed(hr);          // faulted IAsyncAction, GetResults() throws hr
wil::already_failed<T>(hr);       // faulted IAsyncOperation<T>

A single winrt::implements object over the async interface + IAsyncInfo; Completed is fired inline with a single-assignment guard (throws hresult_illegal_delegate_assignment on a second set), no mutex — the compact shape from Raymond Chen's "already-completed asynchronous activity" series. The result storage is null-initialized for projected object types so the faulted path never activates (or requires a default constructor for) a runtimeclass result.

wil::batched_range (#664)

A range-for adapter that prefetches elements in blocks via GetMany instead of one ABI round-trip per element. On a cross-process or heavily-marshaled collection the per-element crossings dominate, so batching cuts them to roughly one per block.

for (winrt::hstring const& item : wil::batched_range(collection))
    use(item);

Works for IVector<T>, IVectorView<T>, IIterable<T>, IIterator<T>, and anything C++/WinRT projects those for (PropertySet, IMap<K,V>, …). Indexed collections prefetch with GetMany(index, …); iterable-only collections buffer through IIterator::GetMany. It's a single-pass input range — a yielded element outlives the step that produced it, matching the observable behavior of wil::to_vector. Block prefetch stops once GetMany returns a short block. Both shapes share one input iterator that differs only in how a block is refilled.

Testing

New coverage in tests/CppWinRTTests.cpp: already_complete/already_failed completed/faulted status, co_await and .get(), inline Completed firing, double-assignment throwing, a runtimeclass (Uri) result on the faulted path, and non-trivial result round-trip; batched_range across the indexed and iterable paths, map/IKeyValuePair, exact block-boundary multiples (1/127/128/129/256/257) for ordering and clean termination, empty collections, duck-typed non-WinRT shapes, and an iterator advanced past its start yielding only the remainder. Built clean across clang and MSVC (debug + relwithdebinfo); full [cppwinrt] suite passes.

References

• C++/WinRT ABI interop improvements cppwinrt#1608
• Raymond Chen, "Creating an already-completed asynchronous activity in C++/WinRT" (parts 1–9)

(via Copilot)