Let deque have its capacity shrunk

[glbrntt]

Description

Deque is often used as a buffer and buffers can be subject to "spiky" sizes; many elements may be buffered before being removed which can result in applications holding on to more memory than desired. Since the capacity of deque is an implementation detail, one way to reduce the size of the deque is asking it to shrink itself.

Related discussion #308

Detailed Design

extension Deque {
  /// Reduces the capacity to store at least the specified number of elements.
  ///
  /// Use this method to request that the deque reduces its storage capacity.
  /// If the capacity of the deque is larger than the target capacity then
  /// the capacity _may_ be reduced. If the capacity of the deque is smaller
  /// than the requested capacity, or the deque contains more elements than
  /// the requested capacity, then the capacity won't be changed.
  ///
  /// - Parameters:
  ///   - targetCapacity: The requested capacity of the deque.
  ///
  /// - Complexity: O(`count`)
  public mutating func shrinkCapacity(_ targetCapacity: Int)
}

Documentation

How has the new feature been documented?

On the new method only.

Have the relevant portions of the guides in the Documentation folder been updated in addition to symbol-level documentation?

Yes.

Testing

How is the new feature tested?

• By shrinking the capacity of deques of differing capacities
• By attempting to shrink a deque to a capacity smaller than the required capacity
• By attempting to shrink a deque to a capacity greater than its current capacity

Performance

How did you verify the new feature performs as expected?

I didn't.

Source Impact

API addition only

Checklist

• I've read the Contribution Guidelines
• My contributions are licensed under the Swift license.
• I've followed the coding style of the rest of the project.
• I've added tests covering all new code paths my change adds to the project (to the extent possible).
• I've added benchmarks covering new functionality (if appropriate).
• I've verified that my change does not break any existing tests or introduce unexpected benchmark regressions.
• I've updated the documentation (if appropriate).

[hassila]

Why do you want separate control of shrinkage vs capacity reservation? Would it make sense to have reserveCapacity shrink if the current buffer is larger than the desired target capacity?

[lorentey]

Nit: Please use the custom expect* assertions from _CollectionsTestSupport -- XCTAssert* does not know about the context, so its failure messages will not identify the case that failed, making debugging much harder.

[lorentey]

Thanks for tackling this! 👍

[lorentey]

Can the _requestedCapacity of the created deque ever be below the capacity we requested? (I.e., shouldn't this be expecting the two values to be equal?)

[lorentey]

Hm, this raises a question: for a Deque with a handful of elements that is backed by a humungous buffer, wouldn't we want to allow the buffer to get shrunk to fit by calling shrink(targetCapacity: count) (or shrink(targetCapacity: 0))?

I suppose that instead of merely comparing directly against the count and capacity, we would want to only allow reallocation when the resulting capacity delta is "large enough" -- whatever that means. (An absolute cutoff? A percentage of existing capacity? Perhaps a combination of both. Probably the percentage value should be somewhat correlated with the regular growth factor; e.g. it would be wasteful to reallocate storage to 1000 items if it is currently only at 1001...) Something along the lines of this condition, maybe?

let delta = requestedCapacity - Swift.max(count, targetCapacity)
let threshold = Swift.max(2 * capacity / 3, 16)
guard delta > threshold else { return }

The numbers above are rather arbitrary and if we go this way, finding the right ones will require building a bit of a model.