Motivation:
Up until recently, it has not been possible to regression check our
documentation. However, in recent releases of the DocC plugin it has
become possible to make warnings into errors, making it possible for us
to CI our docs.
This patch adds support for doing that, and also cleans up our
documentation so that it successfully passes the check.
Along the way I accidentally wrote an `index.md` for `NIOCore` so I
figure we may as well keep it.
Modifications:
- Structure the documentation for NIOCore
- Fix up DocC issues
- Add `check-docs.sh` script to check the docs cleanly build
- Wire things up to our docker-compose scripts.
Result:
We can CI our docs.
Co-authored-by: George Barnett <gbarnett@apple.com>
Motivation:
We've held off on doing this for a while on the theory that function
calls are cheap, and we're happy to make them where there is no
particular need to specialize. Unfortunately, while this is true in
general, Swift is capable of optimizing ARC and exclusivity checking
when it can better understand what a method actually does.
Additionally, we'd hoped that cross-module-optimization would be a
useful addition here. Sadly, right now this still hasn't rolled out as a
default, and even if it had, it tends to be limited to smaller methods
and generic functions, all of which we've already annotated.
Modifications:
- Add @inlinable to essentially everything.
Result:
Better codegen around ByteBuffer.
Motivation:
When turning a BBV into a Collection, several of the collection
algorithms can do better if you implement the semi-private
`_copyContents` hook. We can easily implement it, so we should. While
I'm here we should clean up some other bits.
Modifications:
- Implement _copyContents.
- Implement a faster `.count` for `ByteBufferView`.
- Make `ByteBuffer.capacity` `@inlinable` to reduce ARC traffic
Result:
Copying a BBV into an Array is faster.
Motivation:
Currently the "core" NIO module (currently called NIO) contains two
fairly distinct kinds of things. The first is the core abstractions and
data structures: the things that all NIO programs must necessarily deal
with. This includes our base abstraction protocols (e.g. `EventLoop`,
`Channel`, and `ChannelHandler`), as well as our base data types (e.g.
`ByteBuffer`, `SocketAddress`, `EventLoopFuture`).
The second thing the core NIO module contains is the default POSIX
sockets event-loop and channels. These are the mainline production loops
for NIO programs, and are supported in the various BSD-like OSes to
varying extents. These can be thought of as a baseline implementation of
the core abstraction protocols that form the first part of NIO.
These two fairly distinct use-cases have no particular reason to be
glued together, and in fact in gluing them together we have done a bit
of a disservice to our adopters. The biggest issue is that it has become
impossible to write a NIO program or library that does not bring along
the POSIX layer of NIO. This has made porting NIO to other platforms
difficult (Windows has been painful, and Webassembly is coming down the
road as well), and has also bloated the size of iOS/macOS applications
that use NIO via NIOTransportServices, as all of these applications must
bring along an event loop and several Channels they will not use.
To that end, we plan to begin a scope of work to split the core NIO
module in two. Specifically, we intend to extract the baseline protocols
and data types into a new module, called `NIOCore`, which will be able
to be the baseline NIO module.
The end goal is that libraries that implement protocols on top of
SwiftNIO should be able to depend solely on `NIOCore`, not `NIO`. This
will allow NIO applications to bring along only the event loops they
want or need, without needing to pay for the POSIX sockets
implementation. This should also make porting easier, as there will be
no pressure to bring the existing `NIO` module to new platforms if it
does not fit well.
Modifications:
This is the first in a series of patches, which extracts some of the
low-hanging fruit. In particular, it extracts:
- `ByteBuffer` (and associated types)
- `RecvByteBufferAllocator`
- `CircularBuffer`
This also adds in the backwards compatibility shim: the `NIO` package
performs an exported import of `NIOCore`. This will allow this change to
avoid breaking API.
However, to make a clean break we intend not to release a new NIO minor
version until we have completed our extraction. If we fail to do this it
won't be the end of the world, we can release subsequent minor versions
that continue to extract new types. However, as much as possible should
go at once.
This patch also duplicates a few methods and files. At the end of the
patch series we need to reconcile this duplication. In many cases the
duplication will no longer be necessary, but in some cases we may have
necessary duplicates.
Result:
The first step along the road to better platform citizenship is taken.
Cory Benfield