[Xcb] naming convention (finished)

[Jamey Sharp]

Carl has once again demonstrated why I'm very glad he's been keeping an
eye on my little project. :-)

On Wed, Sep 20, 2006 at 06:14:32AM -0700, Carl Worth wrote:
> As a quiz, which of the following inconsistencies in Xlib have logical
> basis? And which of those (if any) are of practical advantage for the
> user to have to keep in mind to use the API?

That's a great example, as I can't pass this quiz. ;-)

> 	Alloc vs. Create

I guess in the core protocol, the Create requests allocate memory that's
tied to an XID in the server, while the Alloc requests don't have XIDs?
But I don't see a logical extension of that rule into the other Xlib
functions that use the Alloc and Create names.

> 	Get vs. Query vs. Fetch

On quick inspection, it looks to me like Xlib's rule is roughly that
Query functions directly correspond to X protocol with similar names;
Fetch does a round-trip to the server but is utility code for e.g.
ICCCM; and Get functions mostly read state out of the Display structure
or other local objects.

> 	Free vs. Destroy vs Delete

I have the impression that Destroy calls are predominantly recursive,
doing potentially a lot of work to release resources, while Free and
Delete apply to simpler objects.

The middle example seems like a distinction that's almost useful: I'd
certainly like programmers to know when they're incurring a round trip.
I don't see much point in the others though.

> (Of course, I'll pardon XCB for maintaining any of these that are forced
> by the protocol---and I will delight in XCB fixing any of these that
> don't also exist in the protocol.)

There are some gotchas in the twenty hand-written functions of XCB's
public and extension APIs. Nine functions return pointers -- but four
require that the result be free()d, three require calling XCBDisconnect,
and two require the memory not to be freed by the client at all. The
latter two have their return types marked const, which may help, but has
its own challenges from time to time. There are also four pointers
passed by reference as out-parameters to three functions, which bugs me
but I don't see a way around those.

Meanwhile, of course, CreateWindow and AllocColor still are named with
different prefixes since that's what they're called in the protocol
specification.

> There's still a plan in place for applications to be able to migrate
> incrementally to XCB from Xlib, right?

Yes, Xlib/XCB is still supposed to fulfill that role.

> Imagine the confusion evident in a question such as "Why is it that we
> sometimes use XFlush and we sometimes use x_flush?"

Yeah: ouch. Clearly, xcb_ it is.

--Jamey
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.freedesktop.org/archives/xcb/attachments/20060922/97dbda4b/attachment.pgp