docs: ClientBootstrap reuse is not important but permissible on the same thread/EL #2520
Conversation
weissi
changed the title
@tayloraswift I needed to undo the ``Sendable`` and ``EventLoop`` because they're in different modules :|
|
it would be really great if we could suppress the DocC symbol link warnings, those cross-module/cross-package links work on Swiftinit! |
@franklinsch is this an option? Or will this work in DocC soon too? Context is that I had to take out and because it complained |
| /// Usually you re-use a `ClientBootstrap` once you set it up and called `connect` multiple times on it. | ||
| /// This way you ensure that the same `EventLoop`s will be shared across all your connections. | ||
| /// You may re-use a `ClientBootstrap` once you set it up and call `connect` multiple times on it. | ||
| /// This ensures all connections you create share the same `EventLoop`. |
There was a problem hiding this comment.
This is not true. We are taking the next EventLoop from the EventLoopGroup in connect.
| /// Creating a `ClientBootstrap` is cheap. So instead of arranging synchronization allowing | ||
| /// concurrent code to re-use a single `ClientBootstrap` instance across many tasks, it is often | ||
| /// easier to create a dedicated instance for each task. | ||
| /// multiple threads/`EventLoop`s. Creating a `ClientBootstrap` is cheap so instead of arranging | ||
| /// synchronization to re-use a single `ClientBootstrap` instance across threads, it's advisable to | ||
| /// create fresh instances. |
There was a problem hiding this comment.
This here is somewhat duplicated
|
@weissi We're tracking cross-target link resolution with apple/swift-docc#208. It's being worked on primarily by @d-ronnqvist |
The initial support for cross-target linking in DocC is available on main behind a feature flag but the overall feature of multi-target documentation is still in progress. Note that the planned—and currently implemented—syntax for linking to a symbol in another module is stating with a leading
|
@dnadoba I assume NIO isn't using feature flags for its docs right now so this has to stay as is, correct? |
|
I'm not aware of any feature flags set for DocC in NIO. The two main way DocC is compiled is through the build system provided by https://swiftpackageindex.com/ and Xcodes "Product -> Build Documentation" action. I'm not aware of a safe way to add flags to both of them. |
Motivation:
The original
ClientBootstrapdocumentation is sometimes misunderstood as stressing the importance to re-use.Modifications:
Explain that reuse is not important but permissible on the same thread/EL.
Result:
Clearer docs.