Motivation:
Redis is written in C, so even though it has concepts of "types" such as SortedSet or List
its commands are all "free-floating" functions.
This can make it unfamiliar for those new to Redis to work within its systems and understand the relation of all of the commands.
RediStack can improve this by giving a way of having a consistent reference to a Redis type and all of its associated methods.
Modifications:
- Add: New library product called "RedisTypes"
- Add: First type to "RedisTypes", `RedisSet`
Result:
Newcomers to Redis will have an easier time getting familiar with the APIs and working with its types by having wrappers that
provide a familiar Swift Standard Library API tailored to Redis APIs.
Motivation:
The actual process for closing a connection pool involves closing each individual connection, which is all asynchronous.
There is currently no way to work off of the event when all of the connections have completed their close process.
Modifications:
- Add: `poolHasActiveConnections` error value to `RedisConnectionPoolError`
- Add: `promise` parameter to the `RedisConnectionPool.close` method
- Add: Documentation comments for the close method
Result:
Developers should now have a way of chaining callbacks when all connections in a pool have been closed.
Motivation:
As originally pointed out in #48, the `map` prefix alone is not enough context into what the method actually does.
Since it fails the future, and isn't a mapping function, the name should reflect this.
But, this method as-is currently provides little value outside of the client context, so it should not be `public`.
If users provide an adequate use case for having it outside of the package, then it can be made public again.
Modifications:
- Rename: ELF where Value == RESPValue extension `map` to `tryConverting`
- Change: `tryConverting` from public to internal
Result:
A "problematic" method should no longer be available for API users to hurt themselves with.
Motivation:
Much like the change for `RedisClientError` (6471a2) any error enum that we may want to change will necessitate a major SemVer.
To avoid this, we need to use the established struct-as-enum pattern.
Modifications:
- Change: `RESPTranslator.ParsingError` to be a struct backed by an enum
Result:
The library should be able to evolve to add more `RESPTranslator.ParsingError` cases without becoming a breaking change.
Motivation:
The SETEX and PSETEX commands are missing.
Modifications:
- Add SETEX command
- Add PSETEX command
- Add integration tests
Result:
Users can atomically set a key with an expire
Motivation:
SET has a range of options for setting expirations and conditionally
setting a value.
Modification:
- Add another `set` function with a range of options. Options are
modelled as `struct`s backed by private `enum`s to allow additional
options to be added without breaking API.
- Added tests
Result:
Options may be specified with `set`, and resolves#67
Motivation:
- Newer compilers warn that "'exported: true' has no effect in
'_specialize' attribute"
- Specialize is underscored so (probably) shouldn't be relied upon
outside of the stdlib
Modifications:
- Replace @_specialize with @inlinable
Result:
Fewer warnings on more recent compilers
Motivation:
Users of Redis will frequently want to be able to run queries in
parallel, while bounding the number of connections they use. They will
also often want to be able to reuse connections, without having to
arrange to manage those connections themselves. These are jobs usually
done by a Connection Pool.
This new connection pool will conform to `RedisClient` so a pool of clients and a single connection are interchangeable.
Connection Pools come in a wide range of shapes and sizes. In NIO
applications and frameworks, there are a number of questions that have
to be answered by any pool implementation:
1. Is the pool safe to share across EventLoops: that is, is its
interface thread-safe?
2. Is the pool _tied_ to an EventLoop: that is, can the pool return
connections that belong on lots of event loops, or just one?
3. If the pool is not tied to an EventLoop, is it possible to influence
its choice about what event loop it uses for a given connection?
Question 1 is straightforward: it is almost always a trivial win to
ensure that the public interface to a connection pool is thread-safe.
NIO makes it possible to do this fairly cheaply in the case when the
pool is only used on a single loop.
Question 2 is a lot harder. Pools that are not tied to a specific
EventLoop have two advantages. The first is that it is easier to bound
maximum concurrency by simply configuring the pool, instead of needing
to do math on the number of pools and the number of event loops. The
second is that non-tied pools can arrange to keep busy applications
close to this maximum concurrency regardless of how the application
spreads its load across loops.
However, pools that are tied to a specific EventLoop have advantages
too. The first is one of implementation simplicity. As they always serve
connections on a single EventLoop, they can arrange to have all of their
state on that event loop too. This avoids the need to acquire locks on
that loop, making internal state management easier and more obviously
correct without having to worry about how long locks are held for.
The second advantage is that they can be used for latency sensitive
use-cases without needing to go to the work of (3). In cases where
latency is very important, it can be valuable to ensure that any Channel
that needs a connection can get one on the same event loop as itself.
This avoids the need to thread-hop in order to communicate between the
pooled connection and the user connection, reducing the latency of
operations.
Given the simplicity and latency benefits (which we deem particularly
important for Redis use-cases), we concluded that a good initial
implementation will be a pool that has a thread-safe interface, but is
tied to a single EventLoop. This allows a compact, easy-to-verify
implementation of the pool with great low-latency performance and simple
implementation logic, that can still be accessed from any EventLoop in
cases when latency is not a concern.
Modifications:
- Add new internal `ConnectionPool` object
- Add new `RedisConnectionPool` object
- Add new `RedisConnectionPoolError` type
- Add tests for new types
Results:
Users will have access to a pooled Redis client.
Motivation:
`RedisKey` is `ExpressibleByStringLiteral` but not
`ExpressibleByStringInterpolation` which is often just as useful.
Modifications:
- Add `ExpressibleByStringInterpolation` conformance to `RedisKey`
Result:
Users can create `RedisKey`s using string interpolation
Motivation:
The SETNX command is missing.
Modifications:
- Add SETNX command
- Add integration test
Result:
Users can set a key only if it does not already exist
Motivation:
The current state of Swift does not leave room for library evolution of enum types used for `Error`.
To avoid having to increment Major SemVer to add a new error case that might be needed to fix a bug, the `enum-like struct` idiom should be used.
Ideally this idiom will disappear, when Swift provides a way for Swift Packages to have a "library evolution" capability.
See https://forums.swift.org/t/extensible-enumerations-for-non-resilient-libraries/35900
Modifications:
- Change: `RedisClientError` to be struct with private enum value
Result:
Should new error cases be necessary to add, they can be in Minor SemVer releases, rather than Major SemVer.
Motivation:
The project was moved from Mordil/swift-redi-stack to Mordil/RediStack;
some URLs still point to swift-redi-stack.
Modifications:
- Update URLs in README and CHANGELOG
Result:
More accurate URLs; fewer warnings from GitLab :)
Motivation:
The TTL and PTTL commands are missing.
Modifications:
- Add TTL and PTTL commands
- Add integration tests
Result:
- Users can query the ttl in seconds or milliseconds of a key
Motivation:
The EXISTS command was missing.
Modifications:
- Add 'EXISTS' to basic commands
- Add integration tests
Result:
The existence of a key can be checked.
Motivation:
parseInteger did not distinguish between not having enough bytes for an
integer and not being able to parse the integer that was present. This
was a bit tricky for code internally, where some call sites had extra
code looking for spooky action at a distance in order to determine if
the integer failed to parse.
This is unnecessary: parseInteger is sufficiently aware of what's going
on to address this problem itself.
Modifications:
- Added a new parser error (acceptable as we haven't tagged 1.0 yet).
- Throw it from parseInteger if the integer is invalid.
Result:
parseInteger clearly communicates if the integer failed to parse.
Motivation:
ByteBufferView is not zero indexed, but parseSimpleString assumes it is.
Modifications:
- Correctly compute on the distance between two indices.
- New, somewhat contrived, test case.
Result:
No functional change: because RediStack assumes the remote peer will
always correctly terminate with /r/n, there is no point at which this
code could misbehave in the current implementation. However, with small
changes it is possible to trigger it, as the new test demonstrates.
Motivation:
When we only want the first byte, rather than create temporary
intermediate arrays we can just ask NIO to give us the first byte. This
avoids unnecessary allocations.
Modifications:
- Replace `readBytes(length: 1).first` with `readInteger(as:
UInt8.self)`
Results:
11% performance improvement in load testing due to reduced allocator
pressure on the hot path.
Motivation:
When attempting to locate a single byte, creating a transient
ByteBufferView is an excessively heavyweight operation compared to a
simple getInteger. In particular, a BBV requires retain/release
operations to enforce the CoW invariants, as well as requires jumps
through substantial amounts of generic Collection code. While this can
be specialized, so can getInteger, and getInteger has much less code in
the way to cause costs.
Modifications:
- Replace temporary view creation with getInteger.
Results:
5% performance improvement on raw throughput tests.
Motivation:
`RESPValue` exposes a fair amount of complexity on how to intialize a single instance with the various overloads.
This aims to simplify the complexity for developers by providing a single initializer and relying on `RESPValueConvertible` to handle the complexities.
In addition, the Swift complier synthesizes a lot of default conformances that `RedisKey` has manually written, which is just unnecessary code.
Modifications:
- Rename: `RESPValue.init(_:)` to `RESPValue.init(from:)`
- Change: `RESPValue.init` `String?` and `FixedWidthInteger` overloads from `public` to `internal`
- Remove: Unnecessary code for various protocol conformances for `RedisKey`
Result:
Developers should have a direct and guided way of making instances of `RESPValue`
Motivation:
It was noticed that many of the commands are cumbersome to use with boilerplate type casting for each use that can be simplified within the library
by doing type conversion before returning the value to an end user.
Modifications:
Many APIs that return a `RESPValue` now have overloads to provide a `RESPValueConvertible` type that the value will be turned into before being returned.
For a few APIs that returned `RESPValue`, they did so as an Optional. Those APIs have been changed to always provide a `RESPValue` and return `.null` in cases where `nil` was returned.
In addition, the `@inlinable` attribute has been removed from any non-generic command API.
Result:
Developers should have less code boilerplate for turning values from `RESPValue` to their desired type with many commands.
Motivation:
SwiftPM as of Swift 5.2 introduces a new package dependency graph and package description that makes the current naming of RediStack awkward to pull in.
Modifications:
- Change: Package.name to be "RediStack"
The git repo will be renamed to "mordil/redistack" in addition to this change.
Result:
Fixes#72 and makes it seamless to pull in RediStack as a Swift package dependency.
Nathan Harris
tanner
George Barnett
Lukasa
Cory Benfield