[swift-evolution] [Pitch] Eliminate `ManagedProtoBuffer`

[Erik Eckstein]

The reason why `ManagedProtoBuffer` (the base class of `ManagedBuffer`) exists is to give the users an extra bit of type safety inside of the closure `initialHeader` passed to `ManagedBuffer.create()`.

public class ManagedBuffer<Header, Element>
  : ManagedProtoBuffer<Header, Element> {

  /// Create a new instance of the most-derived class, calling
  /// `initialHeader` on the partially-constructed object to
  /// generate an initial `Header`.
  public final class func create(
    minimumCapacity: Int,
    initialHeader: @noescape (ManagedProtoBuffer<Header, Element>) throws -> Header
  ) rethrows -> ManagedBuffer<Header, Element> {
    // ...
  }
}

This closure receives the `ManagedBuffer` instance and returns the initial value that is stored in the buffer (the header part of the buffer).  We are passing the `ManagedBuffer` as `ManagedProtoBuffer` to prevent the closure from reading the uninitialized `value` property. This property is defined in `ManagedBuffer` but not in `ManagedProtoBuffer`.

  public final var header: Header {
    // ...
  }

This extra bit of safety requires the existence of `ManagedProtoBuffer`, which complicates the API.
The name may also lead to some confusion with Google's Protocol Buffers project.

This proposal suggests removing `ManagedProtoBuffer` in order to simplify the API.
It means that  `ManagedBuffer` would not be derived from `ManagedProtoBuffer` and all methods from `ManagedProtoBuffer` would be moved to `ManagedBuffer`.
The closure `initialHeader` would receive a  `ManagedBuffer` instead of a `ManagedProtoBuffer`.

public class ManagedBuffer<Header, Element> {

  /// Create a new instance of the most-derived class, calling
  /// `initialHeader` on the partially-constructed object to
  /// generate an initial `Header`.
  public final class func create(
    minimumCapacity: Int,
    initialHeader: @noescape (ManagedBuffer<Header, Element>) throws -> Header
  ) rethrows -> ManagedBuffer<Header, Element> {
    // ...
  }
}

Also `ManagedBufferPointer`'s init function (the second occurrence of  `ManagedProtoBuffer`) would receive a  `ManagedBuffer` instead of a `ManagedProtoBuffer`:

  /// Manage the given `buffer`.
  ///
  /// - Note: It is an error to use the `header` property of the resulting
  ///   instance unless it has been initialized.
  internal init(_ buffer: ManagedBuffer<Header, Element>) {
    _nativeBuffer = Builtin.castToNativeObject(buffer)
  }


Motivation
==========
The removal of `ManagedProtoBuffer` would simplify the API and avoids confusion with Google's Protocol Buffers.

Alternatives
============
*) Leave as is.
*) Rename the class to avoid the "confusion"-problem.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160718/0dc19fb7/attachment.html>