Motivation:
We recently grew a script to diff the output of `malloc-aggregation.d`,
we should document how this can be used when debugging allocation
regressions.
Modifications:
- Update the doc to include an example of using the script to debug an
allocation regression
- Fix a bug in the script where before/after were mixed up
- Fix a bug in the script where usage would print '()\n' instead of '\n'
Result:
- Better info on debugging allocations
Co-authored-by: Johannes Weiss <johannesweiss@apple.com>
Motivation:
Calling `function(otherFunction)` allocates, but
`function({ otherFunction($0) }` does not.
See: SR-12115 and SR-12116.
Modifications:
Avoid passing functions directly; pass them in new closures instead.
Result:
Fewer allocations.
Motivation:
The tooling around the allocation counter tests is pretty opaque and
also not easy to use.
Modifications:
Document what interested folks should know.
Result:
More people will be able to debug allocations in SwiftNIO.
Co-Authored-By: Cory Benfield <lukasa@apple.com>
Motivation:
NIO doesn't offer any tips of on how to write performant code. After
discussing with @weissi we decided it would be useful to gather and
document some useful tips and tricks.
Modifications:
Started an optimization tips document.
Result:
Easier for NIO users to write performant code.
Motivation:
@tomerd learned the hard way that there were some subtle changes in
B2MDs around intercepting arbitrary channel events. Previously,
intercepting those was illegal but possible. In NIO 2, it's impossible.
Modifications:
add a description for what changed
Result:
easier migrations
Motivation:
A bunch of things change with the release of NIO 2. We should update the
documentation to reflect that.
Modifications:
- update readme
- update migration guide
Result:
up to date docs.
Motivation:
EmbeddedChannel.finish/writeInbound/writeOutbound returned some mystery
bools. I always had to check the code to remember what they actually
meaned.
Whilst this is technically a breaking change, I couldn't find any users
of the return values on Github that are using the convergence releases.
Modifications:
Replace them by enums giving you all the information.
Result:
- fixes#916
- clearer APIs
* make HTTPMethod.hasRequestBody internal
Motivation:
HTTPMethod.hasRequestBody was unnecessarily public.
Modifications:
make it internal
Result:
fixes#151
* Update public-api-changes-NIO1-to-NIO2.md
Motivation:
swift-nio-http2 and swift-nio-transport-services are now converging.
Modifications:
Updated the migration guide.
Result:
Docs will be up to date.
Motivation:
Mention convergence in migration guide.
Modifications:
tell people about the correct dependencies in the migration guide.
Result:
happier users.
Motivation:
Follows on from the work done in #528 for #527: we have moved the the
default error handling out of WebSocketFrameDecoder, but had to leave
the code there for backward compatibility reasons. We can remove that
code now.
Modifications:
Removed automatic error handling code in WebSocketFrameDecoder.
Result:
- fixes#534
Motivation:
scheduleRepeatedTask had two overloads: for synchronous and asynchronous
tasks. They however had the same name so they were pretty much
impossible to use.
Modifications:
rename the asynchronous version of scheduleRepeatedTask to
scheduleRepeatedAsyncTask
Result:
- NIO easier to use
- fixes#882
Motivation:
The HTTP/1 headers were quite complicated, CoW-boxed and exposed their
guts (being a ByteBuffer). In Swift 5 this is no longer necessary
because of native UTF-8 Strings.
Modifications:
- make headers simply `[(String, String)]`
- remove `HTTPHeaderIndex`, `HTTPListHeaderIterator`, etc
Result:
- simpler and more performant code
Motivation:
MessageToByteEncoder was a protocol that similar to ByteToMessageDecoder
was pretty hard to hold correctly (override some methods but not
others). This PR brings MessageToByteEncoder more in line with the new
ByteToMessageDecoder.
Modifications:
- refactor `MessageToByteEncoder`
- introduce `MessageToByteHandler`, similar to `ByteToMessageHandler`
Result:
- better API, more similar to ByteToMessageDecoder
- fixes#864
Motivation:
We need to fix#577 sometime soon and in preparation of that we'll
change convert NIOWebSocketUpgradeError from enum to struct.
Modifications:
convert NIOWebSocketUpgradeError from enum to struct
Result:
- NIOWebSocketUpgradeError can be adjusted without SemVer major breaking
changes
- fixes#839
Motivation:
We're not happy with HTTPResponseCompressor's API and it needs to
incubate a little more, hence moving to
[`swift-nio-extras`](https://github.com/apple/swift-nio-extras).
Modifications:
- removed HTTPResponseDecoder
- removed the zlib dependency
Result:
- no more HTTPResponseDecoder
Motivation:
While the HTTPServerUpgrader and WebSocketUpgrader allowed users to take
their time when reconfiguring the pipeline after they decided to upgrade,
users had to synchronously decide if they wanted to upgrade. This is a bit
inconvenient.
A particular limitation here is that some routes may want to upgrade
only if the upgrading user is authenticated. Checking authentication
credentials is almost always an I/O operation, and so cannot safely be done
on the event loop. Our original design made this impossible.
Modifications:
- Changed the shouldUpgrade callback to return a Future.
- Passed the shouldUpgrade callback the Channel that is upgrading, in
no small part so that it has an EventLoop it can create Futures
on.
- Rewrote the upgrader to handle this new state.
Result:
Users can delay decisions about when to upgrade.
Motivation:
The NIO 1 to 2 migration is not too bad if you know a few tricks. So we
should list them in a migration guide.
Modifications:
add first cut of migration guide
Result:
happier users
Motivation:
Previously we leaked `pthread_key`s as we only ever called
`pthread_key_create` but never `pthread_key_delete`. This patch fixes
that.
Modifications:
- made `ThreadSpecificVariable` a class (so we get lifecycle management
through ARC)
- instead of just storing the value, store `Box<(ThreadSpecificVariable<T>, T)>`
so we can control the lifecycle of the `ThreadSpecificVariable` as
needed
Result:
We don't leak `pthread_key`s anymore.
Motivation:
`ctx` was always an abbreviation was 'context` and in Swift we don't
really use abbreviations, so let's fix it.
Modifications:
- rename all instances of `ctx` to `context`
Result:
- fixes#483
Motivation:
B2MD should never call any of the decode functions after the user has
thrown an error.
Modifications:
introduce an error state and make sure we don't call out if in error
state
Result:
B2MD more correct
Motivation:
The thread pool implementation can be used for many things not just
blocking IO.
Modifications:
rename BlockingIOThreadPool to NIOThreadPool
Result:
fixes#186
Motivation:
Previously B2MDs didn't really have defined semantics regarding EOFs and
we didn't tell them if there was an EOF. Also `decodeLast` was optional
and all that was bad.
Modifications:
- require `decodeLast`
- add a `seenEOF: Bool` parameter to `decodeLast` which tells the
decoder if an EOF has been seen
Result:
- clearer semantics
- more information
Motivation:
- `ChannelPipeline.add(name:handler:...)` had a strange order of arguments
- `remove(handler:)` and `remove(ctx:)` both remove `ChannelHandler`s
but they read like they remove different things
So let's just fix the argument order and name them `addHandler` and
`removeHandler` making clear what they do.
Modifications:
- rename all `ChannelPipeline.add(name:handler:...)`s to `ChannelPipeline.addHandler(_:name:...)`
- rename all `ChannelPipeline.remove(...)`s to `ChannelPipeline.removeHandler(...)`
Result:
more readable and consistent code
Motivation:
Opaque indices are a good idea for collections, (Marked)CircularBuffer
should use those too.
Modifications:
Cheapest possible implementation for opaque indices, could be much
improved. This is the cheapest possible implementation for opaque
indices and this could be much improved later, see #682 but the
improvements won't be SemVer major :).
Result:
first stab at #682
Motivation:
ChannelOptions used a too complicated mechanism for what they are.
Modifications:
- change the ChannelOptions to a much simpler mechanism
- rename the generic parameters from T to Option
Result:
code easier to read and understand
Motivation:
Collisions with Foundation and other standard libraries is painful.
Modifications:
- rename `FileHandle` to `NIOFileHandle`
- rename `Thread` to `NIOThread` (only exposed in docs)
Result:
fewer collisions
Motivation:
ChannelOptions should've always been Equatable and so far we've hacked
around them not being Equatable when we wanted to compare them.
Modifications:
make all ChannelOptions Equtable
Result:
- ChannelOption comparison actually works
- fixes#598
- make more ChannelOptions stuff inlinable to not regress allocations
Motivation:
As part of NIO2 - much work has been done to round out the API of EventLoopFuture. This finishes existing public API parameters to be more in line with Swift API guidelines.
Modifications:
Methods in EventLoopFuture that had `eventLoop` as a parameter label have been changed to `on`
Results:
EventLoopFuture public API is more "Swifty" with calls such as `future.hop(to: eventLoop)` rather than `future.hopTo(eventLoop: eventLoop)`
Motivation:
ByteBuffer methods like `set(string:)` never felt very Swift-like and
also didn't look the same as their counterparts like `getString(...)`.
Modifications:
- rename all `ByteBuffer.set/write(<type>:,...)` methods to
`ByteBuffer.set/write<Type>(...)`
- polyfill the old spellings in `_NIO1APIShims`
Result:
code more Swift-like
Motivation:
If ChannelHandler removal worked correctly, it was often either by
accident or by intricate knowledge about the implementation of the
ChannelHandler that is to be removed. Especially when it comes to
re-entrancy it mostly didn't work correctly.
Modifications:
- introduce a `RemovableChannelHandler` API
- raise allocation limit per HTTP connection by 1
(https://bugs.swift.org/browse/SR-9905)
Result:
Make things work by contruction rather than accident
Motiviation:
After adding `ELF.whenAllComplete` the concept of "fail fast" and "fail slow" for reducing an array of future results together was introduced.
This commit adds that concepts with the `andAll* methods that act as simple completion notifications.
Modifications:
Rename `EventLoopFuture.andAll(_:eventLoop:)` to `andAllSucceed(_🔛)` to denote its "fail fast" nature, and to match Swift API guidelines.
Add new `EventLoopFuture.andAllComplete(_🔛)` for a "fail slow" companion.
Shift implementation of `whenAllComplete(_🔛)` to be usable without unnecessary allocations in `andAllComplete`
Result:
EventLoopFuture now has two methods for "flattening" arrays of EventLoopFuture into a single notification ELF
Motivation:
The `ELF.cascade` methods have a parameter label `promise` that does not match Swift API Guidelines, and a way to cascade just successes is not available - while for failures there is.
Modifications:
`ELF.cascade*` methods that already exist have had their `promise` label renamed to `to`, and a new `ELF.cascadeSuccess` method has been added.
Result:
EventLoopFuture now has the cascade methods `ELF.cascade(to:)`, `ELF.cascadeFailure(to:)`, and `ELF.cascadeSuccess(to:)`
Motivation:
initialRingCapacity is not a great name, initialCapacity is much better
Modifications:
rename CircularBuffer(initialRingCapacity:) to initialCapacity
Result:
more consistent code
Motivation:
The name `mapIfError` implied that you can transform the error value but
really that's never what it did. Instead, it allowed you to recover
from a failure.
Modifications:
- rename `mapIfError` to `recover`
Result:
cleaner method names
Motivation:
EventLoopPromise.succeed/fail has extraneous labels that don't add
anything but noise.
Modifications:
remove extraneous labels
Result:
less noise in the code
Motivation:
ELF's API should be as close as possible to the new Result's API.
Therefore, we should rename `then` to `flatMap`
Modifications:
- renamed `then` to `flatMap`
- renamed `thenIfError` to `flatMapError`
- renamed ELF's generic parameter from `T` to `Value`
Result:
- more like Result
- fixes#688
Motivation:
SemVer requires us to declare a public API, we should do so for NIO 2.
Modifications:
declare our public API.
Result:
more transparency into our versioning policy.
Motivation:
Now that the stdlib has introduced the Result type, we can use it in the
implementation (and the whenComplete) function of EventLoopFuture
Modifications:
- replace EventLoopValue with Result
- make whenComplete provide the Result
Result:
use the new shiny stuff
Motivation:
ContiguousCollection is no longer necessary because Sequence gained
withContiguousStorageIfAvailable.
Modifications:
Removed ContiguousCollection and switch to withContiguousStorageIfAvailable.
Result:
less code
Motivation:
ByteBuffer has pretty good string writing APIs, but they're imperfect.
In particular, the methods in ByteBuffer-aux both return optional Int,
which is strange as they cannot fail. We also only have support for writing
strings in UTF-8.
Modifications:
- ByteBuffer.set(string:at:) and ByteBuffer.write(string:) now both
return `Int`, and their return value has been made discardable.
- NIOFoundationCompat has been expanded with two new methods for writing
strings to ByteBuffers in various encodings using Foundation's
encoding support: ByteBuffer.set(string:encoding:at:) and
ByteBuffer.write(string:encoding:).
- NIOFoundationCompat has also been expanded with a companion to the
already existing ByteBuffer.getString(at:length:encoding), namely
ByteBuffer.readString(length:encoding:).
- New error enum for reporting failures to encode.
Result:
Easier to work with strings in a wider variety of cases with
ByteBuffer
Resolves#253.
* Change unnecessary functions to variables
Motivation:
The changed functions do not have any side effects and therefore better convey intent when being a simple computed variable.
Modifications:
Changes:
- `func markedElementIndex() -> Int?` to `var markedElementIndex: Int?`
- `func markedElement() -> E?` to `var markedElement: E?`
- `func hasMark() -> Bool` to `var hasMark: Bool`
Result:
- improved code quality
Motivation:
WebSocketOpcode was made an enumeration to make it possible to cleanly
switch over the values in switch statements. However, this unfortunately
made it possible to construct contradictory values of WebSocketOpcode,
such as .unknownNonControl(0x1) (which should be spelled .text), or
.unknownControl(0xFF) (which is simply invalid).
This patch removes the ability to construct invalid values of
WebSocketOpcode by turning it into a struct and using static lets for known
values. While we're here it cleans some other stuff up.
Modifications:
- Made WebSocketOpcode a struct
- Added several static lets for easy access and to reduce code churn
- Used synthesised Equatable conformance
- Added synthesised Hashable conformance
- Added CustomStringConvertible conformance to better represent known values
- Added CaseIterable conformance to provide entire range of valid values.
Result:
WebSocketOpcode will be a better-behaved type with more guarantees and
fewer places to trap and explode.
Resolves#617.
George Barnett