[Fwd: Re: [cairo] Missing const in cairo API ?]

[Carl Worth]

On Tue, 03 Oct 2006 22:04:49 +0200,Damien Carbonne wrote:
> I understand opaque as private. If this is correct, it is only related 
> to implementation hiding.

Yes, but as soon as the implementation is hidden, then all the utility
of a "const foo*" goes away, (as far as the compiler is concerned).

>  From the specification viewpoint, thinking of opaque/private types as 
> ADT, it is perfectly possible to define, in the contract (API), the 
> possible "user visible" effects that any function may have on the object.

Yes, I agree. But C doesn't help us much here, so I think we're better
to just explaining these kinds of things in the documentation, rather
than trying to use const for something other than it is defined to be.

> If I say that an object can not be modified by a function, it only means 
> that I tell the compiler that it can make the assumption that the result 
> of this function only depends on the values of its input parameters. 
> This assumption is still true if I use a cache.

It's not just caches though. There are also nested objects, (for
example cairo_t which contains a pointer to a cairo_surface_t). And
the definition of const doesn't affect this. For example, consider
this piece of code for which "gcc -W -Wextra" emits no warnings:

	struct inner { int val; };
	struct outer { struct inner *inner; };

	void
	modify_inner (const struct outer *outer)
	{
	    outer->inner->val = 42;
	}

That's basically the same case as cairo_t containing a pointer to a
cairo_surface_t. So, if you take a simple function such as cairo_fill,
obviously it's a function that's modifying things, (since it is
changing the results on the destination surface), but according to the
rules of const in C, we could legitimately use "const cairo_t*" in
that function. Now, clearly that would be useless.

We could invent a more restricted rule for applying const to fewer
functions than the compiler would let us get away with, but I would
regard that as an abusive overriding of that keyword, and would
instead just argue for getting this kind of information into the
documentation.

> If I try to create an Ada binding, it's because I find this library 
> quite interesting, useful and of quality.

I'm quite glad you do.

> But this may be insufficient. For example, it's not because current 
> implementation of cairo_status has no "user visible" side effect (as 
> defined before), that it will never have. Simply because there is no const.
> So my initial question was only about identification of those "user 
> visible" side effects.

As I said above, I don't think const is the right answer
here. Instead, all user-visible side effects should be clearly
described in the documentation (that's what the documentation is there
for). But if the documentation is not clear on any of these, then we
can improve it.

And any guarantee in the documentation about a function not modifying
an object is just as binding on future cairo development as would be
"const" in the parameter list.

From a quick scan of the functions in cairo.h here are the functions
that I see that accept a cairo_t* parameter and are guaranteed not to
modify it:

	cairo_in_stroke, cairo_in_fill, cairo_stroke_extents,
	cairo_fill_extents, cairo_clip_extents,
	cairo_copy_clip_rectangles, cairo_text_extents,
	cairo_glyph_extents, cairo_copy_path, cairo_copy_path_flat,
	cairo_status, and all functions matching cairo_get_*.

I could generate more such lists, but I hope the documentation is
clear on this already, (and if it's not, let's fix that).

> I agree that a compiler can hardly check an ADT contract when internal 
> pointers are used.
> Is it because such checks can be guaranteed with simple structures 
> (e.g., cairo_matrix, ...) that const is used with them ?

With simple structures, the user can declare objects as const and can
safely share the values, or even have the data stored in
non-modifiable locations, (such as string literals stored in the code
space).

So the const keyword has user-visible benefit where the user might
actually declare a const object.

-Carl
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/cairo/attachments/20061003/b8de29e1/attachment.pgp