Add gather helper functions

[tzoiker]

Adding several helper functions:

async def gather(
    *tocs: Optional[ToC],
    loop: Optional[AbstractEventLoop] = None,
    return_exceptions: bool = False,
)

Same as asyncio.gather but it is possible to safely pass Nones through.

gather_shackled(
    *tocs: Optional[ToC],
    wait_cancelled: bool = False,
) -> list

If any of the tasks fails – others are cancelled. Allows to wait for the completion of the cancelled tasks. Returns a list of values or raises the first exception.

async def gather_independent(
    *tocs: Optional[ToC],
    wait_cancelled: bool = False,
) -> list

If any of the tasks fails – it is ok. Allows to wait for the completion of the cancelled tasks in the case of external cancellation. Returns a list of values or exceptions.

async def gather_graceful(
    primary: Optional[Sequence[Optional[ToC]]] = None, *,
    secondary: Sequence[Optional[ToC]] = None,
    wait_cancelled: bool = False,
) -> Union[list, Tuple[list, list]]

Gather tasks in two groups - primary and secondary. If any primary is somehow failed, then, other tasks are cancelled. If secondary is failed – it is ok. If any primary is failed, then, will raise the first exception. Returns two lists of results, one for the primary tasks (only values) and the other for the secondary tasks (values or exceptions). If only primary or secondary is passed, then, returns a single list.

async def wait_graceful(
    primary: Optional[Iterable[Task]] = None,
    secondary: Optional[Iterable[Task]] = None,
    *,
    wait_cancelled: bool = False,
)

Main logic is the same as for gather_graceful.

async def wait_first_cancelled_or_exception(
    fs: Iterable[Future], *,
    loop: Optional[AbstractEventLoop] = None,
    timeout: float = None,
)

Similar to asyncio.wait, but particularly waits for the first cancelled or failed task.