Add narrative documentation for NIO's concurrency bridges #2423
Conversation
FranzBusch
force-pushed
the
fb-concurrency-narritve-doc
branch
from
8934b25 to
9e1069c
Compare
# Motivation We started to add bridges from NIO to Swift Concurrency and we should provide some narrative documentation for our users how to adopt them. # Modification Adds a new article that explains the NIO concurrency bridges.
FranzBusch
force-pushed
the
fb-concurrency-narritve-doc
branch
from
9e1069c to
f3e0aaf
Compare
| to close the channel once both the reading and the writing have finished. | ||
|
|
||
|
|
||
| This is how you can wrap an existing channel into a `NIOAsyncChannel`, consume the inbound data and |
There was a problem hiding this comment.
We cannot use the symbol link yet because we still use spi for the symbols
| The first bridges, that NIO introduced were adding methods on ``EventLoopFuture`` and ``EventLoopPromise`` | ||
| to bridge to and from Concurrency. Namely these bridges are ``EventLoopFuture/get()`` and ``EventLoopPromise/completeWithTask(_:)``. | ||
|
|
||
| > Warning: The future ``EventLoopFuture/get()`` method does not support task cancellation. |
There was a problem hiding this comment.
| > Warning: The future ``EventLoopFuture/get()`` method does not support task cancellation. | |
| > Warning: ``EventLoopFuture/get()`` does not support task cancellation. |
There was a problem hiding this comment.
I did add the words around because docc renders this as just get() which reads very weird.
There was a problem hiding this comment.
Ah I see. Okay, then it's fine - with the word future though, did you mean ELF?
|
@gjcairo @Lukasa @glbrntt Thanks for the great feedback. I fixed all the nits and rearranged some sections to have a better story line. I also added a general guidance section in the end. Right now that only contains guidance around business logic vs protocol logic but we can extend it in the future with guidance around perf as well |
|
|
||
| #### Where should your code live? | ||
|
|
||
| Before the introduction of Swift Concurrency both, implementations of network protocols and business logic, |
There was a problem hiding this comment.
| Before the introduction of Swift Concurrency both, implementations of network protocols and business logic, | |
| Before the introduction of Swift Concurrency, both implementations of network protocols and business logic |
| try await withThrowingDiscardingTaskGroup { group in | ||
| for try await negotiationResult in serverChannel.inboundStream { | ||
| group.addTask { | ||
| do { |
There was a problem hiding this comment.
Is there a catch missing or why do we use do here?
There was a problem hiding this comment.
Good catch! Pun intended
| protocolNegotiationHandlerType: NIOTypedApplicationProtocolNegotiationHandler<NegotiationResult>.self | ||
| ) | ||
|
|
||
| try await withThrowingDiscardingTaskGroup { group in |
There was a problem hiding this comment.
Is it worth mentioning withThrowingDiscardingTaskGroup is not available in macOS version of Swift 5.8, but is available in Linux?
There was a problem hiding this comment.
I don't think that is the right place to mention this. This should be covered by the documentation of withThrowingDiscardingTaskGroup.
|
Merging over the nightly failure which is an allocation regression |
Motivation
We started to add bridges from NIO to Swift Concurrency and we should provide some narrative documentation for our users how to adopt them.
Modification
Adds a new article that explains the NIO concurrency bridges.