[swift-evolution] [Review] SE-0184: Unsafe[Mutable][Raw][Buffer]Pointer: add missing methods, adjust existing labels for clarity, and remove deallocation size

[Taylor Swift]

On Tue, Sep 5, 2017 at 5:36 PM, Andrew Trick <atrick at apple.com> wrote:

>
>>> In the new raw initializeMemory methods, Xiaodi and I agreed to make
>>> it more clear that the offset is in terms of `self` rather than
>>> `from`, and to further reduce ambiguity by forcing manual stride
>>> computation and using an explicit "offset" label. The call site will
>>> be just as explicit as dropping down to `baseAddress` but without any
>>> pointer conversion boilerplate.
>>>
>>> UMRBP (raw buffer):
>>> +++ func initializeMemory<T>(atByteOffset:as:from:)
>>> +++ func moveInitializeMemory<T>(atByteOffset:as:from:)
>>>
>>>
>> Agree, but the label should just be `atByte:`, not `atByteOffset:`.
>> after all, we don’t use `atOffset:` in the strided case; its obvious
>> that it’s an offset
>>
>
> The existing APIs use the terminology "byte offset"--for example,
> URP.load(fromByteOffset:as:). The rationale is that "at" without a noun
> that follows implies, per Swift API naming guidelines, "at index." If you
> want to specify, as we do here, what the index _is_, then it's written out
> in full.
>
>
> Yes, it seems overly cumbersome, but I was following existing conventions
> which were intentionally very explicit.
>

it’s visually cumbersome because the “atByteOffset” overwhelms the other
two arguments but I guess i could live with it.


>
>>> We don't have a consensus, but I think the suggestion to distinguish
>>> between single value vs. multiple semantics was good. Otherwise,
>>> adding the default count could be very misleading. Normally, we try to
>>> minimize surface area, but adding two methods for the single-value case
>>> avoids ambiguity between the buffer and pointer semantics:
>>>
>>> UMP (pointer)
>>> --- func initialize(to:count:(=1))
>>> +++ func initialize(to:)
>>> +++ func initialize(repeating:count:) // no default count
>>> +++ func assign(to:)
>>> +++ func assign(repeating:count:) // no default count
>>>
>>> UMRP (raw pointer):
>>> --- func initializeMemory<T>(as:at:(=0)count:(1)to:)
>>> +++ func initializeMemory<T>(as:repeating:count:) // remove default
>>> count
>>>
>>
>> still extremely suspicious of this but i’m willing to compromise. also
>> there should be an `initializeMemory<T>(at:to:)` to match the typed
>> methods
>>
>
> Do you mean initializeMemory<T>(as:to:)?
>
>
> I don’t think it’s necessary since raw buffers are not normally used to
> hold a single typed element. We don’t need symmetry between raw and typed
> pointers and I wouldn’t want to add an API that will never be used. So, I
> would be ok with it only if there’s some use case that I’m overlooking.
>

The only case i can think of is initializing a buffer header but then again
i rarely use raw pointers so i’m not sure how much this feature would be
used. However, this function is already
<https://developer.apple.com/documentation/swift/unsafemutablerawpointer/2427589-initializememory>
in the API (with a default count of 1 and offset of 0) so there’s that.


>
> -Andy
>
>
>>> On Tue, Sep 5, 2017 at 11:31 AM, Andrew Trick <atrick at apple.com> wrote:
>>>
>>>> I think we’ve agreed to a few minor updates to this proposal. Since
>>>> there hasn’t been any other feedback on the thread it may be worth posting
>>>> an amended proposal so we all know what we’ve agreed on.
>>>>
>>>> -Andy
>>>>
>>>> On Sep 3, 2017, at 8:23 PM, Andrew Trick via swift-evolution <
>>>> swift-evolution at swift.org> wrote:
>>>>
>>>>
>>>> On Sep 3, 2017, at 8:05 PM, Xiaodi Wu <xiaodi.wu at gmail.com> wrote:
>>>>
>>>> If we use byte offset, then the at parameter in UnsafeMutableRawPointer
>>>>>  should be removed, since pointer arithmetic can be used instead
>>>>> (just like with UnsafeMutablePointer).
>>>>>
>>>>
>>>> I agree that it seems quite sensible to remove the ‘at’ parameter
>>>> altogether from the UMRP method.
>>>>
>>>>
>>>> No code in tree or on github is using the `at` argument. I think it can
>>>> be removed. A fixit should still be possible.
>>>>
>>>> Not convinced moving the at: argument to come before the as: argument
>>>>> is worth it in terms of source breakage.
>>>>>
>>>>
>>>> Since much of this proposal involves shuffling and relabeling
>>>> arguments, I’d argue it’s better to break slight more source in one go for
>>>> the optimal API than to break slightly less for a slightly less optimal
>>>> API, no? (This is assuming there is agreement that ‘at:as:’ is less prone
>>>> to misinterpretation than ‘as:at:’.)
>>>>
>>>>
>>>> To be clear, we’re just talking about UnsafeMutableRawBufferPointer.initializeMemory
>>>> now, so this is purely additive.
>>>> I think the label needs to be `atByteOffset`, and placing it before
>>>> `as` makes a lot of sense because it no longer depends on the type’s
>>>> stride.
>>>>
>>>> -Andy
>>>> _______________________________________________
>>>> swift-evolution mailing list
>>>> swift-evolution at swift.org
>>>> https://lists.swift.org/mailman/listinfo/swift-evolution
>>>>
>>>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20170905/88a3475d/attachment-0001.html>