[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)

[Duncan Horn (dunhor)]

Primary concern I have is that the iterator type holds the array storage, which is alarming for two reasons:

1. The end iterator also holds this storage, since it is the same type, even though it'll never be used
2. Iterators in the STL and STL-like algorithms pass iterators by value most of the time as they are assumed to be cheap to copy. In the worst case, a single algorithm function may delegate to other functions, passing iterators by value, in a loop.

(1) should be addressable by changing to a sentinel type for the end iterator, which should at least be okay in C++20 and beyond b/c of ranges. I did a quick test and it seemed to also work when targeting C++17.

(2) is more alarming, however maybe we just say that this type should only ever be used for loops. Personally, I'm not super thrilled with that limitation, but should we choose to go that route, we may want to at least delete the copy constructor and remove all of the iterator_traits types so that STL algorithms will reject the call.

Alternatively, it might be worth sticking the storage into the range adapter type and just have the iterators reference back to that object instead.

[Duncan Horn (dunhor)]

Curious about the choice of 128 since it' not documented here. Is it just "collections are rarely this big"?

The comment says this "aims" for 2 KiB blocks, however 128 pointers - which is probably the typical case - is 1 KiB

[Duncan Horn (dunhor)]

So, the end iterator also holds a potentially large array? 😬. One possible option would be to use a separate sentinel type, however these types would no longer be usable with the old STL algorithms (but would work with the ranges library).

Similarly, this would also be problematic when calling STL or STL-like algorithms, which take iterator arguments by value as iterators are typically assumed to be cheap to copy.

[Duncan Horn (dunhor)]

Input iterators require *it++ to be well formed and be equivalent to:

auto __val = *it;
++it;

This type only provides pre-increment and therefore can potentially fail to compile, e.g. when calling STL algorithms. Adding pre-increment is probably not the right call since a copy of this iterator type is such a heavy operation (another property that's very unusual for iterators).

[Duncan Horn (dunhor)]

Some asserts would be nice. E.g. WI_ASSERT(m_index < m_size)

[Duncan Horn (dunhor)]

This would break self-equality (i.e. a == a) for non-end iterators. Probably never an issue in practice (realistically someone would be comparing copies) especially given that this is an input iterator, but is enough to cause a feeling of uneasiness.

[Duncan Horn (dunhor)]

nit: this is a WinRT contract, not a coroutine contract

[Duncan Horn (dunhor)]

It's been a while since I used C++/WinRT extensively, so this might be wrong, but this appears to be:

1. Performing an AddRef on the derived object, and then
2. Performing a QueryInterface on the derived object

I can see an argument for increasing the reference count once (the caller may free its only reference in the callback), but two sems unnecessary.

[Duncan Horn (dunhor)]

std::exchange is not an atomic operation. In practice that's probably fine, especially since this type doesn't store the object, but another place that gives the feeling of uneasiness.

[Duncan Horn (dunhor)]

Perhaps invert the two? Define empty<T> here and have the collections code use this definition.

[Duncan Horn (dunhor)]

Maybe I'm just being dumb, but is there a reason these derive from the completed handler delegate types?

[Charles Milette (sylveon)]

FWIW (2) is why I didn't like the idea of making it the default for cppwinrt as was initially intended, and instead wanted to port it to a separate type.