[Xcb] Reply Buffering Question

[Barton C Massey]

In message <20071120095515.GA22307 at suckless.org> you wrote:
> As C programmer I pretty much dislike the namespace
> concept, at least in C++ (in Java it seems acceptable to
> me, with Haskell I have no experience, so I can't argue
> about Haskell). The reason for this is quite simple. Due
> the fact that C does not support namespaces, the average C
> programmer is enforced to keep the amount of exported
> functions small and to think about the interface
> carefully. Hence, I believe no namespaces enforce simple
> and sane interfaces.  So the language limitation lead to
> an advantage in this regard.

I have to respectfully disagree here.  "You can write
Fortran in any language"; Microsoft and others were writing
horrific APIs with horrific names in C well before anybody
had ever heard of C++ or namespaces.  I want the tools to
manage documenting, architecting and cleaning up APIs; C
fails to give me these tools.  In fact, Pascal's tools were
far better.

I'm certainly not going to waste time defending C++; if you
want to see how *I* think namespaces should have looked in a
C-like language, hit http://nickle.org.  Those namespaces
work quite well for us.  Java's aren't quite as nice, but
are good enough to make it clear why it's hard for me to be
happy with C's lack of namespaces (and modules and static
scope and parametric polymorphism, but I digress).

> And if one really needs namespaces in C, there are ways to
> aim them in conjunction with some CPP macros, however I
> won't recommend that for the above reasons.

I won't recommend it for the same reason that I don't
recommend "#define BEGIN {" or "#define NULL 0".  It's an
interesting language, but it ain't C no more.  Anyhow, there
are some fundamental properties of good namespaces that this
approach can't provide, such as auto-import and sensible
error messages.

> Why not using x_ as prefix? Xlib uses X, so x is free. And
> it is implicit that XCB are C bindings, so I see no need
> to introduce the 'cb' in C source code.

Because when I chose the prefix, we were using camel case
instead of the current convention, so it would have been
totally ambiguous.  It's too late for another great
renaming, IMHO.  Besides, I think having a "brand name" on
there is not horrible marketing; everybody can see where
things come from that way.  Do we really want another thing
called "X"?

> iterator = xcb_input_list_input_devices_devices_iterator(reply);
> 
> This function name has several flaws, which have nothing
> todo with C limitations.
> 
> xcb_            -> I'm fine with this prefix, even if I'd recommend simply x_

> input_list_     -> is such verbosity really necessary? Lists are such a central
>                    concept in C structures, that they are omitted usually in
>                    type names.
> 
> input_devices_  -> I'm fine with this

You've mis-parsed it.  It's xcb_, then input_ because it's
part of the input extension, then list_input_devices (the
name of the request, as pulled from the Xinput
documentation).  If it was in a nested namespace

  xcb.input.list_input_devices

this confusion would never have arisen.  As an added bonus
the prefixes would normally be dropped because of imports.
Add on some reasonable ADT support (objects or otherwise),
and you end up with the quite reasonable-looking

  list_input_devices.devices_iterator

in a modern language.

> devices_iterator -> That's also very verbose.

Not really. We can construct an iterator for each kind of
aggregate in the reply record from a given request.
Omitting the fact that this function produces an iterator
seems unwise; omitting the fact that it iterates the devices
would mean a different naming convention for replies that
have more than one kind of thing they can iterate over,
which means that you'd have to guess or look up everytime
you tried to type a name.

In other words, the guiding principle is that one should be
able to *infer* the name of the routine they want to call
without reference to any documentation other than the
protocol spec.  I think these long names are about the best
we can do with this.

I've added a note on our philosophy of naming to the wiki,
BTW; I really should write this stuff down before it comes
up on this list, but I'm lazy.  Thanks for starting the
discussion.

> How about
> 
>   it = x_input_device_iterator(reply);
> 
> in this case.

The problem here is that the iterator for list_input_devices
(the part that disappeared) is actually constructed
differently than for other requests that also produce a
device list to iterate over.  So that's no good.

> I know that it might be hard to generate this function
> name from an XML spec, but it seems possible.

The problem isn't what we can generate; it's what we're
trying to do.  We're trying to be as simple and transparent
a C interface to the protocols as we possibly can.  In other
words, we want to *do no API design* (in core XCB---the
utilities are a different matter, and generally have names I
suspect you would like more.)  IMHO, occasional long names
(and the one you cite is a bit pathological, I think) are a
reasonable price to pay for this clarity and simplicity.

    Bart