Re: [boost] [outcome] On the design and documentation

Subject: Re: [boost] [outcome] On the design and documentation
From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2017-05-26 13:37:45

>> If you've already checked by hand, the compiler will elide the internal
>> check entirely.
> 
> That's quite a claim to make here. When looking at vector<T>::at, this
> is certainly not the case, unless compilers made significant
> improvements over the last few years.

I have spent a lot of time tuning the implementation of Outcome to be
optimiser friendly. I have also been looking at the disassembly of these
objects in use in real world code for over a year. Unless you do a
system call, a call to an extern function, or an atomic operation, the
optimiser does a really great job at converting sequences of (with the
if() hidden inside the outcome implementation):

if(has_value)
 something1(value());
else
 something2(error());
if(has_value)
 something3(value());
else
 something4(error());
if(has_value)
 something5(value());
else
 something6(error());

... into:

if(has_value)
{
 something1(value());
 something3(value());
 something5(value());
}
else
{
 something2(error());
 something4(error());
 something6(error());
}

So, I repeat my claim about eliding the internal check. The optimiser is
clever, if you don't give it cause not to eliminate code, it'll
eliminate code very effectively, especially clang 4.0+ and GCC 6.0+.

Besides, the checking of current state is not the expensive part, it's
usually free on an out-of-order CPU as compare and branch usually uses
non-busy execution ports whilst the CPU is stalled on memory. It's any
branch misprediction which costs real time, typically 20 cycles or so on
recent Intel chips.

As a general rule, jumps to addresses later than current are predicted
to not happen, so I intentionally placed the empty state value before
valued, errored and excepted. That causes branches to equally mispredict
for any of the valued, errored and excepted states, thus creating
predictable execution times by creating a 20 cycle stall for all states
but empty for when the state of an outcome is not deduced by the compiler.

So I have paid attention to this stuff. My choices may be disagreeable
to some or many, but it's not like they weren't thought through.

>>> When I open its "landing page", I get no idea about the following:
>>> - What is the purpose of the library?
>>> - Why/when should I use it?
>>
>> It quite literally tells you both on the landing page.
>> https://ned14.github.io/boost.outcome/index.html.
> 
> From an empirical study of a non representative group, it seems it is
> not as literal as you would like it to be.
> One thing is that the points I mentioned are not visually
> distinguishable at first sight, there are three paragraphs with lots of
> prose.
> 
> The first paragraph reads:
> "This is the Outcome library. It is a C++ 14 library intended to aid
> ultra-lightweight error handling in large C++ codebases, providing a
> more expressive and type safe alternative to integer error codes or enums."
> 
> Apart from the trigger word "ultra-lightweight", what the library
> actually does is at the very end in a long sentence.
> 
> The second:
> "Unlike alternative implementations, it works perfectly with exceptions
> and RTTI disabled and is thus suitable for
> low-latency/games/finance/SG14 users. One could view Outcome as a
> minimum overhead universal outcome transport mechanism for C++, hence
> being named "Outcome"."
> 
> This sentence starts with "Unlike alternative implementations", I don't
> even know what to expect from this library, at this point, I really
> don't care about the alternatives yet, speaking of which, which
> alternatives? The key feature you wanted to highlight here is probably
> "works with exceptions and RTTI disabled".
> 
> The next two paragraphs follow the same scheme.
> 
> So in a nutshell:
> 
> The Outcome library implements a set of types to be used for lightweight
> error transport.
> The main features include:
>  - Type safe alternative to integer or enum based error codes
>  - Works with exceptions and RTTI disabled
>  - Suitable for real-time and low latency applications
>  - Efficient implementation
>  - Rich set of different types to support different use cases
> 
> And then you can go on with everything else you want to say, possibly
> with links pointing into the documentation on where potential users are
> able to find more about the various topics you just advertised.
> (Just a braindump of mine, not claiming this is the ultimate solution.)

I used to have bullet points, but a previous round of Reddit and Boost
feedback reduced the landing page to what is currently there on the
basis of less information is more.

You may have missed that Andrzej has already volunteered to restructure
the landing page and intro into more bitesize chunks. You can track that
issue at https://github.com/ned14/boost.outcome/issues/41. I have
appended your notes to that issue. Thank you for the feedback.

Niall

-- 
ned Productions Limited Consulting
http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/