Re: [Nbd] [PATCHv3] Docs: improve description of disconnection methods

[Wouter Verhelst <w@...112...>]

On Fri, Oct 14, 2016 at 12:59:54PM -0500, Eric Blake wrote:
> On 04/14/2016 03:12 PM, Alex Bligh wrote:
> 
> Sorry for reviving an old thread, but just a heads-up to implementors:
> 
> > Improve the documentation as per the mailing list discussion.
> > Here's what we decided (broadly).
> > 
> > * One side MAY drop the connection if the other end violates a
> >   MUST condition.
> ...
> > ---
> 
> > +
> > +On a server shutdown, the server SHOULD wait for inflight
> > +requests to be serviced prior to initiating a hard disconnect.
> > +A server MAY speed this process up by issuing error replies.
> > +The error value issued in respect of these requests and
> > +any subsequently received requests SHOULD be `ESHUTDOWN`.
> > +
> > +If the client receives an `ESHUTDOWN` error it MUST initiate
> > +a soft disconnect.
> > +
> 
> > @@ -960,6 +1057,7 @@ The following error values are defined:
> >  * `ENOSPC` (28), No space left on device.
> >  * `EOVERFLOW` (75), Value too large; SHOULD NOT be sent outside of the
> >    experimental `STRUCTURED_REPLY` extension; see below.
> > +* `ESHUTDOWN` (108), Server has been shut down.
> >  
> 
> Note that ESHUTDOWN, although present on both Linux and BSD, is not
> specified by POSIX, and is therefore not present on all platforms.  This
> should not matter to the protocol itself (we've hard-coded that an error
> value of 108 MEANS that the server is trying to shut down and will
> reject all further transmission requests from the client, regardless of
> whether either the server or the client actually has an ESHUTDOWN error,
> and regardless of whether a platform's ESHUTDOWN has the value of 108).
> But it CAN make for some interesting compilation scenarios if you are
> trying to port code to more than one platform, such as mingw.

Right. The direct mapping from nbd error codes to errno numbers is a
historical accident; it was decided to just use that because it seemed
easy to do before we noticed that errno numbers are actually not
portable.

> I don't think we have to change anything in the spec, so much as me
> posting this email just as a heads-up in case anyone else hits the
> problem (I just hit it in qemu while trying to add ESHUTDOWN support).

Right. The names in the spec just happen to correlate to the errno
numbers that they encounter, but it's really really not a problem if we
come up with an nbd errno number that doesn't map to a "standard" errno
number.

To put it otherwise: I hadn't even noticed that there actually is an
ESHUTDOWN ;-)

-- 
< ron> I mean, the main *practical* problem with C++, is there's like a dozen
       people in the world who think they really understand all of its rules,
       and pretty much all of them are just lying to themselves too.
 -- #debian-devel, OFTC, 2016-02-12