[libcxx-dev] Proposal for handling experimental features in libc++

Mon May 20 16:08:12 PDT 2019

On Mon, May 20, 2019 at 1:34 PM Louis Dionne <ldionne at apple.com> wrote:

>
>
> On May 17, 2019, at 13:16, Marshall Clow <mclow.lists at gmail.com> wrote:
>
> On Thu, May 16, 2019 at 11:18 PM Eric Fiselier <eric at efcs.ca> wrote:
>
>> I'm coming into this conversation late, so let me pontificate for a
>> moment:
>>
> [snip]
>
>>
>> With that in mind, here are my thoughts on the proposal:
>>
>> * `std::experimental::foo` and `std::foo` are different things. It's
>> important for users to understand that
>>   `std::experimental::foo` provides none of  the same API/ABI stability
>> guarantees `std::foo` does.
>>
>>> <https://lists.llvm.org/cgi-bin/mailman/listinfo/libcxx-dev>
>>
>>
> Not only that, but there is no guarantee that  `std::experimental::foo`
> and `std::foo` behave the same.
> (Similar, almost certainly yes - but in detail, probably not)
> Optional is the poster child here.
>
> If people want stability, guarantees against breaking changes, etc. - then
> they should not use stuff in std::experimental.
> Period. Full stop.
> Wait for it to appear in a standard.
>
>
> Okay, so I had a discussion with Marshall last Friday, and I'd like to
> summarize the current situation and where we disagree. Marshall, please
> feel free to amend anything I say below.
>
> My main gripe is that the user experience for experimental features is
> currently not excellent. In particular, users are making assumptions they
> shouldn't make about experimental features, and they end up using those
> features in places where an experimental feature wouldn't belong (e.g. an
> API boundary of a stable library, or somewhere that requires ABI
> stability). This ends up biting them (and hence us too) when we break those
> assumptions. Note that I fully understand this is a "users are misbehaving"
> kind of problem. However, I think it is unrealistic to expect users to know
> about TSes, Standard release cycles, and even important things like ABI
> stability. I think we must put mechanisms in place to force them to behave
> correctly.
>
> More specifically, I'm trying to address the problem on three main fronts:
> 1. I want users to opt-in explicitly and at the compiler flag level to get
> experimental features. Otherwise, the declarations are not present in the
> headers. This way, by default, they don't have access to experimental
> features. If they want them, they must enable the flag in their project
> (and all dependent projects in case of a library), which I claim is going
> to make them understand the experimental nature of those features.
>

If this is what Apple needs in order to provide these features to their
users, then I support it. What is most important to me is getting these
features in the hands of users.
I hear Marshall's concern, and adding additional barriers will cause
problems for some users. For example, ones using Clang before
`-fexperimental` was implemented.

My opinion is that typing `<experimental/foo>` or `std::experimental::foo`
should be enough to communicate the true experimental nature of these
components to users.
Speaking to other STL implementers/vendors, they seem to share this
position. But I don't feel so strongly that I want to block progress on
this issue.

That being said, let me proposal an middle ground: Let's add a compiler
warning.

The compiler warning would diagnose any use of `std::experimental` names.
It would produce a good quality diagnostic about how the use of
experimental components
should be explicitly opted into because they are not ABI or API stable, and
that users who understand these risks can disable the warning in this way
(Perhaps by specifying
`-fexperimental`).

With a warning the diagnostic the user hits when first trying to use
`std::experimental::foo` will be a lot more understandable than if the
identifier simply isn't present.
And it would provide better compatibility with older Clang versions or GCC.
The warning approach would have consistent behavior across standard library
implementations.

Apple can ship the warning as on-by-default making the use of experimental
components explicitly opt-in.

The warning also leaves open the `-fexperimental` path if we choose to go
down it.

Thoughts?

> 2. I want to have a user-friendly way of using non header-only
> experimental features. This is a nice-to-have.
> 3. I want to have a user-visible way of warning users that an experimental
> feature is going to be removed in a few LLVM releases. People don't read
> the documentation and they don't follow exactly when we implement the non
> experimental version of a feature.
>
> Marshall's opinion is that adding barriers to use experimental features is
> just going to be frustrating and will not change the fact that users make
> incorrect assumptions about experimental features. We already put those
> features in a `experimental` namespace, and users are just going to add the
> compiler flag without really considering the implications.
>
> So we disagree on (1), specifically the part where -fexperimental would
> control whether we provide the declarations of experimental features in
> libc++. However, we both agree on (2) and (3), although we don't agree on
> how to solve (3) exactly -- but I don't think that's the main point of
> contention. I see a couple of paths we can take going forward:
>
> 1. Status quo, which leads to embarrassing situations where we break users
> and tell them "it's your problem, the feature was experimental".
> 2. We adopt my proposal as-is.
> 3. We adopt my proposal but we don't add -fexperimental (or we add it but
> it only controls whether -lc++experimental is linked). It is an improvement
> over the status quo because we still agree to add deprecation warnings when
> we ship the non-experimental version of a feature.
>
> Any thoughts?
> Louis
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/libcxx-dev/attachments/20190520/3e4e5a4b/attachment-0001.html>