Re: [boost] [afio] AFIO review postponed till Monday

Subject: Re: [boost] [afio] AFIO review postponed till Monday
From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2015-07-21 12:24:32

On 21 Jul 2015 at 8:30, Glen Fernandes wrote:

> Did the review start yesterday?

Short answer: Sadly I believe not. I was unhappy with the tutorial in 
the documentation.

Longer answer: I've been investing 40 hours per week after work into 
preparing for this review since C++ Now late May when Ahmed 
volunteered to manage the review in writing lightweight monadic 
future promise as AFIO needs to be refactored along the lines and 
rationale described at 
https://boostgsoc13.github.io/boost.afio/doc/html/afio/design.html.

Lightweight monads + future promise is finished in the sense of being 
close to feature complete and passing conformance and efficiency 
testing on all supported compilers. I spent last week mocking up the 
v1.4 AFIO API based on wrappers and shims atop the v1.3 engine as a 
prelude to rewriting the engine completely based on lightweight 
monads + future promise (that way the same unit test code is used for 
both old engine and new engine, and that eases my conformance testing 
considerably).

I finished the last of the new API shim code at 3am on Sunday night. 
I got the small code examples rewritten to use the new API, but the 
big tutorial code examples still use the old API (which is still in 
there, just hidden from the docs).

At 6am I gave up too exhausted to continue, and I asked Ahmed to give 
me his opinion on if what I had was ready for review or not. The big 
problem is what is the definition of a library being "finished" 
because if you take the strictest interpretation, AFIO will not be 
finished for another three to five years (I have a three year roadmap 
at 
https://boostgsoc13.github.io/boost.afio/doc/html/afio/release_notes.h
tml).

Most would then say, okay it's finished and ready for review when the 
API is stable, but AFIO can happily coexist with different versions 
of itself thanks to APIBind, indeed a full copy of the v1.3 engine 
ships in v1.4, and any code written to use the v1.3 engine will 
forever continue to work perfectly. This is because AFIO guarantees a 
hard versioned and bound ABI layer using PIMPL, so the AFIO DLL can 
deliver multiple ABI versions of itself in the same shared library 
binary.

Note that while the AFIO API pretends it is using lightweight future 
promises, it is in fact internally emulating the API it will have 
once the engine is rewritten to use those. I am estimating four 
months to do the rewrite and debug of the engine, and I usually 
underestimate.

I'd really prefer the peer review *before* I rewrite the engine as 
that is an enormous time saver for me as I can incorporate the 
feedback during the rewrite instead of having to refactor already 
written and debugged code, and then do the debugging again. For me 
debugging is running 24 hour soaks of the unit tests to find every 
last instability, so it's unavoidably time consuming.

I therefore think the minimum definition of a library being 
"finished" has to be when there is a coherent snapshot in time. This 
is why I am unhappy with the tutorial as it was written for a mix of 
the v1.2 and v1.3 engines, and whilst the tutorial code works 
perfectly in v1.4 I think it misleads the reader as to the current 
state of the API and library, specifically regarding the Concurrency 
TS where the v1.4 API is now aligned, but the tutorial presents 
non-aligned idioms and semantics from the < v1.4 era. So I really 
need to rewrite the tutorial completely with all new code examples 
using the new API and for one of the code examples, using the fancy 
new C++ 1z coroutines implementation in VS2015 RTM which just shipped 
as the current code example is nested callback hell, and coroutines 
just make that code so much nicer to understand.

I've decided to take this week away from AFIO to clear my mind as 
it's been a long old stretch from May till now, but will restart work 
on it on Saturday and continuing the following week. I just became 
unemployed last Friday, so I can unusually use daylight hours to do 
the work for once.

As for when the review might start, I guess it depends on when I'm 
not unhappy with what I intend to present and on Ahmed's schedule. 
Sorry for the delay everyone.

All that said, apart from the tutorial any early observations about 
anything within https://boostgsoc13.github.io/boost.afio/ are 
welcome.

Niall

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