[cairo] cairo 1.5.8 API Changes and bindings

[Behdad Esfahbod]

On Wed, 2008-01-30 at 15:53 -0500, Alp Toker wrote:
> Jonathon Jongsma wrote:
> > I had a brief chat with Behdad about this on IRC and he suggested to
> > bring it up on the mailing list.  As far as I know, most bindings do
> > not actually expose the cairo_status_t data type: the manual
> > recommends that bindings check status and throw an exception of the
> > appropriate type.  In this case, if bindings followed this advice,
> > they'd be throwing exceptions on cases that previously didn't throw
> > exceptions, which could potentially break existing applications.
> > Behdad suggested possibly adding something like has_current_point() to
> > work around this.  Anybody have any other thoughts about how to handle
> > this in bindings?
> 
> Agreed.
> 
> I believe the original proposal over a year ago was a boolean return 
> value. has_current_point() or cairo_path_is_empty() may be an even 
> better idea than either a boolean return or an error return.

Status return is better than boolean return because 1) we already have
CAIRO_STATUS_NO_CURRENT_POINT, and 2) it also returns the current error
if cr is in error state.  I agree that the latter is not quite useful.

> An error return isn't technically wrong, but it's likely to lead to 
> wrong interpretation in bindings.
> 
> For the C# Cairo binding, we would have to special case this error so it 
> doesn't raise an exception, since exceptions are intended for truly 
> exceptional conditions and carry some overhead that you don't want to 
> incur when simply checking for an empty path.

Calling get_current_point() without a current point is a real error.
Though I can see that then it would be useful to have a separate
has_current_point().  If going the has_current_point() way, we may even
to move get_current_point() return type back to void but make it put cr
into error status?  That would break Pango but I don't mind much.  I can
fix that.


> The benefit of has_current_point()/is_empty() over changing the return 
> type is that a newly added symbol is easier to document and support.

That's a true point.  But looking into future, other symbols that we
want to change to return status later are cairo_device_to_user() and
family.  That one will be a more "compatible" change though, because the
cases that they would return error are already setting cairo_t in error.
So no regression there.  But your "exceptions are expensive" doesn't
hold there.  It's the same as cairo_matrix_invert() which already
returns status.

One possible solution is to change the binding recommendation.  With the
"throw exception if object is in error state after every call" mode of
operation, something like cairo_get_current_point() can only return
NO_CURRENT_POINT() in the bindings (except for exceptional cases or
cases that you put the cairo_t in error state from C or something out of
your control happens in between...), in that case a binding may want to
bind that call to return a boolean for example, instead of throwing an
exception.

Now before someone points that, that would be a huge mistake because the
idiom for C would be:

  if (!cairo_get_current_point (cr, &x, &y)) {
    do something with x, y...
  }

where other languages will be:

  if (cr.get_current_point (&x, &y)) {
    do something with x, y...
  }

That is, the condition is negated.

Now one may argue that some bindings actually bind that function to
return (x,y) as return value, so no room for a status return anyway.
Then I guess just sticking back to throwing exceptions is fine.


> The build failure mode of a change in return value is somewhat subtle 
> compared to simply introducing cairo_path_is_empty().

So, donno.  cairo_path_is_empty() and cairo_has_current_point() are both
find and welcome additions (patch please!).  In that case I don't mind
making get_current_point() return void again.  Not sure if it should put
cairo_t into error mode.  That would just make it harder for user to use
that API.  Donno.  Carl, others?

-- 
behdad
http://behdad.org/

"Those who would give up Essential Liberty to purchase a little
 Temporary Safety, deserve neither Liberty nor Safety."
        -- Benjamin Franklin, 1759