Add a simple API for getting the first available result from a sequence of Deferreds

[exarkun]

It is common to want to try a few things concurrently but only care about whichever of them completes successfully first.

One example of when this kind of thing is useful is when implementing "happy eyeballs". You want to let N operations run concurrently (some of them might just start with a delay). As soon as any one finishes you want to use its result and you have no use for any of the other results.

DeferredList(deferredList, fireOnOnecallback=True) is a little bit like this API except:

• It is class-based which encourages the misunderstanding that subclassing Deferred is a good idea.
• It mixes around 8 different APIs together in one, controlled by a confusing mix of flags.
• It doesn't cancel the Deferreds that didn't finish first.

Describe the solution you'd like

An API dedicated to this use-case might look something like:

X = TypeVar("X")
Y = TypeVar("Y")
def race(ds: Sequence[Deferred[X]]) -> Deferred[tuple[int, X]]:
    """
    Select the first available result from the sequence of Deferreds and
    cancel the rest.

    :return: A cancellable ``Deferred`` that fires with the index and output
        of the element of ``ds`` to first have a success result, or that fires
        with a failure holding a list of their failures if they all fail.
    """