Adds a description of why we implement invoke as we do

[barcharcraz]

Description

I ran across this comment on reddit from our very own @StephanTLavavej about why we need the _IMPLEMENT_INVOKE macro. I thought it was helpful and I had bounced off that particular macro a few times, so I added his explanation as a comment in the code (with some minor editing)

Checklist

Be sure you've read README.md and understand the scope of this repo.

If you're unsure about a box, leave it unchecked. A maintainer will help you.

• Identifiers in product code changes are properly _Ugly as per
  https://eel.is/c++draft/lex.name#3.1 or there are no product code changes.
• The STL builds successfully and all tests have passed (must be manually
  verified by an STL maintainer before automated testing is enabled on GitHub,
  leave this unchecked for initial submission).
• These changes introduce no known ABI breaks (adding members, renaming
  members, adding virtual functions, changing whether a type is an aggregate
  or trivially copyable, etc.).
• These changes were written from scratch using only this repository,
  the C++ Working Draft (including any cited standards), other WG21 papers
  (excluding reference implementations outside of proposed standard wording),
  and LWG issues as reference material. If they were derived from a project
  that's already listed in NOTICE.txt, that's fine, but please mention it.
  If they were derived from any other project (including Boost and libc++,
  which are not yet listed in NOTICE.txt), you must mention it here,
  so we can determine whether the license is compatible and what else needs
  to be done.

[BillyONeal]

We wouldn't strengthen unconditionally, we would just make invoke call _C_invoke.

[barcharcraz]

I suppose, we'd also eliminate this macro and just expand it in the constexpr case right?

[StephanTLavavej]

There are throughput considerations here - std::function is throughput-sensitive and it uses invoke(). If invoke() were defined to call _C_invoke(), that would be an unnecessary layer of function calls.

I believe that the best thing to do would be to:

1. De-macroize this machinery,
2. Make the _Invoker layer unconditionally constexpr,
3. Make invoke() conditionally _CONSTEXPR20,
4. Change apply() and visit() to use the _Invoker layer.

[BillyONeal]

Make the _Invoker layer unconditionally constexpr

Can we do that without CWG-1581?

[barcharcraz]

I don't think this conversation is relevant to documenting what's there now right.

[StephanTLavavej]

This affects your comment "Now that a Core Language issue affecting constexpr std::invoke has been fixed (CWG-1581), we may make this unconditional and remove the macro (which violates the strengthening rule in C++14/17 mode). TRANSITION, P1065R2" which talks about the future.

[barcharcraz]

yeah it seems like we may be able to do this without CWG-1581...

[BillyONeal]

yeah it seems like we may be able to do this without CWG-1581

I disagree; getting incorrect behavior from invoke is exactly why CWG-1581 existed in the first place. It's possible that Stephan's implementation, which does not use expression SFINAE, is immune to that problem, but I don't understand this area well enough to make such a firm statement. See http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2018/p1065r0.html for more nitty gritty details.

[StephanTLavavej]

There are throughput considerations here - std::function is throughput-sensitive and it uses invoke(). If invoke() were defined to call _C_invoke(), that would be an unnecessary layer of function calls.

I believe that the best thing to do would be to:

1. De-macroize this machinery,
2. Make the _Invoker layer unconditionally constexpr,
3. Make invoke() conditionally _CONSTEXPR20,
4. Change apply() and visit() to use the _Invoker layer.