Document Structured Concurrency violating functions

[weissi]

Description

At the moment, the generator generates functions that violate Structured Concurrency, for example anything that uses HTTP response streaming. The user gets returned an async sequence that they are then supposed to stream and until that's done resources in other tasks/threads are still holding onto the live request.

This is of course violates the main principle of Structured Concurrency which is that upon return of a function, the execution resources it acquired have been released back.

Violating Structured Concurrency might be acceptable in certain cases but:

1. It should be documented that what's going on [this bug report]
2. An alternative should be offered (such as try await withFooRequest(parameters: Parameters) { result, responseBodyStream in ... }) [Offer Structured Concurrency conforming APIs for response streaming #728]

This bug report is squarely about (1), the documentation that certain APIs (namely anything that does HTTP response streaming) violates Structured Concurrency.

Similar efforts in other projects:

• document known Structured Concurrency violations swift-nio#3108
• baby steps towards a Structured Concurrency API swift-server/async-http-client#806
• offer Structured Concurrency API that supports HTTP response streaming swift-server/async-http-client#807

Reproduction

n/a

Package version(s)

all

Expected behavior

docs

Environment

n/a

Additional information

No response