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.
_______________________________________________
swift-evolution mailing list
[email protected]
https://lists.swift.org/mailman/listinfo/swift-evolution
