This is an archive of the discontinued LLVM Phabricator instance.

Differential D95821

[docs] Explain noexcept policy for narrow contracts.
ClosedPublic

Authored by zoecarver on Feb 1 2021, 2:15 PM.

Details

Reviewers
mclow.lists
ldionne
Group Reviewers
Restricted Project
Commits
rGfab194898b5e: [lic++][docs] Explain noexcept policy for narrow contracts.
Summary

Adds documentation around libc++'s policy to add noexcept to things that cannot throw but aren't marked as noexcept.

Refs LWG 3518 and D95251.

Diff Detail

Event Timeline

zoecarver requested review of this revision.Feb 1 2021, 2:15 PM
zoecarver created this revision.
Herald added a project: Restricted Project. · View Herald TranscriptFeb 1 2021, 2:15 PM
Herald added a reviewer: Restricted Project. · View Herald Transcript
Herald added a subscriber: libcxx-commits. · View Herald Transcript
zoecarver mentioned this in D95251: Remove noexcept from basic_string::find and implementation functions..Feb 1 2021, 2:19 PM
Harbormaster completed remote builds in B87424: Diff 320598.Feb 1 2021, 3:23 PM
zoecarver mentioned this in D95848: Add `noexcept` to `string::find` and similar members..Feb 1 2021, 10:15 PM
curdeius added a subscriber: curdeius.Feb 2 2021, 1:46 AM
curdeius added inline comments.
libcxx/docs/UsingLibcxx.rst
355 ↗(On Diff #320598)

Why not 13?

zoecarver added inline comments.Feb 2 2021, 9:51 AM
libcxx/docs/UsingLibcxx.rst
355 ↗(On Diff #320598)

Has the 13 release branch already been created? Even if it hasn't yet, almost all of the changes won't follow this "new" policy, so I think 14 makes more sense.

If you'd still prefer I change it to 13, I'm happy to do that, though.

curdeius added inline comments.Feb 2 2021, 10:06 AM
libcxx/docs/UsingLibcxx.rst
355 ↗(On Diff #320598)

Release branch 12.x has been created a few days ago. So current main is version 13. It will be released in circa 6 months. I guess you thought it was one higher.

zoecarver added inline comments.Feb 2 2021, 10:07 AM
libcxx/docs/UsingLibcxx.rst
355 ↗(On Diff #320598)

Ah, I see, yes, I did think it was one higher.

Mordante added a subscriber: Mordante.Feb 2 2021, 10:59 AM

Can you also update the ReleaseNotes with this change in behaviour?

libcxx/docs/UsingLibcxx.rst
356 ↗(On Diff #320598)

A bit pedantic, but it seems the Standard capitalizes Nothing.

357 ↗(On Diff #320598)

This sentence is quite long. Maybe add a full stop throwing and user-provided -> throwing. User-provided

361 ↗(On Diff #320598)

When adjusting 14 to 13, also change it here.

ldionne requested changes to this revision.Feb 2 2021, 12:14 PM
ldionne added inline comments.
libcxx/docs/UsingLibcxx.rst
352 ↗(On Diff #320598)

I think this should move to libcxx/docs/DesignDocs/<something>.rst. You can then reference it (like the other design docs) from the main rst file.

355 ↗(On Diff #320598)

Instead of wording this as "libc++ *will* mark functions that do not throw as noexcept", I think we should instead say something like: It is acceptable to mark functions that do not throw as noexcept. That way, we say that we are allowed to do it and we may use that right, but we don't *have* to. As worded currently, it sounds like people could file bugs against us for not following our own design policy to the letter. Do you see the distinction?

356 ↗(On Diff #320598)

I think your closing parens is not in the right place. I think you mean this instead:

"Throws: Nothing") as noexcept.

This revision now requires changes to proceed.Feb 2 2021, 12:14 PM
zoecarver added inline comments.Feb 2 2021, 3:38 PM
libcxx/docs/UsingLibcxx.rst
355 ↗(On Diff #320598)

Yes, I see the distinction, and I think you're right.

I'd kind of like to say that going forward we *will* mark these functions as noexcept, but I understand that might not be a reasonable thing to do (or at least not reasonable to do right now).

I updated the text to use 'may'/'might' rather than 'will'.

zoecarver updated this revision to Diff 320936.Feb 2 2021, 3:38 PM
  • Address review comments
Herald added a subscriber: arphaman. · View Herald TranscriptFeb 2 2021, 3:38 PM
zoecarver updated this revision to Diff 320938.Feb 2 2021, 3:39 PM
  • Add newline to UsingLibcxx.rst
zoecarver added inline comments.Feb 2 2021, 3:41 PM
libcxx/docs/DesignDocs/NoexceptPolicy.rst
16

Now that we just say that we might mark some functions as noexcept, we might not need this paragraph, what do you think?

Harbormaster completed remote builds in B87599: Diff 320936.Feb 3 2021, 7:16 AM
Harbormaster completed remote builds in B87600: Diff 320938.Feb 3 2021, 9:09 AM
ldionne accepted this revision.Feb 5 2021, 7:38 AM

LGTM with paragraph removed. This is small, but it's important to record these decisions/policies by writing somewhere so that we can apply them mechanically in the future and avoid wasting time. Thanks!

libcxx/docs/DesignDocs/NoexceptPolicy.rst
16

Agreed.

This revision is now accepted and ready to land.Feb 5 2021, 7:38 AM
Closed by commit rGfab194898b5e: [lic++][docs] Explain noexcept policy for narrow contracts. (authored by zoecarver). · Explain WhyFeb 5 2021, 11:27 AM
This revision was automatically updated to reflect the committed changes.
zoecarver added a commit: rGfab194898b5e: [lic++][docs] Explain noexcept policy for narrow contracts..
zoecarver mentioned this in rGdea74b282061: [libc++] Add `noexcept` to `string::find` and similar members..Feb 9 2021, 11:48 AM

Revision Contents

PathSize
libcxx/
docs/
DesignDocs/
13 lines
1 line

Diff 321838

libcxx/docs/DesignDocs/NoexceptPolicy.rst

  • This file was added.
====================
``noexcept`` Policy
====================
Extended applications of ``noexcept``
------------------------------------------
As of version 13 libc++ may mark functions that do not throw (i.e.,
"Throws: Nothing") as ``noexcept``. This has two primary consequences:
first, functions might not report precondition violations by throwing.
Second, user-provided functions, such as custom predicates or custom
traits, which throw might not be propagated up to the caller (unless
specified otherwise by the Standard).
zoecarverAuthorUnsubmitted
Done
ReplyInline Actions

Now that we just say that we might mark some functions as noexcept, we might not need this paragraph, what do you think?

zoecarver: Now that we just say that we might mark some functions as noexcept, we might not need this…
ldionneUnsubmitted
Not Done
ReplyInline Actions

Agreed.

ldionne: Agreed.

libcxx/docs/index.rst

Show First 20 Lines • Show All 167 Lines • ▼ Show 20 Lines.. toctree::
DesignDocs/ABIVersioning DesignDocs/ABIVersioning
DesignDocs/ExperimentalFeatures DesignDocs/ExperimentalFeatures
DesignDocs/VisibilityMacros DesignDocs/VisibilityMacros
DesignDocs/ThreadingSupportAPI DesignDocs/ThreadingSupportAPI
DesignDocs/FileTimeType DesignDocs/FileTimeType
DesignDocs/FeatureTestMacros DesignDocs/FeatureTestMacros
DesignDocs/ExtendedCXX03Support DesignDocs/ExtendedCXX03Support
DesignDocs/UniquePtrTrivialAbi DesignDocs/UniquePtrTrivialAbi
DesignDocs/NoexceptPolicy
* `<atomic> design <http://libcxx.llvm.org/atomic_design.html>`_ * `<atomic> design <http://libcxx.llvm.org/atomic_design.html>`_
* `<type_traits> design <http://libcxx.llvm.org/type_traits_design.html>`_ * `<type_traits> design <http://libcxx.llvm.org/type_traits_design.html>`_
* `Notes by Marshall Clow`__ * `Notes by Marshall Clow`__
.. __: https://cplusplusmusings.wordpress.com/2012/07/05/clang-and-standard-libraries-on-mac-os-x/ .. __: https://cplusplusmusings.wordpress.com/2012/07/05/clang-and-standard-libraries-on-mac-os-x/
Build Bots and Test Coverage Build Bots and Test Coverage
Show All 39 Lines