Niall Douglas wrote:

More importantly though, is that reference API documentation what people were looking for? With clauses for effects, requires, throws etc?

Yes, this is the style the C++ standard uses.

Do I need to write more detail for the APIs, or is what is there enough?

You could be more detailed in places. For example, "" Function template outcome::policy::throw_directly::narrow_value_check template <class Impl> static constexpr void narrow_value_check(Impl* self) noexcept; Performs a narrow check of state, used in the assume_value() functions "" You have to say what happens, that is, you're missing the Effects clause here. Another minor comment: noexcept(noexcept(value_type(std::forward<T>(t)))&&noexcept(error_type(std::forward<U>(u)))); This is usually written as noexcept(is_nothrow_constructible_v && is_nothrow_constructible_v); If you haven't, you could look at the C++ standard to get an idea of how it specifies things, for example here: http://eel.is/c++draft/tuple.tuple SmartPtr uses a similar style too, f.ex. here: http://www.boost.org/doc/libs/develop/libs/smart_ptr/doc/html/smart_ptr.html...

...

...

https://dedi4.nedprod.com/static/result-v2/doc_result.html

Niall, what does result represent?

On Wed, Jun 21, 2017 at 4:58 PM, Niall Douglas via Boost < boost@lists.boost.org> wrote:

On 22/06/2017 00:21, Peter Dimov via Boost wrote:

...

...

...

...

https://dedi4.nedprod.com/static/result-v2/doc_result.html

Niall, what does result represent?

Same as expected.

It's legal to return that failure occurred, but no information as to why. I see that as being possibly useful.

What's far more interesting is result. Yes expected is also legal too. Where things get mind bendy is that v2 result can return a T with additional info E, so you can quite legitimately have a result with both .has_value() and .has_error() returning true.

Wasn't this one of the issues people took with Noexcept, that since it works with any return type whatsoever, there is no clear invariant, and you could end up in a situation where you have a value and an error? (I actually agree with this criticism, but in my mind this is a small price to pay for not burdening return objects with transporting errors as well as values.)

Niall Douglas wrote:

The idea, since we no longer have variant storage, is to see if we'd like to implement

http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0262r0.html (except with the parameter order reversed).

I'm not particularly enthusiastic about status_value (and the argument given in the paper is unconvincing.) Neither am I thrilled by the idea of result (an optional) or result (something like a glorified pair.) result in its original form represented a very clear concept: the type of a function that must either return a value, or a reason for the lack of value. All of the above do not fit this concept and to me ring hollow. The fact that for outcome we may want to have both an EC and an exception_ptr does not necessarily mean that we need to give up on the Either( Value, Reason ). In outcome's case, the reason is just more elaborate.

2017-06-22 4:23 GMT+02:00 Niall Douglas via Boost :

On 22/06/2017 02:08, Peter Dimov via Boost wrote:

...

Niall Douglas wrote:

...

The idea, since we no longer have variant storage, is to see if we'd like to implement

http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0262r0.html (except with the parameter order reversed).

I'm not particularly enthusiastic about status_value (and the argument given in the paper is unconvincing.) Neither am I thrilled by the idea of result (an optional) or result (something like a glorified pair.)

I've fixed the problems you raised at https://dedi4.nedprod.com/static/result-v2/doc_result.html and moved the implementation stuff into a impl namespace so standardese will still show the docs for the composited types, but not be usable by end users.

...

result in its original form represented a very clear concept: the type of a function that must either return a value, or a reason for the lack of value. All of the above do not fit this concept and to me ring hollow.

Andrzej feels similarly to you.

But I don't think things are as bad as both of you feel. In v2 result you now can have:

1. Successful: T

2. Failure: EC

3. Successful + Status: T + EC

The reason I don't think this is a problem is because you can't accidentally return a wrong result in practice. Either you're using result to return Success + Status, or you're using result to return Success | Failure. It is very hard to accidentally write code which does the wrong thing here, almost certainly the type system would refuse to compile incorrect code.

You could say "if you do not like the state `has both value and error`, then don't create it", and this could be considered acceptable, but now that you have said you intend to change "error" into "status", you are affecting even this conservative usage. In the paper by Laurence Crowl, in the example with queue status: ``` Value queue::value_pop(); queue_op_status queue::wait_pop(Value&); ``` what he is describing is: pair Whereas what you provide (if I got it correctly) is: pair Which means I can get a value with no status. This still does not implement P0262. Regards, &rzej;

So result is either wearing a "status hat", or it is wearing a "failure hat". It cannot be both.

The only remaining objection now is that result<...> is named the same yet has different semantics depending on its S type. Yet error_code is also a status, it's just a *negative* status rather than a *positive* status.

I've pushed clarifying reference API docs regarding this trait separation of positive versus negative status types to https://dedi4.nedprod.com/static/result-v2/doc_result.html. I appreciate that this change is controversial. However, I am also minded that there is no point in Outcome v2 covering the identical ground as Expected, just less well. Outcome ought to be isomorphic to Expected, be strong at the areas Expected is weak at and so on. Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/

On 23/06/2017 00:00, Peter Dimov via Boost wrote:

Niall Douglas wrote:

...

I appreciate that this change is controversial. However, I am also minded that there is no point in Outcome v2 covering the identical ground as Expected, just less well.

Can't say I agree with that. Outcome should cover the ground that needs to be covered. Not cover useless ground that nobody needs covered (status) just to avoid the "expected" ground. If that makes result virtually identical to expected, so be it. This is just a sign that both you and Vicente have the basic design correct. You will still differentiate based on implementation quality, extra features of error_code_extended, and the added value that outcome brings to the party.

I appreciate this. However I am thinking here in terms of WG21 standardisation, specifically SG14's work on a std::vector upgrade which doesn't have the really unfortunate unpredictable latency. The general idea is that a low latency std::vector would never expand its capacity automatically, instead it would return success + capacity approaching warning status. You then could schedule the construction of a new, bigger vector outside the hot path. That's why Lawrence's Status + Value proposal garnered such interest, but there were concerns about whether an expected type solution like Outcome v1 would be a better approach instead, so the idea was that expected could be returned. I don't much care for that idea personally, but it has its fans. I am dropping the expected implementation from Outcome v2. That will lose me a ton of user base. I am minded to claw some of that back from elsewhere, perhaps solve some other pressing problems for SG14 around the Status + Value need. It costs me almost nothing in terms of implementation, so a bit like with empty state, I am minded to provide it opt-in. We'll see how it goes. Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/

...

However I am thinking here in terms of WG21 standardisation, specifically SG14's work on a std::vector upgrade which doesn't have the really unfortunate unpredictable latency. The general idea is that a low latency std::vector would never expand its capacity automatically, instead it would return success + capacity approaching warning status. You then could schedule the construction of a new, bigger vector outside the hot path.

I find this example as unconvincing as Lawrence's original one. For one, vector functions that grow the size typically return void. So you could just turn that into bool or an enum and you'd be done.

For another, when you're in the hot path, the "capacity warning" status is not actionable, so it's of little use. Instead, when you get out of the hot path (or, better yet, before you get into it), you'd simply check capacity(), see if it's yellow/red, and reserve. Or not even check, just reserve( size() + <hot path max size requirement> ).

All valid observations. Yet SG14 likes anything which relocates latency unpredictable things (exception throws, malloc, etc) to the caller. It's certainly how I'd have personally designed the STL originally. std::vector's latency insensitive design has always irritated me, and I still hope - without much basis - that any STL v2 will fix that. I'm minded to try and deliver SG14 a vocabulary type which can help with that so they can propose it for standardisation. As much as it'll cause problems with the Boost review, it delights SG14 members. I received quite a lot of private email during and after the Outcome v1 review about how from the review feedback on boost-dev it was clear here doesn't understand SG14's needs and priorities. I really wish they'd say that here instead of emailing me privately about it. I already know, it's a difference of mindset and philosophy. Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/

...

Yet SG14 likes anything which relocates latency unpredictable things (exception throws, malloc, etc) to the caller. It's certainly how I'd have personally designed the STL originally. std::vector's latency insensitive design has always irritated me, and I still hope - without much basis - that any STL v2 will fix that.

If there is anything wrong with std::vector that isn't it.

There is a significant minority who want their containers to never, ever allocate memory on their own. Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/

...

Yet SG14 likes anything which relocates latency unpredictable things (exception throws, malloc, etc) to the caller. It's certainly how I'd have personally designed the STL originally. std::vector's latency insensitive design has always irritated me, and I still hope - without much basis - that any STL v2 will fix that.

I'm minded to try and deliver SG14 a vocabulary type which can help with that so they can propose it for standardisation.

Do you have in mind some outline of how this SG14-friendly, status-based, vector would look like? A few signatures are fine, no need to list the whole synopsis, although it's not that much.

Ah, that's not my field. I've just been monitoring the work of others. And do remember I'm not on SG14, I can't afford to attend their meetings, same as WG21 meetings. Most, but not all, of their work can be found at https://github.com/WG21-SG14. I can tell you however what I'd personally prefer, though be aware the below is off the top of my head and not thought through. Personally speaking, I'd prefer all STL v2 containers to be exclusively made up of composed views of fixed-at-construction capacity vectors and fixed-at-compile-time arrays. So you might create: std2::vector<int> a(3); // not three items, but capacity for three items a.push_back(1); // returns result a.push_back(1); // returns success, capacity() - size() = 1 a.push_back(1); // returns success, capacity() - size() = 0 a.push_back(1); // returns failure, std::errc::not_enough_memory std2::vector<int> b(3); b.push_back(2); // returns success, capacity() - size() = 2 std2::span c(a, b); // compose c.size() == 4 c.push_back(2); // returns success, capacity() - size() = 1 c.size() == 5 c[0] == 1 c[3] == 2 c[4] == 2 std2::vector d(std::move(c)); // move contents into new storage And you'd keep going with the composing views up into associative maps etc, always being in direct manual control of any memory allocation at all times. std2::vector and std::array are the primitive containers, all other STL v2 containers are built on top in layers with reusable and generic views and spans. So you wouldn't really have an unordered_map container any more, you'd have a std2::mapping_view from a std::vector2 for the hash table onto a set of mapped items. You manually control buckets expansaion. That's the sort of design I'd personally prefer for STL v2 containers (remember no one is proposing to retire STL v1 containers, your std::vector<T> remains exactly as now). I appreciate it's not quite the Ranges TS and that's where things will actually end up at, but it's still very possible that SG14 will design their own low latency STL which doesn't repeat the latency unpredictability of the current STL or a Ranges TS based STL. We'll see. You probably have noted the lack of use of any positive status in any of the above. That's because the above is my personal preference, I'd personally speaking only see a wise use for positive status in insert operations on associative maps where a positive status indicates if a new key was inserted or if an existing value was replaced. But others have different opinions on all that, and as I mentioned my personal preference for STL v2 just described is not well thought through, so I defer to those who've done a lot more work on that. And they appear to want positive status more than I would personally see good reason for. Why I am not sure, because I don't know what they have planned for it. Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/

On 23 June 2017 at 03:25, Peter Dimov via Boost wrote:

For one, vector functions that grow the size typically return void. So you could just turn that into bool or an enum and you'd be done.

Maybe pop_back() could be made to return the popped element instead of void. degski -- "*Ihre sogenannte Religion wirkt bloß wie ein Opiat reizend, betäubend, Schmerzen aus Schwäche stillend.*" - Novalis 1798

degski wrote:

On 23 June 2017 at 03:25, Peter Dimov via Boost wrote:

...

For one, vector functions that grow the size typically return void. So you could just turn that into bool or an enum and you'd be done.

Maybe pop_back() could be made to return the popped element instead of void.

pop_back doesn't grow the size. It never needs to reallocate. As for why it doesn't return the element, because copying it may throw.

2017-06-22 23:09 GMT+02:00 Niall Douglas via Boost :

...

You could say "if you do not like the state `has both value and error`, then don't create it", and this could be considered acceptable, but now that you have said you intend to change "error" into "status", you are affecting even this conservative usage.

In the paper by Laurence Crowl, in the example with queue status:

``` Value queue::value_pop(); queue_op_status queue::wait_pop(Value&); ```

what he is describing is: pair

Whereas what you provide (if I got it correctly) is: pair

Which means I can get a value with no status. This still does not implement P0262.

In response to yours and Peter's concerns, I've now tightened the semantics considerably. For result you now may do:

1. Construct with a T. .value() returns that T. .status() throws bad_result_access. There is no .error().

2. Construct with a T and an S. .value() returns that T, .status() returns that S. There is no .error().

And that's it. If trait::enable_errored_result_creation<S> is true however, you get this instead:

1. Construct with a T. .value() returns that T. .error() throws bad_result_access. There is no .status().

2. Construct with an S. .value() throws that S according to policy. .error() returns that S. There is no .status().

So result is either wearing a "status hat", or it is wearing a "failure hat". It cannot be both.

The only remaining objection now is that result<...> is named the same yet has different semantics depending on its S type. Yet error_code is also a status, it's just a *negative* status rather than a *positive* status.

If you are determined to go this way, why not offer two separate templates: `annotated` and `result`. The former for the "status" functionality, the latter for the Outcome-v1-like "either T or error", and have them just share the same implementation. Since they have different semantics and member functions why have them share the same name? Regards, &rzej;

On Wed, Jun 21, 2017 at 7:23 PM, Niall Douglas via Boost < boost@lists.boost.org> wrote:

On 22/06/2017 02:08, Peter Dimov via Boost wrote:

...

Niall Douglas wrote:

...

The idea, since we no longer have variant storage, is to see if we'd like to implement

http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0262r0.html (except with the parameter order reversed).

I'm not particularly enthusiastic about status_value (and the argument given in the paper is unconvincing.) Neither am I thrilled by the idea of result (an optional) or result (something like a glorified pair.)

I've fixed the problems you raised at https://dedi4.nedprod.com/static/result-v2/doc_result.html and moved the implementation stuff into a impl namespace so standardese will still show the docs for the composited types, but not be usable by end users.

...

result in its original form represented a very clear concept: the type of a function that must either return a value, or a reason for the lack of value. All of the above do not fit this concept and to me ring hollow.

Andrzej feels similarly to you.

But I don't think things are as bad as both of you feel. In v2 result you now can have:

1. Successful: T

2. Failure: EC

3. Successful + Status: T + EC

The reason I don't think this is a problem is because you can't accidentally return a wrong result in practice. Either you're using result to return Success + Status

If I wanted to return Sucess + Status, I would return pair as the value (as opposed to the error) from a given function.

There is certainly more information now in the reference section than before. This is clearly an improvement. You probably want to conceal some of the types used for implementation from the docs, like those from namespace `impl`, but I understand this is just a prototype.

Namespace impl is purely due to current limitations in the standardese tool. It's supposed to be namespace detail.

One thing I want to suggest, is that the standardese used in the standard Library has problems of its own, that you have a chance of avoiding. For instance, as described here: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0411r0.html

the "Requires" clause mixes two things: (1) requirements that can be (and are) checked at compile-time (like DefaultConstructible), and (2) requirements on values that if not met cause UB (like `i < this->size()`). The linked paper proposes, and I encourage the same to use two different clauses:

Precondition: i < this->size(); Requires: is DefaultConstructible

And as some have suggested, even a third one that describes all the enable_if-s in the interface:

"Enabled_if: is_copyable_v<T>" instead of "Effects: this overload shall not participate in overload resolution unless is_copyable_v<T> is true".

Enhancement submitted to https://github.com/foonathan/standardese/issues/62 Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/